offapi/com/sun/star/frame/XStatusbarController.idl

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