INTEGRATION: CWS pbrwuno (1.1.2); FILE ADDED

2005/12/21 14:19:18 fs 1.1.2.9: corrected typos found by juergen.schmidt@sun.com - thanks
2005/12/21 14:16:55 fs 1.1.2.8: new-style service
2005/12/21 08:34:38 fs 1.1.2.7: documentation issues
2005/11/02 11:39:16 fs 1.1.2.6: more exception specifications
2005/10/25 11:51:49 fs 1.1.2.5: #i53095# some exception specifications, and some conceptual changes for multiple handlers supporting the same property
2005/10/25 06:58:46 fs 1.1.2.4: clarified addPropeertyChangeListener constraints
2005/10/19 07:50:45 fs 1.1.2.3: #i53095# some exceptions
2005/10/13 13:14:35 fs 1.1.2.2: #i53095# +inspect
2005/10/11 13:20:38 fs 1.1.2.1: #i53095#

1 files changed, 478 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..0b3dd24a2a7a
--- /dev/null
+++ b/offapi/com/sun/star/inspection/XPropertyHandler.idl
@@ -0,0 +1,478 @@
+/*************************************************************************
+ *
+ *  OpenOffice.org - a multi-platform office productivity suite
+ *
+ *  $RCSfile: XPropertyHandler.idl,v $
+ *
+ *  $Revision: 1.2 $
+ *
+ *  last change: $Author: vg $ $Date: 2006-03-14 11:08:09 $
+ *
+ *  The Contents of this file are made available subject to
+ *  the terms of GNU Lesser General Public License Version 2.1.
+ *
+ *
+ *    GNU Lesser General Public License Version 2.1
+ *    =============================================
+ *    Copyright 2005 by Sun Microsystems, Inc.
+ *    901 San Antonio Road, Palo Alto, CA 94303, USA
+ *
+ *    This library is free software; you can redistribute it and/or
+ *    modify it under the terms of the GNU Lesser General Public
+ *    License version 2.1, as published by the Free Software Foundation.
+ *
+ *    This library 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 for more details.
+ *
+ *    You should have received a copy of the GNU Lesser General Public
+ *    License along with this library; if not, write to the Free Software
+ *    Foundation, Inc., 59 Temple Place, Suite 330, Boston,
+ *    MA  02111-1307  USA
+ *
+ ************************************************************************/
+#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;
+
+//-----------------------------------------------------------------------------
+/** The <type>XPropertyHandler</type> is the basic interface for object inspection.
+
+    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
+*/
+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
+        @param out_Descriptor
+            the descriptor of the property line, to be filled by the <type>XPropertyHandler</type>
+            implementation
+        @param ControlFactory
+            a factory for creating <type>XPropertyControl</type> instances. Must not be <NULL/>.
+        @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
+    */
+    void
+        describePropertyLine(
+            [in] string PropertyName,
+            [out] LineDescriptor out_Descriptor,
+            [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 _rxListener );
+
+    /** 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 propertes (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
+
+
+