diff options
Diffstat (limited to 'offapi/com/sun/star/inspection/XPropertyHandler.idl')
| -rw-r--r-- | offapi/com/sun/star/inspection/XPropertyHandler.idl | 447 |
1 files changed, 447 insertions, 0 deletions
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 <com/sun/star/beans/PropertyState.idl> +#include <com/sun/star/beans/Property.idl> +#include <com/sun/star/beans/XPropertyChangeListener.idl> +#include <com/sun/star/inspection/LineDescriptor.idl> +#include <com/sun/star/lang/NullPointerException.idl> +#include <com/sun/star/beans/UnknownPropertyException.idl> +#include <com/sun/star/beans/PropertyVetoException.idl> +#include <com/sun/star/lang/XComponent.idl> +#include <com/sun/star/inspection/InteractiveSelectionResult.idl> + +module com { module sun { module star { module inspection { + +interface XObjectInspectorUI; +interface XPropertyControlFactory; + +/** is the basic interface for object inspection. + + <p>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.</p> + + @see ObjectInspector + @see LineDescriptor + + @since OOo 2.0.3 +*/ +interface XPropertyHandler +{ + /** used for controlling resources acquired by the handler + + <p>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.</p> + */ + 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 + + <p>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.</p> + + <p>This method converts a control value into a property value, which subsequently can be used + in conjunction with setPropertyValue().</p> + + @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 + + <p>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.</p> + + <p>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.</p> + + <p>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.</p> + + <p>The method is not invoked if the control's value type (XPropertyControl::ValueType + equals the property's value type.</p> + + @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().<br/> + 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 + + <p>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.</p> + + <p>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.</p> + + @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 + + <p>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.</p> + + <p>In the case of returning an empty sequence here, the property handler is ignored + by all further processing in the object inspector.</p> + */ + sequence< com::sun::star::beans::Property > + getSupportedProperties(); + + /** returns the properties which are to be superseded by this handler + + <p>Besides defining an own set of properties (see getSupportedProperties()), + a property handler can also declare that foreign properties (which it is + <em>not</em> responsible for) are superseded by its own properties.</p> + + <p>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.</p> + + <p>In such a case, simply return those properties here.</p> + + <p>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.</p> + + <p>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.</p> + + <p>For instance, imaging an XObjectInspectorModel which provides three + factories, for handler <code>A</code>, <code>B</code>, and <code>C</code> - in this order. + Now if <code>A</code> supports the property <code>Foo</code>, <code>C</code> supports + <code>Bar</code>, and <code>B</code> supersedes both <code>Foo</code> and <code>Bar</code>, + them the result is <code>Bar</code> is still present. This is because <code>B</code> precedes + <code>C</code>, so it cannot, by definition, supersede properties which are supported by + <code>C</code>.</p> + + <p>If getSupportedProperties() returned an empty sequence, this method will + not be called.</p> + + @see XObjectInspectorModel::HandlerFactories + */ + sequence< string > + getSupersededProperties( ); + + /** retrieve the actuating properties which this handler is interested in + + <p>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).</p> + + <p>With this method, a handler can declare that it feels responsible for some/all + of the depending properties of certain actuating properties.</p> + + <p>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.</p> + + <p>If getSupportedProperties() returned an empty sequence, this method will + not be called</p> + */ + sequence< string > + getActuatingProperties( ); + + /** determines whether a given property, which the handler is responsible for, is composable. + + <p>An object inspector can inspect multiple components at once, displaying the <em>intersection</em> + of their properties. For this, all components are examined for their properties, and all properties + which exist for all components, <em>and</em> are declared to be composable by their respective handler, + are displayed in the inspector UI.</p> + + @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 + + <p>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.</p> + + <p>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.</p> + + <p>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).</p> + + <p>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.</p> + + <p>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.</p> + + <p>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.</p> + + @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 + + <p>This method is called whenever a property value changes, limited to those properties + whose changes the handler expressed interest in (see getActuatingProperties()).</p> + + @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.<br/> + If `FALSE`, there was a real com::sun::star::beans::XPropertyChangeListener::propertyChange() + event which triggered the call.<br/> + <br/> + 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 + + <p>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.</p> + + <p>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.</p> + + <p>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.</p> + + @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: */ |