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#ifndef __com_sun_star_inspection_XObjectInspectorUI_idl__
24#define __com_sun_star_inspection_XObjectInspectorUI_idl__
25
26#ifndef __com_sun_star_inspection_XPropertyControl_idl__
27#include <com/sun/star/inspection/XPropertyControl.idl>
28#endif
29#ifndef __com_sun_star_beans_Optional_idl__
30#include <com/sun/star/beans/Optional.idl>
31#endif
32#ifndef __com_sun_star_container_NoSuchElementException_idl__
33#include <com/sun/star/container/NoSuchElementException.idl>
34#endif
35#ifndef __com_sun_star_lang_NoSupportException_idl__
36#include <com/sun/star/lang/NoSupportException.idl>
37#endif
38
39//=============================================================================
40module com {  module sun {  module star {  module inspection {
41
42published interface XPropertyControlObserver;
43
44//-----------------------------------------------------------------------------
45/** grants access to certain aspects of the user interface of an object
46    inspector
47
48    <p>This interface is used as callback for <type>XPropertyHandler</type>s.</p>
49
50    <p>As a consequence, methods operating on the UI for a property, and taking the name of this property,
51    are tolerant against properties which do not exist. For instance, if a property handler tries to
52    disable the UI for property <code>Foo</code>, but another handler has superseded this property, then
53    the <type>ObjectInspector</type> will not <em>have</em> any UI for it. In this case, the call to
54    <code>enablePropertyUI( "Foo" )</code> will simply be ignored.</p>
55
56    @since OOo 2.0.3
57*/
58published interface XObjectInspectorUI
59{
60    /** enables or disables all components belonging to the UI representation of a property
61
62        <p>This is usually used by an <type>XPropertyHandler</type> if it handles properties,
63        where one does only make sense if another one has a certain value.</p>
64
65        @param  PropertyName
66            denotes the name of the property whose UI is to be enabled or disabled.
67        @param  Enable
68            <TRUE/> if and only if the UI should be disabled, <FALSE/> otherwise.
69    */
70    void    enablePropertyUI( [in] string PropertyName, [in] boolean Enable );
71
72    /** enables or disables the single elements which can be part of the UI representation of a property
73
74        <p>Note that the complete UI for the property must be enabled in order for these settings to
75        be evaluated. That is, <member>enablePropertyUIElements</member> does not have any effect if
76        somebody previously disabled the complete UI for this property with <member>enablePropertyUI</member>.</p>
77
78        @param  PropertyName
79            the name of the property whose user interface elements are to be enabled or disabled
80
81        @param  Elements
82            a combination of <type>PropertyLineElement</type> flags specifying which elements are to be
83            enabled or disabled.<br/>
84            Note that if you don't set a particular bit here (say, <member>PropertyLineElement::PrimaryButton</member>),
85            this does mean that this element's state is not affected by the call - it does
86            <em>not</em> mean that it is disabled.
87        @param  Enable
88            <TRUE/> if the elements denoted by <arg>_nElements</arg> should be enabled, <FALSE/> if
89            they should be disabled.
90    */
91    void    enablePropertyUIElements(
92                        [in] string PropertyName,
93                        [in] short Elements,
94                        [in] boolean Enable
95                    );
96
97    /** completely rebuilds the UI for the given property.
98
99        <p>This method might be used by an <type>XPropertyHandler</type> if it wants to change the type
100        of control (see <type>PropertyControlType</type>) used to display a certain property.</p>
101
102        <p>The object inspector will then call describePropertyLine again, and update its UI accordingly.</p>
103
104        <p>Note that the property whose UI should be rebuilt must not necessarily be (though usually <em>is</em>)
105        in the responsibility of the handler which calls this method. The object inspector will look up the
106        handler with the responsibility for <arg>PropertyName</arg> and call its
107        <member>XPropertyHandler::describePropertyLine</member></p>
108
109        @param PropertyName
110            the name of the property whose UI is to be completely rebuilt.
111    */
112    void    rebuildPropertyUI( [in] string PropertyName );
113
114    /** shows the UI for a given property
115
116        @param  PropertyName
117            the name of the property whose UI is to be shown
118    */
119    void    showPropertyUI( [in] string PropertyName );
120
121    /** hides the UI for a given property
122
123        @param  PropertyName
124            the name of the property whose UI is to be hidden
125    */
126    void    hidePropertyUI( [in] string PropertyName );
127
128    /** shows or hides all properties belonging to a given category
129        @see LineDescriptor::Category
130        @see XObjectInspectorModel::describeCategories
131    */
132    void    showCategory( [in] string Category, [in] boolean Show );
133
134    /** retrieves the control currently used to display a given property
135
136        @param PropertyName
137            the name of the property whose control should be retrieved
138
139        @return
140            the <type>XPropertyControl</type> representing the given property, or <NULL/>
141            if there is no such property control.
142    */
143    XPropertyControl
144            getPropertyControl( [in] string PropertyName );
145
146    /** registers an observer for all property controls
147
148        <p>The given XPropertyControlObserver will be notified of all changes
149        in all property controls.</p>
150
151        @see revokeControlObserver
152
153        @since OOo 2.2
154    */
155    void    registerControlObserver( [in] XPropertyControlObserver Observer );
156
157    /** revokes a previously registered control observer
158
159        @see registerControlObserver
160
161        @since OOo 2.2
162    */
163    void    revokeControlObserver( [in] XPropertyControlObserver Observer );
164
165    /** sets the text of the help section, if the object inspector contains
166        one.
167
168        @throws NoSupportException
169            if the <member>XObjectInspectorModel::HasHelpSection</member> property
170            requires the help section to be unavailable.
171
172        @since OOo 2.2
173    */
174    void setHelpSectionText( [in] string HelpText )
175        raises ( ::com::sun::star::lang::NoSupportException );
176};
177
178//=============================================================================
179
180}; }; }; };
181
182#endif
183
184