Language:

The Free and Open Productivity Suite
Apache OpenOffice 4.1.4 released

Developer's Guide

API

SDK

Tips 'n' Tricks

Miscellaneous


:: com :: sun :: star :: inspection ::

interface XPropertyHandler
Base Interfaces
XPropertyHandler
┗ ::com::sun::star::lang::XComponent

::com::sun::star::lang::XComponent
Description
used for controlling resources acquired by the handler

::com::sun::star::lang::XComponent::dispose is invoked when the property handler is not needed by the object inspector anymore. Handler implementations should clean up any resources here.

Description
is the basic interface for object inspection.

The ObjectInspector itself does not know anything about the object it is inspecting, all information is obtained via XPropertyHandlers. Also, property handlers are responsible for describing the user interface which should be used to interact with the user, with respect to a given aspect of the inspected component.

Since
OOo 2.0.3
See also
ObjectInspector, LineDescriptor

Methods' Summary
inspect binds the property handler to a new component  
getPropertyValue retrieves the current value of a property  
setPropertyValue sets the value of a property  
getPropertyState returns the state of a property  
describePropertyLine describes the UI to be used to represent the property  
convertToPropertyValue converts a given control-compatible value to a property value  
convertToControlValue converts a given property value to a control-compatible value  
addPropertyChangeListener registers a listener for notification about property value changes  
removePropertyChangeListener revokes a listener for notification about property value changes  
getSupportedProperties returns the properties which the handler can handle  
getSupersededProperties returns the properties which are to be superseded by this handler  
getActuatingProperties retrieve the actuating properties which this handler is interested in  
isComposable determines whether a given property, which the handler is responsible for, is composable.  
onInteractivePropertySelection called when a browse button belonging to a property UI represenation has been clicked  
actuatingPropertyChanged updates the UI of dependent properties when the value of a certain actuating property changed  
suspend suspends the handler  
Methods' Details
inspect
void
inspect( [in] ::com::sun::star::uno::XInterface  Component )
raises( ::com::sun::star::lang::NullPointerException );

Description
binds the property handler to a new component
Parameter Component
the component to inspect. Must not be NULL
Throws
com::sun::star::lang::NullPointerException if the component is NULL
getPropertyValue
any
getPropertyValue( [in] string  PropertyName )
raises( ::com::sun::star::beans::UnknownPropertyException );

Description
retrieves the current value of a property
Parameter PropertyName
the name of the property whose value is to be retrieved
Throws
com::sun::star::beans::UnknownPropertyException if the given property is not supported by the property handler
setPropertyValue
void
setPropertyValue( [in] string  PropertyName,
[in] any  Value )
raises( ::com::sun::star::beans::UnknownPropertyException );

Description
sets the value of a property
Parameter PropertyName
the name of the property whose value is to be set
Parameter Value
the property value to set
Throws
com::sun::star::beans::UnknownPropertyException if the given property is not supported by the property handler
getPropertyState
::com::sun::star::beans::PropertyState
getPropertyState( [in] string  PropertyName )
raises( ::com::sun::star::beans::UnknownPropertyException );

Description
returns the state of a property
Parameter PropertyName
the name of the property whose state is to be retrieved
Throws
com::sun::star::beans::UnknownPropertyException if the given property is not supported by the property handler
describePropertyLine
LineDescriptor
describePropertyLine( [in] string  PropertyName,
[in] XPropertyControlFactory  ControlFactory )
raises( ::com::sun::star::beans::UnknownPropertyException,
::com::sun::star::lang::NullPointerException );

Description
describes the UI to be used to represent the property
Parameter PropertyName
the name of the property whose user interface is to be described implementation
Parameter ControlFactory
a factory for creating XPropertyControl instances. Must not be NULL.
Returns
the descriptor of the property line.
Throws
com::sun::star::beans::UnknownPropertyException if the given property is not supported by this handler
Throws
com::sun::star::lang::NullPointerException if ControlFactory is NULL.
See also
PropertyControlType, LineDescriptor
convertToPropertyValue
any
convertToPropertyValue( [in] string  PropertyName,
[in] any  ControlValue )
raises( ::com::sun::star::beans::UnknownPropertyException );

Description
converts a given control-compatible value to a property value

In describePropertyLine, a property handler declared which type of control should be used to display the value of a certain property. To allow to use the same control type for different properties, and in particular, for properties of different type, conversions between controls values and property values are needed.

This method converts a control value into a property value, which subsequently can be used in conjunction with setPropertyValue.

Parameter PropertyName
The name of the conversion's target property.
Parameter ControlValue
The to-be-converted control value. This value has been obtained from an XPropertyControl, using its Value attribute.
Throws
com::sun::star::beans::UnknownPropertyException if the given property is not supported by the property handler
See also
convertToControlValue, describePropertyLine, XPropertyControl, getPropertyValue
convertToControlValue
any
convertToControlValue( [in] string  PropertyName,
[in] any  PropertyValue,
[in] type  ControlValueType )
raises( ::com::sun::star::beans::UnknownPropertyException );

