offapi/com/sun/star/inspection/XPropertyHandler.idl

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