From ed5640d8b587fbcfed7dd7967f3de04b37a76f26 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 11:06:44 +0200 Subject: Adding upstream version 4:7.4.7. Signed-off-by: Daniel Baumann --- .../com/sun/star/inspection/XPropertyHandler.idl | 447 +++++++++++++++++++++ 1 file changed, 447 insertions(+) create mode 100644 offapi/com/sun/star/inspection/XPropertyHandler.idl (limited to 'offapi/com/sun/star/inspection/XPropertyHandler.idl') diff --git a/offapi/com/sun/star/inspection/XPropertyHandler.idl b/offapi/com/sun/star/inspection/XPropertyHandler.idl new file mode 100644 index 000000000..f65c44672 --- /dev/null +++ b/offapi/com/sun/star/inspection/XPropertyHandler.idl @@ -0,0 +1,447 @@ +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ +/* + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + * This file incorporates work covered by the following license notice: + * + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed + * with this work for additional information regarding copyright + * ownership. The ASF licenses this file to you under the Apache + * License, Version 2.0 (the "License"); you may not use this file + * except in compliance with the License. You may obtain a copy of + * the License at http://www.apache.org/licenses/LICENSE-2.0 . + */ +#ifndef __com_sun_star_inspection_XPropertyHandler_idl__ +#define __com_sun_star_inspection_XPropertyHandler_idl__ + +#include +#include +#include +#include +#include +#include +#include +#include +#include + +module com { module sun { module star { module inspection { + +interface XObjectInspectorUI; +interface XPropertyControlFactory; + +/** 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 ObjectInspector + @see LineDescriptor + + @since OOo 2.0.3 +*/ +interface XPropertyHandler +{ + /** 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.

+ */ + interface com::sun::star::lang::XComponent; + + /** binds the property handler to a new component + @param Component + the component to inspect. Must not be `NULL` + @throws com::sun::star::lang::NullPointerException + if the component is `NULL` + */ + void inspect( [in] com::sun::star::uno::XInterface Component ) + raises( com::sun::star::lang::NullPointerException ); + + /** retrieves the current value of a property + @param 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 + */ + any + getPropertyValue( [in] string PropertyName ) + raises (::com::sun::star::beans::UnknownPropertyException); + + /** sets the value of a property + + @param PropertyName + the name of the property whose value is to be set + @param Value + the property value to set + @throws com::sun::star::beans::UnknownPropertyException + if the given property is not supported by the property handler + */ + void + setPropertyValue( [in] string PropertyName, [in] any Value ) + raises (::com::sun::star::beans::UnknownPropertyException, + ::com::sun::star::beans::PropertyVetoException); + + /** returns the state of a property + + @param 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 + */ + com::sun::star::beans::PropertyState + getPropertyState( [in] string PropertyName ) + raises (::com::sun::star::beans::UnknownPropertyException); + + /** describes the UI to be used to represent the property + @param PropertyName + the name of the property whose user interface is to be described + implementation + @param ControlFactory + a factory for creating XPropertyControl instances. Must not be `NULL`. + @return + 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 PropertyControlType + @see LineDescriptor + */ + LineDescriptor + describePropertyLine( + [in] string PropertyName, + [in] XPropertyControlFactory ControlFactory + ) + raises (::com::sun::star::beans::UnknownPropertyException, ::com::sun::star::lang::NullPointerException); + + /** 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().

+ + @param PropertyName + The name of the conversion's target property. + @param ControlValue + The to-be-converted control value. This value has been obtained from an XPropertyControl, + using its XPropertyControl::Value attribute. + + @throws com::sun::star::beans::UnknownPropertyException + if the given property is not supported by the property handler + + @see convertToControlValue + @see describePropertyLine + @see XPropertyControl + @see getPropertyValue + */ + any + convertToPropertyValue( + [in] string PropertyName, + [in] any ControlValue + ) + 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.

+ + @param PropertyName + The name of the property whose value is to be converted. + @param PropertyValue + The to-be-converted property value. + @param 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 convertToPropertyValue + @see describePropertyLine + @see XPropertyControl + @see getPropertyValue + */ + any + convertToControlValue( + [in] string PropertyName, + [in] any PropertyValue, + [in] type ControlValueType + ) + raises (::com::sun::star::beans::UnknownPropertyException); + + /** 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.

+ + @param Listener + the listener to notify about property changes + @throws com::sun::star::lang::NullPointerException + if the listener is `NULL` + @see removePropertyChangeListener + */ + void + addPropertyChangeListener( [in] com::sun::star::beans::XPropertyChangeListener Listener ) + raises ( com::sun::star::lang::NullPointerException ); + + /** revokes a listener for notification about property value changes + @see addPropertyChangeListener + */ + void + removePropertyChangeListener( [in] com::sun::star::beans::XPropertyChangeListener Listener ); + + /** 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.

+ */ + sequence< com::sun::star::beans::Property > + getSupportedProperties(); + + /** 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 XObjectInspectorModel::HandlerFactories + */ + sequence< string > + getSupersededProperties( ); + + /** 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

+ */ + sequence< string > + getActuatingProperties( ); + + /** 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.

+ + @param 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 + */ + boolean isComposable( [in] string PropertyName ) + raises (::com::sun::star::beans::UnknownPropertyException); + + /** 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.

+ + @param PropertyName + The name of the property whose browse button has been clicked + + @param Primary + `TRUE` if and only if the primary button has been clicked, `FALSE` otherwise + + @param 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. + + @param 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. + + @return + 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 describePropertyLine + @see addPropertyChangeListener + @see isComposable + */ + ::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); + + /** 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()).

+ + @param ActuatingPropertyName + the id of the actuating property. + @param NewValue + the new value of the property + @param OldValue + the old value of the property + @param InspectorUI + a callback for updating the object inspector UI + @param 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`. + @throws com::sun::star::lang::NullPointerException + if InspectorUI is `NULL` + */ + void + actuatingPropertyChanged( + [in] string ActuatingPropertyName, + [in] any NewValue, + [in] any OldValue, + [in] XObjectInspectorUI InspectorUI, + [in] boolean FirstTimeInit + ) + raises (::com::sun::star::lang::NullPointerException); + + /** 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.

+ + @param 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. + + @return + `TRUE` if the handler does allow suspension, `FALSE` if it vetoes it. + */ + boolean suspend( [in] boolean Suspend ); +}; + + +}; }; }; }; + +#endif + + + +/* vim:set shiftwidth=4 softtabstop=4 expandtab: */ -- cgit v1.2.3