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/XInitialization.idl>
31#include <com/sun/star/util/XUpdatable.idl>
32
33module com {  module sun {  module star {  module frame {
34
35/** interface to be implemented by a component offering a more complex user
36    interface to users within a status bar.
37
38    <p>
39    A generic status bar field is represented as a simple text field. A status
40    bar controller can be added to a Statusbar and provide information or
41    functions with a more sophisticated user interface.<br/>
42    A typical example for status bar controller is a zoom chooser. It shows
43    the current zoom and provides general zoom levels on a popup menu
44    that can be activated by a mouse action for context menus.
45    <p>
46
47    @see com::sun::star::frame::XDispatchProvider
48
49    @since OOo 2.0
50*/
51interface XStatusbarController
52{
53    /** used to initialize a component with required arguments.
54
55        <p>A status bar controller is initialized with <b>five</b> additional
56        arguments provided as a sequence of
57        <type scope="com::sun::star::beans">PropertyValue</type>:</p>
58
59        <ul>
60            <li><b>Frame</b><br/>a <type scope="com::sun::star::frame">XFrame</type>
61                instance to which the status bar controller belongs.
62            </li>
63            <li><b>CommandURL</b><br/>a string which specifies the command
64                associated with the statusbar controller.</br>
65                The command is used to identify the status bar controller
66                implementation.
67            </li>
68            <li><b>StatusbarItem</b><br/>a <type scope="com::sun::star::ui">XStatusbarItem</type>
69                instance which represents the status bar item asociated with
70                this controller.
71            </li>
72            <li><b>ParentWindow</b><br/>a <type scope="com::sun::star::awt">Window</type>
73                instance which represents the parent window (status bar window).
74            </li>
75            <li><b>ModuleName</b><br/>a string which specifies the name of the
76                office module attached to the frame to which this controller
77                belongs; the value is taken from
78                <member scope="com::sun::star::frame">XModuleManager::identify()</member>.
79            </li>
80        </ul>
81    */
82    interface com::sun::star::lang::XInitialization;
83
84    /** with this interface a component can receive events if a feature has
85        changed.
86
87        <p>The status bar controller implementation should register itself as a
88        listener when its <member scope="com::sun::star::util">XUpdatable</member>
89        interface has been called.</p>
90    */
91    interface com::sun::star::frame::XStatusListener;
92
93    /** used to notify an implementation that it needs to add its listener or
94        remove and add them again.
95
96        <p>
97        A status bar controller instance is ready for use after this call has
98        been made the first time. The status bar implementation guarentees that
99        the controller's item window has been added to the status bar and its
100        reference is held by it.
101        </p>
102    */
103    interface com::sun::star::util::XUpdatable;
104
105    /** is called by a status bar if the mouse position is within the controller
106        and a mouse button has been pressed. If the controller has captured the
107        mouse input this function is also called when the mouse position is not
108        within the controller.
109
110        @param aMouseEvent
111            current information about the mouse pointer.
112
113        @return
114            return <TRUE/> if the event should not be processed and <FALSE/>
115            if the event should be processed by the status bar.
116    */
117    boolean mouseButtonDown( [in] ::com::sun::star::awt::MouseEvent aMouseEvent );
118
119    /** is called by a status bar if the mouse position is within the controller
120        and a mouse has been moved. If the controller has captured the
121        mouse input this function is also called when the mouse position is not
122        within the controller.
123
124        @param aMouseEvent
125            current information about the mouse pointer.
126
127        @return
128            return <TRUE/> if the event should not be processed and <FALSE/>
129            if the event should be processed by the status bar.
130    */
131    boolean mouseMove( [in] ::com::sun::star::awt::MouseEvent aMouseEvent );
132
133    /** is called by a status bar if the mouse position is within the controller
134        and a mouse button has been released. If the controller has captured the
135        mouse input this function is also called when the mouse position is not
136        within the controller.
137
138        @param aMouseEvent
139            current information about the mouse pointer.
140
141        @return
142            return <TRUE/> if the event should not be processed and <FALSE/>
143            if the event should be processed by the status bar.
144    */
145    boolean mouseButtonUp( [in] ::com::sun::star::awt::MouseEvent aMouseEvent );
146
147    /** is called by a status bar if a command event is available for a controller.
148
149        @param aPos
150            the current mouse position in pixel.
151
152        @param nCommand
153            describes which command has been invoked.
154            <br/>See <type scope="com::sun::star::awt">Command</type> for
155            possible values.
156
157        @param bMouseEvent
158            <TRUE/> if the command is based on a mouse event, otherwise <FALSE/>.
159
160        @param aData
161            for future use only.
162    */
163    void command( [in] ::com::sun::star::awt::Point aPos,
164                  [in] long nCommand,
165                  [in] boolean bMouseEvent,
166                  [in] any aData );
167
168    /** is called by a status bar if the controller has to update the visual
169        representation.
170
171        @param xGraphics
172            a reference to a <type scope="com::sun::star::awt">XGraphics</type>
173            which has to be used to update the visual representation.
174
175        @param nCommand
176            a <type scope="com::sun::star::awt">Rectangle</type> which
177            determine the output rectangle for all drawing operations
178
179        @param nStyle
180            reserved for future use.
181    */
182    void paint( [in] ::com::sun::star::awt::XGraphics xGraphics,
183                [in] ::com::sun::star::awt::Rectangle rOutputRectangle,
184                [in] long nStyle );
185
186    /** is called by a status bar if the user clicked with mouse into the
187        field of the corresponding control.
188
189        @param aPos
190            the current mouse position in pixel.
191    */
192    void click( [in] ::com::sun::star::awt::Point aPos );
193
194    /** is called by a status bar if the user double-clicked with mouse
195        into the field of the corresponding control.
196
197        @param aPos
198            the current mouse position in pixel.
199    */
200    void doubleClick( [in] ::com::sun::star::awt::Point aPos );
201};
202
203}; }; }; };
204
205#endif
206