1/**************************************************************
2 *
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements.  See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership.  The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License.  You may obtain a copy of the License at
10 *
11 *   http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied.  See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 *
20 *************************************************************/
21
22#ifndef __com_sun_star_frame_XStatusbarController_idl__
23#define __com_sun_star_frame_XStatusbarController_idl__
24
25#include <com/sun/star/awt/MouseEvent.idl>
26#include <com/sun/star/awt/Point.idl>
27#include <com/sun/star/awt/Rectangle.idl>
28#include <com/sun/star/awt/XGraphics.idl>
29#include <com/sun/star/frame/XStatusListener.idl>
30#include <com/sun/star/lang/XComponent.idl>
31#include <com/sun/star/lang/XInitialization.idl>
32#include <com/sun/star/util/XUpdatable.idl>
33
34module com {  module sun {  module star {  module frame {
35
36/** interface to be implemented by a component offering a more complex user
37    interface to users within a status bar.
38
39    <p>
40    A generic status bar field is represented as a simple text field. A status
41    bar controller can be added to a Statusbar and provide information or
42    functions with a more sophisticated user interface.<br/>
43    A typical example for status bar controller is a zoom chooser. It shows
44    the current zoom and provides general zoom levels on a popup menu
45    that can be activated by a mouse action for context menus.
46    <p>
47
48    @see com::sun::star::frame::XDispatchProvider
49
50    @since OpenOffice 2.0
51*/
52interface XStatusbarController
53{
54    /** used to control the life-time of the component
55
56        Used by a status bar implementation to control the life-time of
57        a status bar controller. The status bar is the only instance which
58        is allowed to dispose the component.
59     */
60    interface com::sun::star::lang::XComponent;
61
62    /** used to initialize a component with required arguments.
63
64        <p>A status bar controller is initialized with <b>five</b> additional
65        arguments provided as a sequence of
66        <type scope="com::sun::star::beans">PropertyValue</type>:</p>
67
68        <ul>
69            <li><b>Frame</b><br/>a <type scope="com::sun::star::frame">XFrame</type>
70                instance to which the status bar controller belongs.
71            </li>
72            <li><b>CommandURL</b><br/>a string which specifies the command
73                associated with the statusbar controller.</br>
74                The command is used to identify the status bar controller
75                implementation.
76            </li>
77            <li><b>StatusbarItem</b><br/>a <type scope="com::sun::star::ui">XStatusbarItem</type>
78                instance which represents the status bar item associated with
79                this controller.
80            </li>
81            <li><b>ParentWindow</b><br/>a <type scope="com::sun::star::awt">Window</type>
82                instance which represents the parent window (status bar window).
83            </li>
84            <li><b>ModuleName</b><br/>a string which specifies the name of the
85                office module attached to the frame to which this controller
86                belongs; the value is taken from
87                <member scope="com::sun::star::frame">XModuleManager::identify()</member>.
88            </li>
89        </ul>
90    */
91    interface com::sun::star::lang::XInitialization;
92
93    /** with this interface a component can receive events if a feature has
94        changed.
95
96        <p>The status bar controller implementation should register itself as a
97        listener when its <member scope="com::sun::star::util">XUpdatable</member>
98        interface has been called.</p>
99    */
100    interface com::sun::star::frame::XStatusListener;
101
102    /** used to notify an implementation that it needs to add its listener or
103        remove and add them again.
104
105        <p>
106        A status bar controller instance is ready for use after this call has
107        been made the first time. The status bar implementation guarantees that
108        the controller's item window has been added to the status bar and its
109        reference is held by it.
110        </p>
111    */
112    interface com::sun::star::util::XUpdatable;
113
114    /** is called by a status bar if the mouse position is within the controller
115        and a mouse button has been pressed. If the controller has captured the
116        mouse input this function is also called when the mouse position is not
117        within the controller.
118
119        @param aMouseEvent
120            current information about the mouse pointer.
121
122        @return
123            return <TRUE/> if the event should not be processed and <FALSE/>
124            if the event should be processed by the status bar.
125    */
126    boolean mouseButtonDown( [in] ::com::sun::star::awt::MouseEvent aMouseEvent );
127
128    /** is called by a status bar if the mouse position is within the controller
129        and a mouse has been moved. If the controller has captured the
130        mouse input this function is also called when the mouse position is not
131        within the controller.
132
133        @param aMouseEvent
134            current information about the mouse pointer.
135
136        @return
137            return <TRUE/> if the event should not be processed and <FALSE/>
138            if the event should be processed by the status bar.
139    */
140    boolean mouseMove( [in] ::com::sun::star::awt::MouseEvent aMouseEvent );
141
142    /** is called by a status bar if the mouse position is within the controller
143        and a mouse button has been released. If the controller has captured the
144        mouse input this function is also called when the mouse position is not
145        within the controller.
146
147        @param aMouseEvent
148            current information about the mouse pointer.
149
150        @return
151            return <TRUE/> if the event should not be processed and <FALSE/>
152            if the event should be processed by the status bar.
153    */
154    boolean mouseButtonUp( [in] ::com::sun::star::awt::MouseEvent aMouseEvent );
155
156    /** is called by a status bar if a command event is available for a controller.
157
158        @param aPos
159            the current mouse position in pixel.
160
161        @param nCommand
162            describes which command has been invoked.
163            <br/>See <type scope="com::sun::star::awt">Command</type> for
164            possible values.
165
166        @param bMouseEvent
167            <TRUE/> if the command is based on a mouse event, otherwise <FALSE/>.
168
169        @param aData
170            for future use only.
171    */
172    void command( [in] ::com::sun::star::awt::Point aPos,
173                  [in] long nCommand,
174                  [in] boolean bMouseEvent,
175                  [in] any aData );
176
177    /** is called by a status bar if the controller has to update the visual
178        representation.
179
180        @param xGraphics
181            a reference to a <type scope="com::sun::star::awt">XGraphics</type>
182            which has to be used to update the visual representation.
183
184        @param nCommand
185            a <type scope="com::sun::star::awt">Rectangle</type> which
186            determine the output rectangle for all drawing operations
187
188        @param nStyle
189            reserved for future use.
190    */
191    void paint( [in] ::com::sun::star::awt::XGraphics xGraphics,
192                [in] ::com::sun::star::awt::Rectangle rOutputRectangle,
193                [in] long nStyle );
194
195    /** is called by a status bar if the user clicked with mouse into the
196        field of the corresponding control.
197
198        @param aPos
199            the current mouse position in pixel.
200    */
201    void click( [in] ::com::sun::star::awt::Point aPos );
202
203    /** is called by a status bar if the user double-clicked with mouse
204        into the field of the corresponding control.
205
206        @param aPos
207            the current mouse position in pixel.
208    */
209    void doubleClick( [in] ::com::sun::star::awt::Point aPos );
210};
211
212}; }; }; };
213
214#endif
215