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