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

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XObjectInspectorModel.idl,v $
  10  * $Revision: 1.6 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef __com_sun_star_inspection_XObjectInspectorModel_idl__
  32 #define __com_sun_star_inspection_XObjectInspectorModel_idl__
  33
  34 #ifndef __com_sun_star_uno_XInterface_idl__
  35 #include <com/sun/star/uno/XInterface.idl>
  36 #endif
  37 #ifndef __com_sun_star_inspection_PropertyCategoryDescriptor_idl__
  38 #include <com/sun/star/inspection/PropertyCategoryDescriptor.idl>
  39 #endif
  40
  41 //=============================================================================
  42 module com {  module sun {  module star {  module inspection {
  43
  44 interface XPropertyHandler;
  45
  46 //-----------------------------------------------------------------------------
  47 /** describes the model of an <type>ObjectInspector</type>
  48
  49     @see ObjectInspector
  50
  51     @since OOo 2.0.3
  52 */
  53 interface XObjectInspectorModel
  54 {
  55     /** describes a set of factories for creating <type>XPropertyHandler</type>s
  56
  57         <p>Every element of the sequence must contain information to create a
  58         <type>XPropertyHandler</type> instance. Two ways are currently supported:
  59         <ul>
  60             <li>A sevice name:</br>
  61                 If a sequence element contains a string, this string is interpreted
  62                 as service name, and an <type scope="com::sun::star::lang">XMultiComponentFactory</type>
  63                 is asked to create an instance of this service.</li>
  64             <li>A factory:<br/>
  65                 If a sequence element contains an instance implementing the
  66                 <type scope="com::sun::star::lang">XSingleComponentFactory</type> interface, this factory
  67                 is used to create a property handler.</li>
  68         </ul></p>
  69
  70         <p>This attribute is usually only evaluated by the <type>ObjectInspector</type> instance
  71         which the model is currently bound to.</p>
  72
  73         <p>The order of factories is important: If two property handlers declare themself responsible
  74         for the same property, the one whose factory is listed <strong>last</strong> wins. Also,
  75         if a handler <code>B</code> wants to supersede a property of another handler <code>A</code>,
  76         <code>A</code>'s factory must precede the factory of <code>B</code>.</p>
  77
  78         @see XPropertyHandler::getSupportedProperties
  79         @see XPropertyHandler::getSupersededProperties
  80     */
  81     [attribute, readonly] sequence< any > HandlerFactories;
  82
  83     /** describes the property categories used by the property handlers.
  84
  85         <p>Properties can be sorted into different categories, described by the <member>LineDescriptor::Category</member>
  86         attribute, which is filled in <member>XPropertyHandler::describePropertyLine</member>
  87         method of your property handler.<br/>
  88         Those names provided by the handlers are programmatic names. All other information
  89         about categories is part of the <type>PropertyCategoryDescriptor</type>, and
  90         <member>describeCategories</member> assembles information about all categories which
  91         all property handlers provided by the model use.</p>
  92
  93         @return
  94             a sequence of category descriptors. Their relative ordering also describes
  95             the relative ordering of the categories in the <type>ObjectInspector</type>'s
  96             user interface.<br/>
  97             The sequence must not contain two entries with the same programmatic name.<br/>
  98             <br/>
  99             The model implementation might return an empty sequence here, in this case, the ObjectInspector
 100             automatically builds its category information from the categories provided by the
 101             property handlers.
 102         @see PropertyCategoryDescriptor
 103         @see LineDescriptor::Category
 104     */
 105     sequence< PropertyCategoryDescriptor > describeCategories();
 106
 107     /** retrieves an index in a global property ordering, for a given property name
 108
 109         <p>In the user interface of an ObjectInspector, single properties are represented by
 110         single lines, and those lines are displayed successively. To determine an order of
 111         the property lines, the inspector model can associate an "order index" with each property.
 112         The <type>ObjectInspector</type> will then sort the property lines in a way that they
 113         have the same relative ordering as the "order indexes" of their properties.</p>
 114
 115         <p>Note that the concrete value the model returns for a given property does not
 116         matter. All what matters is that if you want a certain property <code>Foo</code>
 117         to be displayed after another property <code>Bar</code>, then the order index
 118         of <code>Foo</code> should be greater than the order index of <code>Bar</code>.
 119
 120         <p>If for two different properties the same order index is returned, the
 121         <type>ObjectInspector</type> will assume the order in which those properties
 122         were provided by the respective property handler
 123         (<member>XPropertyHandler::getSupportedProperties</member>).<br/>
 124         If two such properties originate from different handlers, they will be ordered according
 125         to the order of the handlers, as provided in the <member>HandlerFactories</member> attribute.</p>
 126
 127         @param PropertyName
 128             the property whose global order index should be retrieved
 129         @return
 130             the global order index of <arg>PropertyName</arg>.
 131     */
 132     long    getPropertyOrderIndex( [in] string PropertyName );
 133
 134     /** indicates that the object inspector should have a help section.
 135
 136         <p>The object inspector displays lines of property/values, optionally grouped
 137         into categories, as described by the property handlers.<br/>
 138         Additionally, the inspector can optionally display a section dedicated to help
 139         texts. Clients could use this section to display context-sensitive help, for
 140         instance short texts explaining the currently selected property.</p>
 141
 142         @since OOo 2.2
 143     */
 144     [attribute, readonly] boolean HasHelpSection;
 145
 146     /** denotes the minimum number of lines of text to be reserved for the help
 147         section.
 148
 149         <p>This property is ignored by the <type>ObjectInspector</type> if
 150         <member>HasHelpSection</member> is <FALSE/>.</p>
 151
 152         <p>The layout of the <type>ObjectInspector</type> is undefined if
 153         <member>MinHelpTextLines</member> is larger than
 154         <member>MaxHelpTextLines</member>.</p>
 155
 156         @since OOo 2.2
 157     */
 158     [attribute, readonly] long MinHelpTextLines;
 159
 160     /** denotes the maximum number of lines of text to be reserved for the help
 161         section.
 162
 163         <p>This property is ignored by the <type>ObjectInspector</type> if
 164         <member>HasHelpSection</member> is <FALSE/>.</p>
 165
 166         <p>The layout of the <type>ObjectInspector</type> is undefined if
 167         <member>MaxHelpTextLines</member> is smaller than
 168         <member>MinHelpTextLines</member>.</p>
 169
 170         @since OOo 2.2
 171     */
 172     [attribute, readonly] long MaxHelpTextLines;
 173
 174     /** determines whether the object inspector's UI should be read-only.
 175
 176         <p>In this case, the user is able to browse through all properties, but cannot
 177         change any of them.</p>
 178
 179         <p>In a read-only object inspector, the property controls are readonly or
 180         disabled themself, and the primary and secondary buttons of a property line
 181         are both disabled.</p>
 182
 183         @see XPropertyControl
 184         @see LineDescriptor
 185     */
 186     [attribute, bound] boolean IsReadOnly;
 187 };
 188
 189 //=============================================================================
 190
 191 }; }; }; };
 192
 193 #endif
 194
 195