summaryrefslogtreecommitdiffstats
path: root/offapi/com/sun/star/inspection/XPropertyHandler.idl
diff options
context:
space:
mode:
Diffstat (limited to 'offapi/com/sun/star/inspection/XPropertyHandler.idl')
-rw-r--r--offapi/com/sun/star/inspection/XPropertyHandler.idl447
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: */