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_LineDescriptor_idl__
25#define __com_sun_star_inspection_LineDescriptor_idl__
26
27#ifndef com_sun_star_graphic_XGraphic_idl
28#include <com/sun/star/graphic/XGraphic.idl>
29#endif
30
31//=============================================================================
32module com {  module sun {  module star {  module inspection {
33
34published interface XPropertyControl;
35
36//-----------------------------------------------------------------------------
37/** describes the appearance of a line representing a single property in an <type>ObjectInspector</type>.
38
39    Such a line consists of
40    <ul><li>a label with a human-readable name for the property</li>
41        <li>a control which is used for user interaction - i.e. it displays the current property
42            value, and allows the user entering a new one.</li>
43        <li>(optional) one or two buttons which, when clicked, can start a more complex, interactive
44            property value input. For instance, if you have a property whose value is a path in the
45            file system, such a button could be used to let the user browse for a path with a
46            usual file picker.</li>
47    </ul>
48
49    @see XPropertyHandler::describePropertyLine
50    @see PropertyLineElement
51
52    @since OpenOffice 2.0.3
53*/
54published struct LineDescriptor
55{
56    /** denotes the human-readable display name used to present a property to the user
57    */
58    string  DisplayName;
59
60    /** denotes the control which should be used to represent the property at the UI.
61
62        @see XPropertyControlFactory
63    */
64    XPropertyControl Control;
65
66    /** specifies the URL to the help topic to be associated with the property
67    */
68    string HelpURL;
69
70    /** detetrmines whether a button exists which can be used for a more complex, interactive
71        property value input.
72
73        <p>If no image for the primary button is specified, but a primary button is present,
74        the three dots will be displayed on the button.</p>
75
76        @see XPropertyHandler::onInteractivePropertySelection
77        @see HasSecondaryButton
78        @see PrimaryButtonImageURL
79        @see PrimaryButtonImage
80    */
81    boolean HasPrimaryButton;
82
83    /** describes a unique id to associate with the primary button
84
85        <p>In OpenOffice.org, UI elements sometimes require a so-called UniqueID, which can be
86        used to uniquely (within the whole application) identify this UI element. For instance,
87        automating the OpenOffice.org UI via a dedicated separate application ("TestTool") requires
88        such IDs.</p>
89
90        <p>If a primary button exists for a property's UI representation (<member>HasPrimaryButton</member>),
91        it gets the ID specified herein.</p>
92    */
93    string PrimaryButtonId;
94
95    /** describes the URL of an image to display on the primary button, if any.
96
97        <p>This URL will be used to obtain an actual <type scope="com::sun::star::graphic">XGraphic</type>
98        object from an <type scope="com::sun::star::graphic">GraphicProvider</type>.</p>
99
100        <p>The property will be ignored if <member>HasPrimaryButton</member> is <FALSE/>.</p>
101
102        <p>If you need to specify a graphic which does not have an URL, but is available as
103        <type scope="com::sun::star::graphic">XGraphic</type> only, then you must leave
104        <code>PrimaryButtonImageURL</code> empty, and use the <member>PrimaryButtonImage</member> property.
105
106        @see PrimaryButtonImage
107    */
108    string  PrimaryButtonImageURL;
109
110    /** describes a graphics to display at the primary button, if any.
111
112        <p>The property will be ignored if <member>HasPrimaryButton</member> is <FALSE/>, or
113        if <member>PrimaryButtonImageURL</member> is a non-empty string.</p>
114
115        @see HasPrimaryButton
116        @see PrimaryButtonImageURL
117    */
118    com::sun::star::graphic::XGraphic PrimaryButtonImage;
119
120    /** detetrmines whether a secondary button exists which can be used for a more complex, interactive
121        property value input.
122
123        <p>A secondary button subordinated to the primary button. If no primary button exists
124        (<member>HasPrimaryButton</member>), this member is ignored.</p>
125
126        @see XPropertyHandler::onInteractivePropertySelection
127        @see HasSecondaryButton
128    */
129    boolean HasSecondaryButton;
130
131    /** describes a unique id to associate with the primary button
132
133        <p>If a secondary button exists for a property's UI representation (<member>HasSecondaryButton</member>),
134        it gets the ID specified herein.</p>
135
136        @see PrimaryButtonId
137    */
138    string SecondaryButtonId;
139
140    /** describes the URL of an image to display on the secondary button, if any.
141
142        <p>This URL will be used to obtain an actual <type scope="com::sun::star::graphic">XGraphic</type>
143        object from an <type scope="com::sun::star::graphic">GraphicProvider</type>.</p>
144
145        <p>The property will be ignored if <member>HasSecondaryButton</member> is <FALSE/>.</p>
146
147        <p>If you need to specify a graphic which does not have an URL, but is available as
148        <type scope="com::sun::star::graphic">XGraphic</type> only, then you must leave
149        <code>SecondaryButtonImageURL</code> empty, and use the <member>SecondaryButtonImage</member> property.
150
151        @see SecondaryButtonImage
152    */
153    string  SecondaryButtonImageURL;
154
155    /** describes a graphics to display at the secondary button, if any.
156
157        <p>The property will be ignored if <member>HasSecondaryButton</member> is <FALSE/>, or
158        if <member>SecondaryButtonImageURL</member> is a non-empty string.</p>
159
160        @see HasSecondaryButton
161        @see SecondaryButtonImageURL
162    */
163    com::sun::star::graphic::XGraphic SecondaryButtonImage;
164
165    /** describes the indent level for the property
166
167        <p>If a given property semantically depends on another one, the indent level
168        can be used to visually represent this fact. For this, the dependent property's
169        indent level would be one larger than the indent level of the other property.</p>
170
171        <p>Normally, <type>XPropertyHandler</type>s will set this to <code>0</code> when describing
172        the UI for a normal property.
173    */
174    short IndentLevel;
175
176    /** describes the category into which the property should be sorted by the <type>ObjectInspector</type>.
177
178        <p>An <type>ObjectInspector</type> can visually group properties which semantically belong
179        together (for instance using tab pages). The decision which properties actually belong together
180        is made using this <member>Category</member> attribute.</p>
181
182        <p>For your implementation of <type>XPropertyHandler</type>, it's recommended that you document the programmatic
183        names used for property categories. This way, your handler might be re-used in
184        different contexts, where only the <type>XObjectInspectorModel</type> needs to provide consistent
185        UI names for the categories.</p>
186
187        @see XObjectInspectorModel::describeCategories
188    */
189    string Category;
190};
191
192//=============================================================================
193
194}; }; }; };
195
196#endif
197
198