diff options
Diffstat (limited to 'offapi/com/sun/star/inspection/XPropertyHandler.idl')
| -rw-r--r-- | offapi/com/sun/star/inspection/XPropertyHandler.idl | 471 |
1 files changed, 471 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 000000000000..81a105b8b9a5 --- /dev/null +++ b/offapi/com/sun/star/inspection/XPropertyHandler.idl @@ -0,0 +1,471 @@ +/************************************************************************* + * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. + * + * Copyright 2000, 2010 Oracle and/or its affiliates. + * + * OpenOffice.org - a multi-platform office productivity suite + * + * This file is part of OpenOffice.org. + * + * OpenOffice.org is free software: you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License version 3 + * only, as published by the Free Software Foundation. + * + * OpenOffice.org is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Lesser General Public License version 3 for more details + * (a copy is included in the LICENSE file that accompanied this code). + * + * You should have received a copy of the GNU Lesser General Public License + * version 3 along with OpenOffice.org. If not, see + * <http://www.openoffice.org/license.html> + * for a copy of the LGPLv3 License. + * + ************************************************************************/ +#ifndef __com_sun_star_inspection_XPropertyHandler_idl__ +#define __com_sun_star_inspection_XPropertyHandler_idl__ + +#ifndef __com_sun_star_beans_PropertyState_idl__ +#include <com/sun/star/beans/PropertyState.idl> +#endif +#ifndef __com_sun_star_beans_Property_idl__ +#include <com/sun/star/beans/Property.idl> +#endif +#ifndef __com_sun_star_beans_XPropertyChangeListener_idl__ +#include <com/sun/star/beans/XPropertyChangeListener.idl> +#endif +#ifndef __com_sun_star_inspection_LineDescriptor_idl__ +#include <com/sun/star/inspection/LineDescriptor.idl> +#endif +#ifndef __com_sun_star_lang_NullPointerException_idl__ +#include <com/sun/star/lang/NullPointerException.idl> +#endif +#ifndef __com_sun_star_beans_UnknownPropertyException_idl__ +#include <com/sun/star/beans/UnknownPropertyException.idl> +#endif +#ifndef __com_sun_star_lang_XComponent_idl__ +#include <com/sun/star/lang/XComponent.idl> +#endif +#ifndef __com_sun_star_inspection_InteractiveSelectionResult_idl__ +#include <com/sun/star/inspection/InteractiveSelectionResult.idl> +#endif + +//============================================================================= +module com { module sun { module star { module inspection { + +interface XObjectInspectorUI; +interface XPropertyControlFactory; + +//----------------------------------------------------------------------------- +/** is the basic interface for object inspection. + + <p>The <type>ObjectInspector</type> itself does not know anything about the object + it is inspecting, all information is obtained via <type>XPropertyHandler</type>s. + 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><member scope="com::sun::star::lang">XComponent::dispose</member> 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); + + /** 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 <type>XPropertyControl</type> 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 <arg>ControlFactory</arg> 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 <member>describePropertyLine</member>, 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 <member>setPropertyValue</member>.</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 <type>XPropertyControl</type>, + using its <member>Value</member> 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 <member>describePropertyLine</member>, 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 + <member>getPropertyValue</member>, into a control-compatible value, which can be used + with <type>XPropertyControl</type>'s <member>XPropertyControl::Value</member> 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, + <member>convertToControlValue</member> and <member>convertToPropertyValue</member> are used.</p> + + <p>The method is not invoked if the control's value type (<member>XPropertyControl::ValueType</member> + 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 <member>describePropertyLine</member>.<br/> + Speaking strictly, this is passed for convenience only, since every <type>XPropertyHandler</type> + implementation should know exactly which type to expect, since it implicitly determined this type + in <member>describePropertyLine</member> by creating an appropriate <type>XPropertyControl</type>. + + @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 <type>XPropertyHandler</type> 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 <member>addPropertyChangeListener</member> 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 <member>inspect</member> 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 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.</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 <member>getSupportedProperties</member>), + 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 <type>ObjectInspector</type>, + 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 + <member>XObjectInspectorModel::HandlerFactories</member> 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 <type>XObjectInspectorModel</type> 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 <member>getSupportedProperties</member> 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 + <member>actuatingPropertyChanged</member> method.</p> + + <p>If <member>getSupportedProperties</member> 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 represenation 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 <member>LineDescriptor::HasPrimaryButton</member> + and <member>LineDescriptor::HasSecondaryButton</member> members of a <type>LineDescriptor</type>, + which the <type>XPropertyHandler</type> fills in its <member>describePropertyLine</member> 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 <type>InteractiveSelectionResult</type>).</p> + + <p>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 + <member>InteractiveSelectionResult::ObtainedValue</member>.</p> + + <p>If a handler sets the new property value directly, and returns + <member>InteractiveSelectionResult::ObtainedValue</member>, 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 <member>onInteractivePropertySelection</member> + 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 composeable, 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 out_Data + If the method returns <member>InteractiveSelectionResult::ObtainedValue</member>, + then <arg>out_Data</arg> 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, + <member>onInteractivePropertySelection</member> should return <member>InteractiveSelectionResult::Pending</member>, + 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 <arg>InspectorUI</arg> is <NULL/> + + @see describePropertyLine + @see addPropertyChangeListener + @see isComposable + */ + ::com::sun::star::inspection::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); + + /** 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 <member>getActuatingProperties</member>).</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 <member scope="com::sun::star::beans">XPropertyChangeListener::propertyChange</member> + 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 definately not do this when <arg>FirstTimeInit</arg> is <TRUE/>. + @throws com::sun::star::lang::NullPointerException + if <arg>InspectorUI</arg> 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 <type>XPropertyHandler</type> is used by a <type>XObjectInspector</type> instance, + which implements the XController interface. By definition, a XObjectInspector always forwards + all suspend requests (<member scope="com::sun::star::frame">XController::suspend</member>) to + all it's 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 + <member>onInteractivePropertySelection</member>. If a property handler receives a + <member>suspend</member> call, it should forward the suspension request to the UI + component, and veto suspension of the <type>XObjectInspector</type> 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 <member>suspend</member> 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 + + + |