/*************************************************************************
 *
 *  OpenOffice.org - a multi-platform office productivity suite
 *
 *  $RCSfile: ToolbarController.idl,v $
 *
 *  $Revision: 1.7 $
 *
 *  last change: $Author: rt $ $Date: 2005/09/08 01:06:41 $
 *
 *  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_frame_ToolbarController_idl__
#define __com_sun_star_frame_ToolbarController_idl__

#ifndef __com_sun_star_lang_XInitialization_idl__
#include <com/sun/star/lang/XInitialization.idl>
#endif

#ifndef __com_sun_star_util_XUpdatable_idl__
#include <com/sun/star/util/XUpdatable.idl>
#endif

#ifndef __com_sun_star_frame_XStatusListener_idl__
#include <com/sun/star/frame/XStatusListener.idl>
#endif

#ifndef __com_sun_star_frame_XToolbarController_idl__
#include <com/sun/star/frame/XToolbarController.idl>
#endif

#ifndef __com_sun_star_frame_XSubToolbarController_idl__
#include <com/sun/star/frame/XSubToolbarController.idl>
#endif

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

 module com {  module sun {  module star {  module frame {

//=============================================================================
/** is an abstract service for a component which offers a more complex user 
    interface to users within a toolbar.

    <p>
    A generic toolbar function is represented as a button which has a state 
    (enabled,disabled and selected, not selected). A toolbar controller can 
    be added to a toolbar and provide information or functions within a more 
    sophisticated user interface.<br/> A typical example for toolbar controller 
    is the font chooser within the toolbar. It provides all available fonts in 
    a dropdown box and shows the current chosen font.
    <p>

    @see com::sun::star::frame::XDispatchProvider

    @since OOo 2.0.0
 */

service ToolbarController
{
    //-------------------------------------------------------------------------
    /** with this interface a component can receive events if a feature has 
        changed.

        <p>
        The toolbar controller implementation should register itself as a 
        listener when its <member scope="com::sun::star::util">XUpdatable</member> 
        interface has been called.
        </p>
     */
    interface com::sun::star::frame::XStatusListener;

    /** used to initialize a component with required arguments.

        A toolbar controller needs at least three additional arguments 
        provided as <type scope="com::sun::star::beans">PropertyValue</type>:
        <ul>
            <li><b>Frame</b><br>a <type scope="com::sun::star::frame">XFrame</type> 
                   instance to which the toolbar controller belongs.</li>
            <li><b>CommandURL</b><br>a string which specifies the command a 
                   toolbar controller is bound.</li>
            <li><b>ServiceManager</b><br>a 
                   <type scope="com::sun::star::lang">XMultiServiceFactory</type>
                   instance which can be used to create additional UNO services.</li>
        </ul>
    */
    interface com::sun::star::lang::XInitialization;

    /** used to notify an implementation that it needs to add its listener or remove 
        and add them again.

        <p>
        A toolbar controller instance is ready for use after this call has been made 
        the first time. The toolbar implementation guarentees that the controller's 
        item window has been added to the toolbar and its reference is held by it.
        </p>
    */
    interface com::sun::star::util::XUpdatable;

    //-------------------------------------------------------------------------
    /** used to notify changed features and requests for additional user interface 
        items.

        <p>
        Mostly used by a toolbar implementation to forward information to and request
        services from a toolbar controller component. This interface must be useable 
        after <member scope="com::sun::star::lang">XInitialitation::initialize</member> 
        has been called.  The behavior of the interface is undefined if the controller 
        component hasn't been initialized.
        </p>
     */
    interface com::sun::star::frame::XToolbarController;

    //-------------------------------------------------------------------------
    /** used to notify and retrieve information that are specific for sub-toolbar 
        controllers.

        <p>
        Used by implementations that want to provide the toolbar button/sub-
        toolbar function feature. A controller supporting this interface exchanges 
        the function of its own toolbar button, that opened the sub-toolbar, with 
        the one that has been selected on the sub-toolbar.
        </p>
     */
    [optional] interface ::com::sun::star::frame::XSubToolbarController;
};

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

}; }; }; };

#endif
