/**************************************************************
 * 
 * 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
 * 
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 * 
 *************************************************************/


#ifndef __com_sun_star_inspection_XObjectInspectorUI_idl__
#define __com_sun_star_inspection_XObjectInspectorUI_idl__

#ifndef __com_sun_star_inspection_XPropertyControl_idl__
#include <com/sun/star/inspection/XPropertyControl.idl>
#endif
#ifndef __com_sun_star_beans_Optional_idl__
#include <com/sun/star/beans/Optional.idl>
#endif
#ifndef __com_sun_star_container_NoSuchElementException_idl__
#include <com/sun/star/container/NoSuchElementException.idl>
#endif
#ifndef __com_sun_star_lang_NoSupportException_idl__
#include <com/sun/star/lang/NoSupportException.idl>
#endif

//=============================================================================
module com {  module sun {  module star {  module inspection {

published interface XPropertyControlObserver;

//-----------------------------------------------------------------------------
/** grants access to certain aspects of the user interface of an object
    inspector

    <p>This interface is used as callback for <type>XPropertyHandler</type>s.</p>

    <p>As a consequence, methods operating on the UI for a property, and taking the name of this property,
    are tolerant against properties which do not exist. For instance, if a property handler tries to
    disable the UI for property <code>Foo</code>, but another handler has superseded this property, then
    the <type>ObjectInspector</type> will not <em>have</em> any UI for it. In this case, the call to
    <code>enablePropertyUI( "Foo" )</code> will simply be ignored.</p>

    @since OOo 2.0.3
*/
published interface XObjectInspectorUI
{
    /** enables or disables all components belonging to the UI representation of a property

        <p>This is usually used by an <type>XPropertyHandler</type> if it handles properties,
        where one does only make sense if another one has a certain value.</p>

        @param  PropertyName
            denotes the name of the property whose UI is to be enabled or disabled.
        @param  Enable
            <TRUE/> if and only if the UI should be disabled, <FALSE/> otherwise.
    */
    void    enablePropertyUI( [in] string PropertyName, [in] boolean Enable );

    /** enables or disables the single elements which can be part of the UI representation of a property

        <p>Note that the complete UI for the property must be enabled in order for these settings to
        be evaluated. That is, <member>enablePropertyUIElements</member> does not have any effect if
        somebody previously disabled the complete UI for this property with <member>enablePropertyUI</member>.</p>

        @param  PropertyName
            the name of the property whose user interface elements are to be enabled or disabled

        @param  Elements
            a combination of <type>PropertyLineElement</type> flags specifying which elements are to be
            enabled or disabled.<br/>
            Note that if you don't set a particular bit here (say, <member>PropertyLineElement::PrimaryButton</member>),
            this does mean that this element's state is not affected by the call - it does
            <em>not</em> mean that it is disabled.
        @param  Enable
            <TRUE/> if the elements denoted by <arg>_nElements</arg> should be enabled, <FALSE/> if
            they should be disabled.
    */
    void    enablePropertyUIElements(
                        [in] string PropertyName,
                        [in] short Elements,
                        [in] boolean Enable
                    );

    /** completely rebuilds the UI for the given property.

        <p>This method might be used by an <type>XPropertyHandler</type> if it wants to change the type
        of control (see <type>PropertyControlType</type>) used to display a certain property.</p>

        <p>The object inspector will then call describePropertyLine again, and update its UI accordingly.</p>

        <p>Note that the property whose UI should be rebuilt must not necessarily be (though usually <em>is</em>)
        in the responsibility of the handler which calls this method. The object inspector will look up the
        handler with the responsibility for <arg>PropertyName</arg> and call its
        <member>XPropertyHandler::describePropertyLine</member></p>

        @param PropertyName
            the name of the property whose UI is to be completely rebuilt.
    */
    void    rebuildPropertyUI( [in] string PropertyName );

    /** shows the UI for a given property

        @param  PropertyName
            the name of the property whose UI is to be shown
    */
    void    showPropertyUI( [in] string PropertyName );

    /** hides the UI for a given property

        @param  PropertyName
            the name of the property whose UI is to be hidden
    */
    void    hidePropertyUI( [in] string PropertyName );

    /** shows or hides all properties belonging to a given category
        @see LineDescriptor::Category
        @see XObjectInspectorModel::describeCategories
    */
    void    showCategory( [in] string Category, [in] boolean Show );

    /** retrieves the control currently used to display a given property

        @param PropertyName
            the name of the property whose control should be retrieved

        @return
            the <type>XPropertyControl</type> representing the given property, or <NULL/>
            if there is no such property control.
    */
    XPropertyControl
            getPropertyControl( [in] string PropertyName );

    /** registers an observer for all property controls

        <p>The given XPropertyControlObserver will be notified of all changes
        in all property controls.</p>

        @see revokeControlObserver

        @since OOo 2.2
    */
    void    registerControlObserver( [in] XPropertyControlObserver Observer );

    /** revokes a previously registered control observer

        @see registerControlObserver

        @since OOo 2.2
    */
    void    revokeControlObserver( [in] XPropertyControlObserver Observer );

    /** sets the text of the help section, if the object inspector contains
        one.

        @throws NoSupportException
            if the <member>XObjectInspectorModel::HasHelpSection</member> property
            requires the help section to be unavailable.

        @since OOo 2.2
    */
    void setHelpSectionText( [in] string HelpText )
        raises ( ::com::sun::star::lang::NoSupportException );
};

//=============================================================================

}; }; }; };

#endif