xref: /AOO41X/main/offapi/com/sun/star/frame/XStatusbarController.idl (revision c4dc0a1aba8e7aaa49e08ea6b3b605484dad910b)

/**************************************************************
 *
 * 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_frame_XStatusbarController_idl__
#define __com_sun_star_frame_XStatusbarController_idl__

#include <com/sun/star/awt/MouseEvent.idl>
#include <com/sun/star/awt/Point.idl>
#include <com/sun/star/awt/Rectangle.idl>
#include <com/sun/star/awt/XGraphics.idl>
#include <com/sun/star/frame/XStatusListener.idl>
#include <com/sun/star/lang/XComponent.idl>
#include <com/sun/star/lang/XInitialization.idl>
#include <com/sun/star/util/XUpdatable.idl>

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

/** interface to be implemented by a component offering a more complex user
    interface to users within a status bar.

    <p>
    A generic status bar field is represented as a simple text field. A status
    bar controller can be added to a Statusbar and provide information or
    functions with a more sophisticated user interface.<br/>
    A typical example for status bar controller is a zoom chooser. It shows
    the current zoom and provides general zoom levels on a popup menu
    that can be activated by a mouse action for context menus.
    <p>

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

    @since OpenOffice 2.0
*/
interface XStatusbarController
{
    /** used to control the life-time of the component

        Used by a status bar implementation to control the life-time of
        a status bar controller. The status bar is the only instance which
        is allowed to dispose the component.
     */
    interface com::sun::star::lang::XComponent;

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

        <p>A status bar controller is initialized with <b>five</b> additional
        arguments provided as a sequence of
        <type scope="com::sun::star::beans">PropertyValue</type>:</p>

        <ul>
            <li><b>Frame</b><br/>a <type scope="com::sun::star::frame">XFrame</type>
                instance to which the status bar controller belongs.
            </li>
            <li><b>CommandURL</b><br/>a string which specifies the command
                associated with the statusbar controller.</br>
                The command is used to identify the status bar controller
                implementation.
            </li>
            <li><b>StatusbarItem</b><br/>a <type scope="com::sun::star::ui">XStatusbarItem</type>
                instance which represents the status bar item asociated with
                this controller.
            </li>
            <li><b>ParentWindow</b><br/>a <type scope="com::sun::star::awt">Window</type>
                instance which represents the parent window (status bar window).
            </li>
            <li><b>ModuleName</b><br/>a string which specifies the name of the
                office module attached to the frame to which this controller
                belongs; the value is taken from
                <member scope="com::sun::star::frame">XModuleManager::identify()</member>.
            </li>
        </ul>
    */
    interface com::sun::star::lang::XInitialization;

    /** with this interface a component can receive events if a feature has
        changed.

        <p>The status bar 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 notify an implementation that it needs to add its listener or
        remove and add them again.

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

    /** is called by a status bar if the mouse position is within the controller
        and a mouse button has been pressed. If the controller has captured the
        mouse input this function is also called when the mouse position is not
        within the controller.

        @param aMouseEvent
            current information about the mouse pointer.

        @return
            return <TRUE/> if the event should not be processed and <FALSE/>
            if the event should be processed by the status bar.
    */
    boolean mouseButtonDown( [in] ::com::sun::star::awt::MouseEvent aMouseEvent );

    /** is called by a status bar if the mouse position is within the controller
        and a mouse has been moved. If the controller has captured the
        mouse input this function is also called when the mouse position is not
        within the controller.

        @param aMouseEvent
            current information about the mouse pointer.

        @return
            return <TRUE/> if the event should not be processed and <FALSE/>
            if the event should be processed by the status bar.
    */
    boolean mouseMove( [in] ::com::sun::star::awt::MouseEvent aMouseEvent );

    /** is called by a status bar if the mouse position is within the controller
        and a mouse button has been released. If the controller has captured the
        mouse input this function is also called when the mouse position is not
        within the controller.

        @param aMouseEvent
            current information about the mouse pointer.

        @return
            return <TRUE/> if the event should not be processed and <FALSE/>
            if the event should be processed by the status bar.
    */
    boolean mouseButtonUp( [in] ::com::sun::star::awt::MouseEvent aMouseEvent );

    /** is called by a status bar if a command event is available for a controller.

        @param aPos
            the current mouse position in pixel.

        @param nCommand
            describes which command has been invoked.
            <br/>See <type scope="com::sun::star::awt">Command</type> for
            possible values.

        @param bMouseEvent
            <TRUE/> if the command is based on a mouse event, otherwise <FALSE/>.

        @param aData
            for future use only.
    */
    void command( [in] ::com::sun::star::awt::Point aPos,
                  [in] long nCommand,
                  [in] boolean bMouseEvent,
                  [in] any aData );

    /** is called by a status bar if the controller has to update the visual
        representation.

        @param xGraphics
            a reference to a <type scope="com::sun::star::awt">XGraphics</type>
            which has to be used to update the visual representation.

        @param nCommand
            a <type scope="com::sun::star::awt">Rectangle</type> which
            determine the output rectangle for all drawing operations

        @param nStyle
            reserved for future use.
    */
    void paint( [in] ::com::sun::star::awt::XGraphics xGraphics,
                [in] ::com::sun::star::awt::Rectangle rOutputRectangle,
                [in] long nStyle );

    /** is called by a status bar if the user clicked with mouse into the
        field of the corresponding control.

        @param aPos
            the current mouse position in pixel.
    */
    void click( [in] ::com::sun::star::awt::Point aPos );

    /** is called by a status bar if the user double-clicked with mouse
        into the field of the corresponding control.

        @param aPos
            the current mouse position in pixel.
    */
    void doubleClick( [in] ::com::sun::star::awt::Point aPos );
};

}; }; }; };

#endif