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_XPropertyHandler_idl__
24#define __com_sun_star_inspection_XPropertyHandler_idl__
25
26#ifndef __com_sun_star_beans_PropertyState_idl__
27#include <com/sun/star/beans/PropertyState.idl>
28#endif
29#ifndef __com_sun_star_beans_Property_idl__
30#include <com/sun/star/beans/Property.idl>
31#endif
32#ifndef __com_sun_star_beans_XPropertyChangeListener_idl__
33#include <com/sun/star/beans/XPropertyChangeListener.idl>
34#endif
35#ifndef __com_sun_star_inspection_LineDescriptor_idl__
36#include <com/sun/star/inspection/LineDescriptor.idl>
37#endif
38#ifndef __com_sun_star_lang_NullPointerException_idl__
39#include <com/sun/star/lang/NullPointerException.idl>
40#endif
41#ifndef __com_sun_star_beans_UnknownPropertyException_idl__
42#include <com/sun/star/beans/UnknownPropertyException.idl>
43#endif
44#ifndef __com_sun_star_lang_XComponent_idl__
45#include <com/sun/star/lang/XComponent.idl>
46#endif
47#ifndef __com_sun_star_inspection_InteractiveSelectionResult_idl__
48#include <com/sun/star/inspection/InteractiveSelectionResult.idl>
49#endif
50
51//=============================================================================
52module com {  module sun {  module star {  module inspection {
53
54published interface XObjectInspectorUI;
55published interface XPropertyControlFactory;
56
57//-----------------------------------------------------------------------------
58/** is the basic interface for object inspection.
59
60    <p>The <type>ObjectInspector</type> itself does not know anything about the object
61    it is inspecting, all information is obtained via <type>XPropertyHandler</type>s.
62    Also, property handlers are responsible for describing the user interface which should
63    be used to interact with the user, with respect to a given aspect of the inspected
64    component.</p>
65
66    @see ObjectInspector
67    @see LineDescriptor
68
69    @since OpenOffice 2.0.3
70*/
71published interface XPropertyHandler
72{
73    /** used for controlling resources acquired by the handler
74
75        <p><member scope="com::sun::star::lang">XComponent::dispose</member> is invoked when the property handler is not
76        needed by the object inspector anymore. Handler implementations should clean up any
77        resources here.</p>
78    */
79    interface com::sun::star::lang::XComponent;
80
81    /** binds the property handler to a new component
82        @param Component
83            the component to inspect. Must not be <NULL/>
84        @throws com::sun::star::lang::NullPointerException
85            if the component is <NULL/>
86    */
87    void inspect( [in] com::sun::star::uno::XInterface Component )
88        raises( com::sun::star::lang::NullPointerException );
89
90    /** retrieves the current value of a property
91        @param PropertyName
92            the name of the property whose value is to be retrieved
93        @throws com::sun::star::beans::UnknownPropertyException
94            if the given property is not supported by the property handler
95    */
96    any
97        getPropertyValue( [in] string PropertyName )
98        raises (::com::sun::star::beans::UnknownPropertyException);
99
100    /** sets the value of a property
101
102        @param  PropertyName
103            the name of the property whose value is to be set
104        @param  Value
105            the property value to set
106        @throws com::sun::star::beans::UnknownPropertyException
107            if the given property is not supported by the property handler
108    */
109    void
110        setPropertyValue( [in] string PropertyName, [in] any Value )
111        raises (::com::sun::star::beans::UnknownPropertyException);
112
113    /** returns the state of a property
114
115        @param  PropertyName
116            the name of the property whose state is to be retrieved
117        @throws com::sun::star::beans::UnknownPropertyException
118            if the given property is not supported by the property handler
119    */
120    com::sun::star::beans::PropertyState
121        getPropertyState( [in] string PropertyName )
122        raises (::com::sun::star::beans::UnknownPropertyException);
123
124    /** describes the UI to be used to represent the property
125        @param PropertyName
126            the name of the property whose user interface is to be described
127            implementation
128        @param ControlFactory
129            a factory for creating <type>XPropertyControl</type> instances. Must not be <NULL/>.
130        @return
131            the descriptor of the property line.
132        @throws com::sun::star::beans::UnknownPropertyException
133            if the given property is not supported by this handler
134        @throws com::sun::star::lang::NullPointerException
135            if <arg>ControlFactory</arg> is <NULL/>.
136        @see PropertyControlType
137        @see LineDescriptor
138    */
139    LineDescriptor
140        describePropertyLine(
141            [in] string PropertyName,
142            [in] XPropertyControlFactory ControlFactory
143        )
144        raises (::com::sun::star::beans::UnknownPropertyException, ::com::sun::star::lang::NullPointerException);
145
146    /** converts a given control-compatible value to a property value
147
148        <p>In <member>describePropertyLine</member>, a property handler declared which type of control
149        should be used to display the value of a certain property. To allow to use the same control
150        type for different properties, and in particular, for properties of different type,
151        conversions between controls values and property values are needed.</p>
152
153        <p>This method converts a control value into a property value, which subsequently can be used
154        in conjunction with <member>setPropertyValue</member>.</p>
155
156        @param PropertyName
157            The name of the conversion's target property.
158        @param ControlValue
159            The to-be-converted control value. This value has been obtained from an <type>XPropertyControl</type>,
160            using its <member>Value</member> attribute.
161
162        @throws com::sun::star::beans::UnknownPropertyException
163            if the given property is not supported by the property handler
164
165        @see convertToControlValue
166        @see describePropertyLine
167        @see XPropertyControl
168        @see getPropertyValue
169    */
170    any
171        convertToPropertyValue(
172            [in] string PropertyName,
173            [in] any ControlValue
174        )
175        raises (::com::sun::star::beans::UnknownPropertyException);
176
177    /** converts a given property value to a control-compatible value
178
179        <p>In <member>describePropertyLine</member>, a property handler declared which type of control
180        should be used to display the value of a certain property. To allow to use the same control
181        type for different properties, and in particular, for properties of different type,
182        conversions between controls values and property values are needed.</p>
183
184        <p>This method converts a property value, which has previously been obtained using
185        <member>getPropertyValue</member>, into a control-compatible value, which can be used
186        with <type>XPropertyControl</type>'s <member>XPropertyControl::Value</member> attribute.</p>
187
188        <p>A usual application of this method are list boxes: There is a generic list box implementation,
189        which is able to display a simple list of strings. Usually, every string represents one
190        possible property value. To translate between those property values and the displayed strings,
191        <member>convertToControlValue</member> and <member>convertToPropertyValue</member> are used.</p>
192
193        <p>The method is not invoked if the control's value type (<member>XPropertyControl::ValueType</member>
194        equals the property's value type.</p>
195
196        @param PropertyName
197            The name of the property whose value is to be converted.
198        @param PropertyValue
199            The to-be-converted property value.
200        @param ControlValueType
201            The target type of the conversion. This type is determined by the control which
202            is used to display the property, which in turn is determined by the handler itself
203            in <member>describePropertyLine</member>.<br/>
204            Speaking strictly, this is passed for convenience only, since every <type>XPropertyHandler</type>
205            implementation should know exactly which type to expect, since it implicitly determined this type
206            in <member>describePropertyLine</member> by creating an appropriate <type>XPropertyControl</type>.
207
208        @throws com::sun::star::beans::UnknownPropertyException
209            if the given property is not supported by the property handler
210
211        @see convertToPropertyValue
212        @see describePropertyLine
213        @see XPropertyControl
214        @see getPropertyValue
215    */
216    any
217        convertToControlValue(
218            [in] string PropertyName,
219            [in] any PropertyValue,
220            [in] type ControlValueType
221        )
222        raises (::com::sun::star::beans::UnknownPropertyException);
223
224    /** registers a listener for notification about property value changes
225
226        <p>An <type>XPropertyHandler</type> implementation might decide to ignore this call.
227        However, in this case property value changes made by third party components are not
228        reflected in the object inspector.</p>
229
230        <p>If a handler implementation supports property change listeners, it must be able to cope
231        with a call to <member>addPropertyChangeListener</member> even if currently no component is
232        being inspected. In this case, the listener must become active as soon as a new introspectee
233        is set in the next <member>inspect</member> call.</p>
234
235        @param Listener
236            the listener to notify about property changes
237        @throws com::sun::star::lang::NullPointerException
238            if the listener is <NULL/>
239        @see removePropertyChangeListener
240    */
241    void
242        addPropertyChangeListener( [in] com::sun::star::beans::XPropertyChangeListener Listener )
243            raises ( com::sun::star::lang::NullPointerException );
244
245    /** revokes a listener for notification about property value changes
246        @see addPropertyChangeListener
247    */
248    void
249        removePropertyChangeListener( [in] com::sun::star::beans::XPropertyChangeListener Listener );
250
251    /** returns the properties which the handler can handle
252
253        <p>A handler is allowed to return an empty sequence here, indicating that for
254        the given introspectee, no properties handling can be provided. This might happen
255        when a fixed set of property handlers is used for a variety of components to inspect,
256        where not all handlers can really cope with all components.</p>
257
258        <p>In the case of returning an empty sequence here, the property handler is ignored
259        by all further processing in the object inspector.</p>
260    */
261    sequence< com::sun::star::beans::Property >
262        getSupportedProperties();
263
264    /** returns the properties which are to be superseded by this handler
265
266        <p>Besides defining an own set of properties (see <member>getSupportedProperties</member>),
267        a property handler can also declare that foreign properties (which it is
268        <em>not</em> responsible for) are superseded by its own properties.</p>
269
270        <p>This is usually used if your handler is used with another, more generic one, which
271        should continue to be responsible for all properties, except a few which your
272        handler handles more elegantly.</p>
273
274        <p>In such a case, simply return those properties here.</p>
275
276        <p>There is a precedence in the property handlers used by an <type>ObjectInspector</type>,
277        which also is important for the superseded properties. This precendence is implied by the
278        precendence of factories to create the property handlers, as denoted in the
279        <member>XObjectInspectorModel::HandlerFactories</member> attribute.</p>
280
281        <p>With this in mind, property handlers can only supersede properties which are supported
282        by a handler preceding them, but not properties of handlers succeeding them.</p>
283
284        <p>For instance, imaging an <type>XObjectInspectorModel</type> which provides three
285        factories, for handler <code>A</code>, <code>B</code>, and <code>C</code> - in this order.
286        Now if <code>A</code> supports the property <code>Foo</code>, <code>C</code> supports
287        <code>Bar</code>, and <code>B</code> supersedes both <code>Foo</code> and <code>Bar</code>,
288        them the result is <code>Bar</code> is still present. This is because <code>B</code> precedes
289        <code>C</code>, so it cannot, by definition, supersede properties which are supported by
290        <code>C</code>.</p>
291
292        <p>If <member>getSupportedProperties</member> returned an empty sequence, this method will
293        not be called.</p>
294
295        @see XObjectInspectorModel::HandlerFactories
296    */
297    sequence< string >
298        getSupersededProperties( );
299
300    /** retrieve the actuating properties which this handler is interested in
301
302        <p>In general, properties can be declared as "actuating", that is, when their value
303        changes, the UI for other properties needs to be updated (e.g. enabled or disabled).</p>
304
305        <p>With this method, a handler can declare that it feels responsible for some/all
306        of the depending properties of certain actuating properties.</p>
307
308        <p>Whenever the value of an actuating property changes, all handlers which expressed
309        their interest in this particular actuating properties are called with their
310        <member>actuatingPropertyChanged</member> method.</p>
311
312        <p>If <member>getSupportedProperties</member> returned an empty sequence, this method will
313        not be called</p>
314    */
315    sequence< string >
316        getActuatingProperties( );
317
318    /** determines whether a given property, which the handler is responsible for, is composable.
319
320        <p>An object inspector can inspect multiple components at once, displaying the <em>intersection</em>
321        of their properties. For this, all components are examined for their properties, and all properties
322        which exist for all components, <em>and</em> are declared to be composable by their respective handler,
323        are displayed in the inspector UI.</p>
324
325        @param PropertyName
326            the name of the property whose composability is to be determined
327        @throws com::sun::star::beans::UnknownPropertyException
328            if the given property is not supported by the property handler
329    */
330    boolean isComposable( [in] string PropertyName )
331        raises (::com::sun::star::beans::UnknownPropertyException);
332
333    /** called when a browse button belonging to a property UI represenation has been clicked
334
335        <p>Property handlers can raise a dedicated UI for entering or somehow changing a property value.
336        Usually, this will be a modal dialog, but it can also be a non-modal user interface component.</p>
337
338        <p>Availability of this feature is indicated by the <member>LineDescriptor::HasPrimaryButton</member>
339        and <member>LineDescriptor::HasSecondaryButton</member> members of a <type>LineDescriptor</type>,
340        which the <type>XPropertyHandler</type> fills in its <member>describePropertyLine</member> method.</p>
341
342        <p>When this method is called, the property handler should raise the UI needed to enter the
343        property value, and return the result of this (see <type>InteractiveSelectionResult</type>).</p>
344
345        <p>It is recommended that property handlers do not directly set the property value which has
346        been obatined from the user, but store it in the output-parameter Data, and return
347        <member>InteractiveSelectionResult::ObtainedValue</member>.</p>
348
349        <p>If a handler sets the new property value directly, and returns
350        <member>InteractiveSelectionResult::ObtainedValue</member>, this implies that the property
351        cannot properly be handled in case the object inspector is inspecting an intersection of
352        multiple components, since in this case <member>onInteractivePropertySelection</member>
353        will be called at one handler only, however the new property would have to be forwarded to
354        all handlers.</p>
355
356        <p>If a property is not composeable, directly setting the new property value does not yield any problem,
357        as long as property listeners are properly notified of the change.</p>
358
359        @param PropertyName
360            The name of the property whose browse button has been clicked
361
362        @param Primary
363            <TRUE/> if and only if the primary button has been clicked, <FALSE/> otherwise
364
365        @param out_Data
366            If the method returns <member>InteractiveSelectionResult::ObtainedValue</member>,
367            then <arg>out_Data</arg> contains the value which has been interactively obtained
368            from the user, and which still needs to be set at the inspected component.
369
370        @param InspectorUI
371            provides access to the object inspector UI. Implementations should use this if
372            the property selection requires non-modal user input. In those cases,
373            <member>onInteractivePropertySelection</member> should return <member>InteractiveSelectionResult::Pending</member>,
374            and the UI for (at least) the property whose input is still pending should be disabled.
375
376        @return
377            the result of the interactive property value selection.
378
379        @throws com::sun::star::beans::UnknownPropertyException
380            if the given property is not supported by the property handler
381        @throws com::sun::star::lang::NullPointerException
382            if <arg>InspectorUI</arg> is <NULL/>
383
384        @see describePropertyLine
385        @see addPropertyChangeListener
386        @see isComposable
387    */
388    ::com::sun::star::inspection::InteractiveSelectionResult
389        onInteractivePropertySelection(
390            [in] string PropertyName,
391            [in] boolean Primary,
392            [out] any out_Data,
393            [in] XObjectInspectorUI InspectorUI
394        )
395        raises (::com::sun::star::beans::UnknownPropertyException, ::com::sun::star::lang::NullPointerException);
396
397    /** updates the UI of dependent properties when the value of a certain actuating property changed
398
399        <p>This method is called whenever a property value changes, limited to those properties
400        whose changes the handler expressed interest in (see <member>getActuatingProperties</member>).</p>
401
402        @param ActuatingPropertyName
403            the id of the actuating property.
404        @param NewValue
405            the new value of the property
406        @param OldValue
407            the old value of the property
408        @param InspectorUI
409            a callback for updating the object inspector UI
410        @param FirstTimeInit
411            If <TRUE/>, the method is called for the first-time update of the respective property, that
412            is, when the property browser is just initializing with the properties of the introspected
413            object.<br/>
414            If <FALSE/>, there was a real <member scope="com::sun::star::beans">XPropertyChangeListener::propertyChange</member>
415            event which triggered the call.<br/>
416            <br/>
417            In some cases it may be necessary to differentiate between both situations. For instance,
418            if you want to set the value of another property when an actuating property's value changed,
419            you should definately not do this when <arg>FirstTimeInit</arg> is <TRUE/>.
420        @throws com::sun::star::lang::NullPointerException
421            if <arg>InspectorUI</arg> is <NULL/>
422    */
423    void
424        actuatingPropertyChanged(
425            [in] string ActuatingPropertyName,
426            [in] any NewValue,
427            [in] any OldValue,
428            [in] XObjectInspectorUI InspectorUI,
429            [in] boolean FirstTimeInit
430        )
431        raises (::com::sun::star::lang::NullPointerException);
432
433    /** suspends the handler
434
435        <p>A <type>XPropertyHandler</type> is used by a <type>XObjectInspector</type> instance,
436        which implements the XController interface. By definition, a XObjectInspector always forwards
437        all suspend requests (<member scope="com::sun::star::frame">XController::suspend</member>) to
438        all it's handlers.</p>
439
440        <p>The usual use case for this method are non-modal user interface components used
441        for property value input. Such a component might have been opened during
442        <member>onInteractivePropertySelection</member>. If a property handler receives a
443        <member>suspend</member> call, it should forward the suspension request to the UI
444        component, and veto suspension of the <type>XObjectInspector</type> as appropriate.</p>
445
446        <p>If suspension is not to be vetoed, then all non-modal UI components opened
447        by the handler should have been closed when it returns from the <member>suspend</member> call.</p>
448
449        @param Suspend
450            Whether the handler is to be suspended <TRUE/> or reactivated (<FALSE/>). The
451            latter happens if a handler was successfully suspended, but an external instance
452            vetoed the whole suspension process.
453
454        @return
455            <TRUE/> if the handler does allow suspension, <FALSE/> if it vetoes it.
456    */
457    boolean suspend( [in] boolean Suspend );
458};
459
460//=============================================================================
461
462}; }; }; };
463
464#endif
465
466
467
468