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