Description
converts a given property value to a control-compatible value

In describePropertyLine, a property handler declared which type of control should be used to display the value of a certain property. To allow to use the same control type for different properties, and in particular, for properties of different type, conversions between controls values and property values are needed.

This method converts a property value, which has previously been obtained using getPropertyValue, into a control-compatible value, which can be used with XPropertyControl's XPropertyControl::Value attribute.

A usual application of this method are list boxes: There is a generic list box implementation, which is able to display a simple list of strings. Usually, every string represents one possible property value. To translate between those property values and the displayed strings, convertToControlValue and convertToPropertyValue are used.

The method is not invoked if the control's value type (XPropertyControl::ValueType equals the property's value type.

Parameter PropertyName
The name of the property whose value is to be converted.
Parameter PropertyValue
The to-be-converted property value.
Parameter ControlValueType
The target type of the conversion. This type is determined by the control which is used to display the property, which in turn is determined by the handler itself in describePropertyLine.
Speaking strictly, this is passed for convenience only, since every XPropertyHandler implementation should know exactly which type to expect, since it implicitly determined this type in describePropertyLine by creating an appropriate XPropertyControl.
Throws
com::sun::star::beans::UnknownPropertyException if the given property is not supported by the property handler
See also
convertToPropertyValue, describePropertyLine, XPropertyControl, getPropertyValue
addPropertyChangeListener
void
addPropertyChangeListener( [in] ::com::sun::star::beans::XPropertyChangeListener  Listener )
raises( ::com::sun::star::lang::NullPointerException );

Description
registers a listener for notification about property value changes

An XPropertyHandler implementation might decide to ignore this call. However, in this case property value changes made by third party components are not reflected in the object inspector.

If a handler implementation supports property change listeners, it must be able to cope with a call to addPropertyChangeListener even if currently no component is being inspected. In this case, the listener must become active as soon as a new introspectee is set in the next inspect call.

Parameter Listener
the listener to notify about property changes
Throws
com::sun::star::lang::NullPointerException if the listener is NULL
See also
removePropertyChangeListener
removePropertyChangeListener
void
removePropertyChangeListener( [in] ::com::sun::star::beans::XPropertyChangeListener  Listener );

Description
revokes a listener for notification about property value changes
See also
addPropertyChangeListener
getSupportedProperties
sequence< ::com::sun::star::beans::Property >
getSupportedProperties();

Description
returns the properties which the handler can handle

A handler is allowed to return an empty sequence here, indicating that for the given introspectee, no properties handling can be provided. This might happen when a fixed set of property handlers is used for a variety of components to inspect, where not all handlers can really cope with all components.

In the case of returning an empty sequence here, the property handler is ignored by all further processing in the object inspector.

getSupersededProperties
sequence< string >
getSupersededProperties();

Description
returns the properties which are to be superseded by this handler

Besides defining an own set of properties (see getSupportedProperties), a property handler can also declare that foreign properties (which it is not responsible for) are superseded by its own properties.

This is usually used if your handler is used with another, more generic one, which should continue to be responsible for all properties, except a few which your handler handles more elegantly.

In such a case, simply return those properties here.

There is a precedence in the property handlers used by an ObjectInspector, which also is important for the superseded properties. This precendence is implied by the precendence of factories to create the property handlers, as denoted in the XObjectInspectorModel::HandlerFactories attribute.

With this in mind, property handlers can only supersede properties which are supported by a handler preceding them, but not properties of handlers succeeding them.

For instance, imaging an XObjectInspectorModel which provides three factories, for handler A, B, and C - in this order. Now if A supports the property Foo, C supports Bar, and B supersedes both Foo and Bar, them the result is Bar is still present. This is because B precedes C, so it cannot, by definition, supersede properties which are supported by C.

If getSupportedProperties returned an empty sequence, this method will not be called.

See also
XObjectInspectorModel::HandlerFactories
getActuatingProperties
sequence< string >
getActuatingProperties();

Description
retrieve the actuating properties which this handler is interested in

In general, properties can be declared as "actuating", that is, when their value changes, the UI for other properties needs to be updated (e.g. enabled or disabled).

With this method, a handler can declare that it feels responsible for some/all of the depending properties of certain actuating properties.

Whenever the value of an actuating property changes, all handlers which expressed their interest in this particular actuating properties are called with their actuatingPropertyChanged method.

If getSupportedProperties returned an empty sequence, this method will not be called

isComposable
boolean
isComposable( [in] string  PropertyName )
raises( ::com::sun::star::beans::UnknownPropertyException );

Description
determines whether a given property, which the handler is responsible for, is composable.

An object inspector can inspect multiple components at once, displaying the intersection of their properties. For this, all components are examined for their properties, and all properties which exist for all components, and are declared to be composable by their respective handler, are displayed in the inspector UI.

Parameter PropertyName
the name of the property whose composability is to be determined
Throws
com::sun::star::beans::UnknownPropertyException if the given property is not supported by the property handler
onInteractivePropertySelection
InteractiveSelectionResult
onInteractivePropertySelection( [in] string  PropertyName,
[in] boolean  Primary,
[out] any  out_Data,
[in] XObjectInspectorUI  InspectorUI )
raises( ::com::sun::star::beans::UnknownPropertyException,
::com::sun::star::lang::NullPointerException );

Description
called when a browse button belonging to a property UI represenation has been clicked

Property handlers can raise a dedicated UI for entering or somehow changing a property value. Usually, this will be a modal dialog, but it can also be a non-modal user interface component.

Availability of this feature is indicated by the LineDescriptor::HasPrimaryButton and LineDescriptor::HasSecondaryButton members of a LineDescriptor, which the XPropertyHandler fills in its describePropertyLine method.

When this method is called, the property handler should raise the UI needed to enter the property value, and return the result of this (see InteractiveSelectionResult).

It is recommended that property handlers do not directly set the property value which has been obatined from the user, but store it in the output-parameter Data, and return InteractiveSelectionResult::ObtainedValue.

If a handler sets the new property value directly, and returns InteractiveSelectionResult::ObtainedValue, this implies that the property cannot properly be handled in case the object inspector is inspecting an intersection of multiple components, since in this case onInteractivePropertySelection will be called at one handler only, however the new property would have to be forwarded to all handlers.

If a property is not composeable, directly setting the new property value does not yield any problem, as long as property listeners are properly notified of the change.

Parameter PropertyName
The name of the property whose browse button has been clicked
Parameter Primary
true if and only if the primary button has been clicked, false otherwise
Parameter out_Data
If the method returns InteractiveSelectionResult::ObtainedValue, then out_Data contains the value which has been interactively obtained from the user, and which still needs to be set at the inspected component.
Parameter InspectorUI
provides access to the object inspector UI. Implementations should use this if the property selection requires non-modal user input. In those cases, onInteractivePropertySelection should return InteractiveSelectionResult::Pending, and the UI for (at least) the property whose input is still pending should be disabled.
Returns
the result of the interactive property value selection.
Throws
com::sun::star::beans::UnknownPropertyException if the given property is not supported by the property handler
Throws
com::sun::star::lang::NullPointerException if InspectorUI is NULL
See also
describePropertyLine, addPropertyChangeListener, isComposable
actuatingPropertyChanged
void
actuatingPropertyChanged( [in] string  ActuatingPropertyName,
[in] any  NewValue,
[in] any  OldValue,
[in] XObjectInspectorUI  InspectorUI,
[in] boolean  FirstTimeInit )
raises( ::com::sun::star::lang::NullPointerException );

Description
updates the UI of dependent properties when the value of a certain actuating property changed

This method is called whenever a property value changes, limited to those properties whose changes the handler expressed interest in (see getActuatingProperties).

Parameter ActuatingPropertyName
the id of the actuating property.
Parameter NewValue
the new value of the property
Parameter OldValue
the old value of the property
Parameter InspectorUI
a callback for updating the object inspector UI
Parameter FirstTimeInit
If true, the method is called for the first-time update of the respective property, that is, when the property browser is just initializing with the properties of the introspected object.
If false, there was a real ::com::sun::star::beans::XPropertyChangeListener::propertyChange event which triggered the call.

In some cases it may be necessary to differentiate between both situations. For instance, if you want to set the value of another property when an actuating property's value changed, you should definately not do this when FirstTimeInit is true.
Throws
com::sun::star::lang::NullPointerException if InspectorUI is NULL
suspend
boolean
suspend( [in] boolean  Suspend );

Description
suspends the handler

A XPropertyHandler is used by a XObjectInspector instance, which implements the XController interface. By definition, a XObjectInspector always forwards all suspend requests (::com::sun::star::frame::XController::suspend) to all it's handlers.

The usual use case for this method are non-modal user interface components used for property value input. Such a component might have been opened during onInteractivePropertySelection. If a property handler receives a suspend call, it should forward the suspension request to the UI component, and veto suspension of the XObjectInspector as appropriate.

If suspension is not to be vetoed, then all non-modal UI components opened by the handler should have been closed when it returns from the suspend call.

Parameter Suspend
Whether the handler is to be suspended true or reactivated (false). The latter happens if a handler was successfully suspended, but an external instance vetoed the whole suspension process.
Returns
true if the handler does allow suspension, false if it vetoes it.
Top of Page

Apache Software Foundation

Copyright & License | Privacy | Contact Us | Donate | Thanks

Apache and the Apache feather logo are trademarks of The Apache Software Foundation. OpenOffice, OpenOffice.org and the seagull logo are registered trademarks of The Apache Software Foundation. Other names appearing on the site may be trademarks of their respective owners.