/* -*- 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_XObjectInspectorUI_idl__
#define __com_sun_star_inspection_XObjectInspectorUI_idl__

#include <com/sun/star/inspection/XPropertyControl.idl>
#include <com/sun/star/beans/Optional.idl>
#include <com/sun/star/container/NoSuchElementException.idl>
#include <com/sun/star/lang/NoSupportException.idl>

module com {  module sun {  module star {  module inspection {

interface XPropertyControlObserver;

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

    <p>This interface is used as callback for XPropertyHandlers.</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 ObjectInspector 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
*/
interface XObjectInspectorUI
{
    /** enables or disables all components belonging to the UI representation of a property

        <p>This is usually used by an XPropertyHandler 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, enablePropertyUIElements() does not have any effect if
        somebody previously disabled the complete UI for this property with enablePropertyUI().</p>

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

        @param  Elements
            a combination of PropertyLineElement flags specifying which elements are to be
            enabled or disabled.<br/>
            Note that if you don't set a particular bit here (say, PropertyLineElement::PrimaryButton),
            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 _nElements 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 XPropertyHandler if it wants to change the type
        of control (see PropertyControlType) 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 PropertyName and call its
        XPropertyHandler::describePropertyLine()</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 XPropertyControl 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 XObjectInspectorModel::HasHelpSection property
            requires the help section to be unavailable.

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


}; }; }; };

#endif

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