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