is the basic interface for object inspection. More...

import"XPropertyHandler.idl";

Inheritance diagram for XPropertyHandler:

Exported Interfaces
interface	com::sun::star::lang::XComponent
	used for controlling resources acquired by the handler More...

Public Member Functions
void	inspect ([in] com::sun::star::uno::XInterface Component) raises ( com::sun::star::lang::NullPointerException )
	binds the property handler to a new component More...

any	getPropertyValue ([in] string PropertyName) raises (::com::sun::star::beans::UnknownPropertyException)
	retrieves the current value of a property More...

void	setPropertyValue ([in] string PropertyName, [in] any Value) raises (::com::sun::star::beans::UnknownPropertyException, ::com::sun::star::beans::PropertyVetoException)
	sets the value of a property More...

com::sun::star::beans::PropertyState	getPropertyState ([in] string PropertyName) raises (::com::sun::star::beans::UnknownPropertyException)
	returns the state of a property More...

LineDescriptor	describePropertyLine ([in] string PropertyName, [in] XPropertyControlFactory ControlFactory) raises (::com::sun::star::beans::UnknownPropertyException, ::com::sun::star::lang::NullPointerException)
	describes the UI to be used to represent the property More...

any	convertToPropertyValue ([in] string PropertyName, [in] any ControlValue) raises (::com::sun::star::beans::UnknownPropertyException)
	converts a given control-compatible value to a property value More...

any	convertToControlValue ([in] string PropertyName, [in] any PropertyValue, [in] type ControlValueType) raises (::com::sun::star::beans::UnknownPropertyException)
	converts a given property value to a control-compatible value More...

void	addPropertyChangeListener ([in] com::sun::star::beans::XPropertyChangeListener Listener) raises ( com::sun::star::lang::NullPointerException )
	registers a listener for notification about property value changes More...

void	removePropertyChangeListener ([in] com::sun::star::beans::XPropertyChangeListener Listener)
	revokes a listener for notification about property value changes More...

sequence< com::sun::star::beans::Property >	getSupportedProperties ()
	returns the properties which the handler can handle More...

sequence< string >	getSupersededProperties ()
	returns the properties which are to be superseded by this handler More...

sequence< string >	getActuatingProperties ()
	retrieve the actuating properties which this handler is interested in More...

boolean	isComposable ([in] string PropertyName) raises (::com::sun::star::beans::UnknownPropertyException)
	determines whether a given property, which the handler is responsible for, is composable. More...

::com::sun::star::inspection::InteractiveSelectionResult	onInteractivePropertySelection ([in] string PropertyName, [in] boolean Primary, [out] any outData, [in] XObjectInspectorUI InspectorUI) raises (::com::sun::star::beans::UnknownPropertyException, ::com::sun::star::lang::NullPointerException)
	called when a browse button belonging to a property UI representation has been clicked More...

void	actuatingPropertyChanged ([in] string ActuatingPropertyName, [in] any NewValue, [in] any OldValue, [in] XObjectInspectorUI InspectorUI, [in] boolean FirstTimeInit) raises (::com::sun::star::lang::NullPointerException)
	updates the UI of dependent properties when the value of a certain actuating property changed More...

boolean	suspend ([in] boolean Suspend)
	suspends the handler More...

Public Member Functions inherited from XComponent
void	dispose ()
	The owner of an object calls this method to explicitly free all resources kept by this object and thus break cyclic references. More...

void	addEventListener ([in] XEventListener xListener)
	adds an event listener to the object. More...

void	removeEventListener ([in] XEventListener aListener)
	removes an event listener from the listener list. More...

Public Member Functions inherited from XInterface
any	queryInterface ([in] type aType)
	queries for a new interface to an existing UNO object. More...

void	acquire ()
	increases the reference counter by one. More...

void	release ()
	decreases the reference counter by one. More...

Detailed 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.

See also: ObjectInspector; LineDescriptor

Since: OOo 2.0.3

Exported Interfaces

◆ com::sun::star::lang::XComponent

interface com::sun::star::lang::XComponent

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.

Member Function Documentation

◆ actuatingPropertyChanged()

void actuatingPropertyChanged	(	[in] string	ActuatingPropertyName,
		[in] any	NewValue,
		[in] any	OldValue,
		[in] XObjectInspectorUI	InspectorUI,
		[in] boolean	FirstTimeInit
	)
raises	(	::com::sun::star::lang::NullPointerException
	)

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()).

Parameters

ActuatingPropertyName	the id of the actuating property.
NewValue	the new value of the property
OldValue	the old value of the property
InspectorUI	a callback for updating the object inspector UI
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 definitely not do this when FirstTimeInit is `TRUE`.

Exceptions

com::sun::star::lang::NullPointerException if InspectorUI is NULL

◆ addPropertyChangeListener()

void addPropertyChangeListener	(	[in] com::sun::star::beans::XPropertyChangeListener	Listener	)
raises	(	com::sun::star::lang::NullPointerException
	)

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 introspection is set in the next inspect() call.

Parameters

Listener the listener to notify about property changes

Exceptions

com::sun::star::lang::NullPointerException if the listener is NULL

See also: removePropertyChangeListener

◆ convertToControlValue()

any convertToControlValue	(	[in] string	PropertyName,
		[in] any	PropertyValue,
		[in] type	ControlValueType
	)
raises	(	::com::sun::star::beans::UnknownPropertyException
	)

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.

Parameters

PropertyName	The name of the property whose value is to be converted.
PropertyValue	The to-be-converted property value.
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.

Exceptions

com::sun::star::beans::UnknownPropertyException if the given property is not supported by the property handler

See also: convertToPropertyValue; describePropertyLine; XPropertyControl; getPropertyValue

