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

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