path: root/offapi/com/sun/star/inspection/XPropertyHandler.idl

/* -*- 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 .
 */

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 );
};


}; }; }; };



/* vim:set shiftwidth=4 softtabstop=4 expandtab: */