offapi/com/sun/star/awt/XExtendedToolkit.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 #ifndef __com_sun_star_awt_XExtendedToolkit_idl__
  21 #define __com_sun_star_awt_XExtendedToolkit_idl__
  22
  23 #include <com/sun/star/uno/XInterface.idl>
  24 #include <com/sun/star/awt/XTopWindow.idl>
  25 #include <com/sun/star/lang/IndexOutOfBoundsException.idl>
  26 #include <com/sun/star/awt/XTopWindowListener.idl>
  27 #include <com/sun/star/awt/XKeyHandler.idl>
  28 #include <com/sun/star/awt/XFocusListener.idl>
  29
  30
  31
  32 module com {  module sun {  module star {  module awt {
  33
  34
  35 /** The XExtendedToolkit is an extension of the
  36     ::com::sun::star::awt::XToolkit interface.  It basically
  37     provides access to three event broadcasters which are used for instance
  38     in the context of accessibility.  It is, however, not restricted to
  39     accessibility.
  40
  41     <p>The first event broadcaster lets you keep track of the open top-level
  42     windows (frames).  To get the set of currently open top-level window use
  43     the XExtendedToolkit::getTopWindowCount() and
  44     XExtendedToolkit::getTopWindow() methods.</p>
  45
  46     <p>The second event broadcaster informs its listeners of key events.
  47     Its listeners can, unlike with most other broadcasters/listeners,
  48     consume events, so that other listeners will not be called for consumed
  49     events.</p>
  50
  51     <p>The last event broadcaster sends events on focus changes of all
  52     elements that can have the input focus.</p>
  53
  54     @deprecated
  55         This interface was only implemented in an intermediate developer
  56         release anyway.
  57
  58     @since OOo 1.1.2
  59 */
  60 published interface XExtendedToolkit : ::com::sun::star::uno::XInterface
  61 {
  62
  63     /** This function returns the number of currently existing top-level
  64         windows.
  65         @return
  66             Returns the number of top-level windows.  This includes all
  67             top-level windows, regardless of whether they are iconized,
  68             visible, or active.
  69     */
  70     long getTopWindowCount ();
  71
  72
  73     /** Return a reference to the specified top-level window.  Note that the
  74         number of top-level windows may change between a call to
  75         getTopWindowCount() and successive calls to this
  76         function.
  77         @param nIndex
  78             The index should be in the interval from 0 up to but not
  79             including the number of top-level windows as returned by
  80             getTopWindowCount().
  81         @return
  82             The returned value is a valid reference to a top-level window.
  83         @throws IndexOutOfBoundsException
  84            when the specified index is outside the valid range.
  85     */
  86     ::com::sun::star::awt::XTopWindow getTopWindow ([in] long nIndex)
  87         raises (::com::sun::star::lang::IndexOutOfBoundsException);
  88
  89
  90     /** Return the currently active top-level window, i.e. which has
  91         currently the input focus.
  92         @return
  93             The returned reference may be empty when no top-level window is
  94             active.
  95     */
  96     ::com::sun::star::awt::XTopWindow getActiveTopWindow ();
  97
  98     /** Add a new listener that is called for events that involve
  99         ::com::sun::star::awt::XTopWindow.  After having
 100         obtained the current list of existing top-level windows you can
 101         keep this list up-to-date by listening to opened or closed top-level
 102         windows.  Wait for activations or deactivations of top-level windows
 103         to keep track of the currently active frame.
 104         @param xListener
 105             If this is a valid reference it is inserted into the list of
 106             listeners.  It is the task of the caller to not register the
 107             same listener twice (otherwise that listener will be called
 108             twice.)
 109     */
 110     void addTopWindowListener (
 111         [in] ::com::sun::star::awt::XTopWindowListener xListener);
 112
 113
 114     /** Remove the specified listener from the list of listeners.
 115         @param xListener
 116             If the reference is empty then nothing will be changed.  If the
 117             listener has been registered twice (or more) then all references
 118             will be removed.
 119     */
 120     void removeTopWindowListener (
 121         [in] ::com::sun::star::awt::XTopWindowListener xListener);
 122
 123
 124     /** Add a new listener that is called on
 125         ::com::sun::star::awt::KeyEvent.  Every listener is
 126         given the opportunity to consume the event, i.e. prevent the not yet
 127         called listeners from being called.
 128         @param xHandler
 129             If this is a valid reference it is inserted into the list of
 130             handlers.  It is the task of the caller to not register the
 131             same handler twice (otherwise that listener will be called
 132             twice.)
 133     */
 134     void addKeyHandler (
 135         [in] ::com::sun::star::awt::XKeyHandler xHandler);
 136
 137
 138     /** Remove the specified listener from the list of listeners.
 139         @param xHandler
 140             If the reference is empty then nothing will be changed.  If the
 141             handler has been registered twice (or more) then all references
 142             will be removed.
 143     */
 144     void removeKeyHandler (
 145         [in] ::com::sun::star::awt::XKeyHandler xHandler);
 146
 147
 148     /** Add a new listener that is called on
 149         ::com::sun::star::awt::FocusEvent.  Use this focus
 150         broadcaster to keep track of the object that currently has the input
 151         focus.
 152         @param xListener
 153             If this is a valid reference it is inserted into the list of
 154             listeners.  It is the task of the caller to not register the
 155             same listener twice (otherwise that listener will be called
 156             twice.)
 157     */
 158     void addFocusListener (
 159         [in] ::com::sun::star::awt::XFocusListener xListener);
 160
 161
 162     /** Remove the specified listener from the list of listeners.
 163         @param xListener
 164             If the reference is empty then nothing will be changed.  If the
 165             listener has been registered twice (or more) then all references
 166             will be removed.
 167     */
 168     void removeFocusListener (
 169         [in] ::com::sun::star::awt::XFocusListener xListener);
 170
 171
 172     /** Broadcasts the a focusGained on all registered focus listeners
 173         @param source
 174             The object that has gained the input focus. It should implement
 175             com::sun::star::accessibility::XAccessible.
 176     */
 177     void fireFocusGained (
 178         [in] ::com::sun::star::uno::XInterface source);
 179
 180
 181     /** Broadcasts the a focusGained on all registered focus listeners
 182         @param source
 183             The object that has lost the input focus. It should implement
 184             com::sun::star::accessibility::XAccessible.
 185     */
 186     void fireFocusLost (
 187         [in] ::com::sun::star::uno::XInterface source);
 188
 189 };
 190
 191 }; }; }; };
 192
 193 #endif
 194
 195 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */