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.

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.

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.

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.

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.

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

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.

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.

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

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.