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