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