◆ convertToPropertyValue()

any convertToPropertyValue	(	[in] string	PropertyName,
		[in] any	ControlValue
	)
raises	(	::com::sun::star::beans::UnknownPropertyException
	)

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().

Parameters

PropertyName	The name of the conversion's target property.
ControlValue	The to-be-converted control value. This value has been obtained from an XPropertyControl, using its XPropertyControl::Value attribute.

Exceptions

com::sun::star::beans::UnknownPropertyException if the given property is not supported by the property handler

See also: convertToControlValue; describePropertyLine; XPropertyControl; getPropertyValue

◆ describePropertyLine()

LineDescriptor describePropertyLine	(	[in] string	PropertyName,
		[in] XPropertyControlFactory	ControlFactory
	)
raises	(	::com::sun::star::beans::UnknownPropertyException,
		::com::sun::star::lang::NullPointerException
	)

describes the UI to be used to represent the property

Parameters

PropertyName	the name of the property whose user interface is to be described implementation
ControlFactory	a factory for creating XPropertyControl instances. Must not be `NULL`.

Returns: the descriptor of the property line.

Exceptions

com::sun::star::beans::UnknownPropertyException	if the given property is not supported by this handler
com::sun::star::lang::NullPointerException	if ControlFactory is `NULL`.

See also: PropertyControlType; LineDescriptor

◆ getActuatingProperties()

sequence< string > getActuatingProperties ( )

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

◆ getPropertyState()

com::sun::star::beans::PropertyState getPropertyState	(	[in] string	PropertyName	)
raises	(	::com::sun::star::beans::UnknownPropertyException
	)

returns the state of a property

Parameters

PropertyName the name of the property whose state is to be retrieved

Exceptions

com::sun::star::beans::UnknownPropertyException if the given property is not supported by the property handler

◆ getPropertyValue()

any getPropertyValue	(	[in] string	PropertyName	)
raises	(	::com::sun::star::beans::UnknownPropertyException
	)

retrieves the current value of a property

Parameters

PropertyName the name of the property whose value is to be retrieved

Exceptions

com::sun::star::beans::UnknownPropertyException if the given property is not supported by the property handler

◆ getSupersededProperties()

sequence< string > getSupersededProperties ( )

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 precedence is implied by the precedence 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

◆ getSupportedProperties()

sequence< com::sun::star::beans::Property > getSupportedProperties ( )

returns the properties which the handler can handle

A handler is allowed to return an empty sequence here, indicating that for the given introspection, 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.

◆ inspect()

void inspect	(	[in] com::sun::star::uno::XInterface	Component	)
raises	(	com::sun::star::lang::NullPointerException
	)

binds the property handler to a new component

Parameters

Component the component to inspect. Must not be NULL

Exceptions

com::sun::star::lang::NullPointerException if the component is NULL

◆ isComposable()

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

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.

Parameters

PropertyName the name of the property whose composability is to be determined

Exceptions

com::sun::star::beans::UnknownPropertyException if the given property is not supported by the property handler

◆ onInteractivePropertySelection()

::com::sun::star::inspection::InteractiveSelectionResult onInteractivePropertySelection	(	[in] string	PropertyName,
		[in] boolean	Primary,
		[out] any	outData,
		[in] XObjectInspectorUI	InspectorUI
	)
raises	(	::com::sun::star::beans::UnknownPropertyException,
		::com::sun::star::lang::NullPointerException
	)

called when a browse button belonging to a property UI representation 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 obtained 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 composable, directly setting the new property value does not yield any problem, as long as property listeners are properly notified of the change.

Parameters

PropertyName	The name of the property whose browse button has been clicked
Primary	`TRUE` if and only if the primary button has been clicked, `FALSE` otherwise
outData	If the method returns InteractiveSelectionResult::ObtainedValue, then outData contains the value which has been interactively obtained from the user, and which still needs to be set at the inspected component.
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.

Exceptions

com::sun::star::beans::UnknownPropertyException	if the given property is not supported by the property handler
com::sun::star::lang::NullPointerException	if InspectorUI is `NULL`

See also: describePropertyLine; addPropertyChangeListener; isComposable

◆ removePropertyChangeListener()

void removePropertyChangeListener ( [in] com::sun::star::beans::XPropertyChangeListener Listener )

revokes a listener for notification about property value changes

See also: addPropertyChangeListener

◆ setPropertyValue()

void setPropertyValue	(	[in] string	PropertyName,
		[in] any	Value
	)
raises	(	::com::sun::star::beans::UnknownPropertyException,
		::com::sun::star::beans::PropertyVetoException
	)

sets the value of a property

Parameters

PropertyName	the name of the property whose value is to be set
Value	the property value to set

Exceptions

com::sun::star::beans::UnknownPropertyException if the given property is not supported by the property handler

◆ suspend()

boolean suspend ( [in] boolean Suspend )

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 its 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.

Parameters

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.

The documentation for this interface was generated from the following file:

com/sun/star/inspection/XPropertyHandler.idl

Exported Interfaces

Public Member Functions

Detailed Description

Exported Interfaces

◆ com::sun::star::lang::XComponent

Member Function Documentation

◆ actuatingPropertyChanged()

◆ addPropertyChangeListener()

◆ convertToControlValue()

◆ convertToPropertyValue()

◆ describePropertyLine()

◆ getActuatingProperties()

◆ getPropertyState()

◆ getPropertyValue()

◆ getSupersededProperties()

◆ getSupportedProperties()

◆ inspect()

◆ isComposable()

◆ onInteractivePropertySelection()

◆ removePropertyChangeListener()

◆ setPropertyValue()

◆ suspend()