offapi/com/sun/star/inspection/XObjectInspectorModel.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef __com_sun_star_inspection_XObjectInspectorModel_idl__
  21 #define __com_sun_star_inspection_XObjectInspectorModel_idl__
  22
  23 #include <com/sun/star/uno/XInterface.idl>
  24 #include <com/sun/star/inspection/PropertyCategoryDescriptor.idl>
  25
  26 module com {  module sun {  module star {  module inspection {
  27
  28 interface XPropertyHandler;
  29
  30 /** describes the model of an ObjectInspector
  31
  32     @see ObjectInspector
  33
  34     @since OOo 2.0.3
  35 */
  36 interface XObjectInspectorModel
  37 {
  38     /** describes a set of factories for creating XPropertyHandlers
  39
  40         <p>Every element of the sequence must contain information to create a
  41         XPropertyHandler instance. Two ways are currently supported:
  42         <ul>
  43             <li>A service name:<br>
  44                 If a sequence element contains a string, this string is interpreted
  45                 as service name, and an com::sun::star::lang::XMultiComponentFactory
  46                 is asked to create an instance of this service.</li>
  47             <li>A factory:<br>
  48                 If a sequence element contains an instance implementing the
  49                 com::sun::star::lang::XSingleComponentFactory interface, this factory
  50                 is used to create a property handler.</li>
  51         </ul></p>
  52
  53         <p>This attribute is usually only evaluated by the ObjectInspector instance
  54         which the model is currently bound to.</p>
  55
  56         <p>The order of factories is important: If two property handlers declare themselves responsible
  57         for the same property, the one whose factory is listed <strong>last</strong> wins. Also,
  58         if a handler <code>B</code> wants to supersede a property of another handler <code>A</code>,
  59         <code>A</code>'s factory must precede the factory of <code>B</code>.</p>
  60
  61         @see XPropertyHandler::getSupportedProperties
  62         @see XPropertyHandler::getSupersededProperties
  63     */
  64     [attribute, readonly] sequence< any > HandlerFactories;
  65
  66     /** describes the property categories used by the property handlers.
  67
  68         <p>Properties can be sorted into different categories, described by the LineDescriptor::Category
  69         attribute, which is filled in XPropertyHandler::describePropertyLine()
  70         method of your property handler.<br>
  71         Those names provided by the handlers are programmatic names. All other information
  72         about categories is part of the PropertyCategoryDescriptor, and
  73         describeCategories() assembles information about all categories which
  74         all property handlers provided by the model use.</p>
  75
  76         @return
  77             a sequence of category descriptors. Their relative ordering also describes
  78             the relative ordering of the categories in the ObjectInspector's
  79             user interface.<br>
  80             The sequence must not contain two entries with the same programmatic name.<br>
  81             <br>
  82             The model implementation might return an empty sequence here, in this case, the ObjectInspector
  83             automatically builds its category information from the categories provided by the
  84             property handlers.
  85         @see PropertyCategoryDescriptor
  86         @see LineDescriptor::Category
  87     */
  88     sequence< PropertyCategoryDescriptor > describeCategories();
  89
  90     /** retrieves an index in a global property ordering, for a given property name
  91
  92         <p>In the user interface of an ObjectInspector, single properties are represented by
  93         single lines, and those lines are displayed successively. To determine an order of
  94         the property lines, the inspector model can associate an "order index" with each property.
  95         The ObjectInspector will then sort the property lines in a way that they
  96         have the same relative ordering as the "order indexes" of their properties.</p>
  97
  98         <p>Note that the concrete value the model returns for a given property does not
  99         matter. All what matters is that if you want a certain property <code>Foo</code>
 100         to be displayed after another property <code>Bar</code>, then the order index
 101         of <code>Foo</code> should be greater than the order index of <code>Bar</code>.
 102
 103         <p>If for two different properties the same order index is returned, the
 104         ObjectInspector will assume the order in which those properties
 105         were provided by the respective property handler
 106         (XPropertyHandler::getSupportedProperties()).<br>
 107         If two such properties originate from different handlers, they will be ordered according
 108         to the order of the handlers, as provided in the #HandlerFactories attribute.</p>
 109
 110         @param PropertyName
 111             the property whose global order index should be retrieved
 112         @return
 113             the global order index of PropertyName.
 114     */
 115     long    getPropertyOrderIndex( [in] string PropertyName );
 116
 117     /** indicates that the object inspector should have a help section.
 118
 119         <p>The object inspector displays lines of property/values, optionally grouped
 120         into categories, as described by the property handlers.<br>
 121         Additionally, the inspector can optionally display a section dedicated to help
 122         texts. Clients could use this section to display context-sensitive help, for
 123         instance short texts explaining the currently selected property.</p>
 124
 125         @since OOo 2.2
 126     */
 127     [attribute, readonly] boolean HasHelpSection;
 128
 129     /** denotes the minimum number of lines of text to be reserved for the help
 130         section.
 131
 132         <p>This property is ignored by the ObjectInspector if
 133         #HasHelpSection is `FALSE`.</p>
 134
 135         <p>The layout of the ObjectInspector is undefined if
 136         #MinHelpTextLines is larger than
 137         #MaxHelpTextLines.</p>
 138
 139         @since OOo 2.2
 140     */
 141     [attribute, readonly] long MinHelpTextLines;
 142
 143     /** denotes the maximum number of lines of text to be reserved for the help
 144         section.
 145
 146         <p>This property is ignored by the ObjectInspector if
 147         #HasHelpSection is `FALSE`.</p>
 148
 149         <p>The layout of the ObjectInspector is undefined if
 150         #MaxHelpTextLines is smaller than
 151         #MinHelpTextLines.</p>
 152
 153         @since OOo 2.2
 154     */
 155     [attribute, readonly] long MaxHelpTextLines;
 156
 157     /** determines whether the object inspector's UI should be read-only.
 158
 159         <p>In this case, the user is able to browse through all properties, but cannot
 160         change any of them.</p>
 161
 162         <p>In a read-only object inspector, the property controls are readonly or
 163         disabled themselves, and the primary and secondary buttons of a property line
 164         are both disabled.</p>
 165
 166         @see XPropertyControl
 167         @see LineDescriptor
 168     */
 169     [attribute, bound] boolean IsReadOnly;
 170 };
 171
 172
 173 }; }; }; };
 174
 175 #endif
 176
 177
 178 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */