offapi/com/sun/star/awt/XExtendedToolkit.idl

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XExtendedToolkit.idl,v $
  10  * $Revision: 1.10 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30
  31 #ifndef __com_sun_star_awt_XExtendedToolkit_idl__
  32 #define __com_sun_star_awt_XExtendedToolkit_idl__
  33
  34 #ifndef __com_sun_star_uno_XInterface_idl__
  35 #include <com/sun/star/uno/XInterface.idl>
  36 #endif
  37
  38 #ifndef __com_sun_star_awt_XTopWindow_idl__
  39 #include <com/sun/star/awt/XTopWindow.idl>
  40 #endif
  41
  42 #ifndef __com_sun_star_lang_IndexOutOfBoundsException_idl__
  43 #include <com/sun/star/lang/IndexOutOfBoundsException.idl>
  44 #endif
  45
  46 #ifndef __com_sun_star_awt_XTopWindowListener_idl__
  47 #include <com/sun/star/awt/XTopWindowListener.idl>
  48 #endif
  49
  50 #ifndef __com_sun_star_awt_XKeyHandler_idl__
  51 #include <com/sun/star/awt/XKeyHandler.idl>
  52 #endif
  53
  54 #ifndef __com_sun_star_awt_XFocusListener_idl__
  55 #include <com/sun/star/awt/XFocusListener.idl>
  56 #endif
  57
  58
  59 //=============================================================================
  60
  61 module com {  module sun {  module star {  module awt {
  62
  63 //=============================================================================
  64
  65 /** The <type>XExtendedToolkit</type> is an extension of the <type
  66     scope="::com::sun::star::awt">XToolkit</type> interface.  It basically
  67     provides access to three event broadcasters which are used for instance
  68     in the context of accessibility.  It is, however, not restricted to
  69     accessibility.
  70
  71     <p>The first event broadcaster lets you keep track of the open top-level
  72     windows (frames).  To get the set of currently open top-level window use
  73     the <member>XExtendedToolkit::getTopWindowCount</member> and
  74     <member>XExtendedToolkit::getTopWindow</member> methods.</p>
  75
  76     <p>The second event broadcaster informs its listeners of key events.
  77     Its listeners can, unlike with most other broadcasters/listeners,
  78     consume events, so that other listeners will not be called for consumed
  79     events.</p>
  80
  81     <p>The last event broadcaster sends events on focus changes of all
  82     elements that can have the input focus.</p>
  83
  84     @deprecated
  85         This interface was only implemented in an intermediate developer
  86         release anyway.
  87
  88     @since OOo 1.1.2
  89 */
  90 published interface XExtendedToolkit : ::com::sun::star::uno::XInterface
  91 {
  92     //-------------------------------------------------------------------------
  93
  94     /** This function returns the number of currently existing top-level
  95         windows.
  96         @return
  97             Returns the number of top-level windows.  This includes all
  98             top-level windows, regardless of whether they are iconized,
  99             visible, or active.
 100     */
 101     long getTopWindowCount ();
 102
 103     //-------------------------------------------------------------------------
 104
 105     /** Return a reference to the specified top-level window.  Note that the
 106         number of top-level windows may change between a call to
 107         <member>getTopWindowCount()</member> and successive calls to this
 108         function.
 109         @param nIndex
 110             The index should be in the intervall from 0 up to but not
 111             including the number of top-level windows as returned by
 112             <member>getTopWindowCount()</member>.
 113         @return
 114             The returned value is a valid reference to a top-level window.
 115         @throws IndexOutOfBoundsException
 116            when the specified index is outside the valid range.
 117     */
 118     ::com::sun::star::awt::XTopWindow getTopWindow ([in] long nIndex)
 119         raises (::com::sun::star::lang::IndexOutOfBoundsException);
 120
 121     //-------------------------------------------------------------------------
 122
 123     /** Return the currently active top-level window, i.e. which has
 124         currently the input focus.
 125         @return
 126             The returned reference may be empty when no top-level window is
 127             active.
 128     */
 129     ::com::sun::star::awt::XTopWindow getActiveTopWindow ();
 130
 131     /** Add a new listener that is called for events that involve <type
 132         scope="::com::sun::star::awt">XTopWindow</type>s.  After having
 133         obtained the current list of exisiting top-level windows you can
 134         keep this list up-to-date by listening to opened or closed top-level
 135         windows.  Wait for activations or deactivations of top-level windows
 136         to keep track of the currently active frame.
 137         @param xListener
 138             If this is a valid reference it is inserted into the list of
 139             listeners.  It is the task of the caller to not register the
 140             same listener twice (otherwise that listener will be called
 141             twice.)
 142     */
 143     [oneway] void addTopWindowListener (
 144         [in] ::com::sun::star::awt::XTopWindowListener xListener);
 145
 146     //-------------------------------------------------------------------------
 147
 148     /** Remove the specified listener from the list of listeners.
 149         @param xListener
 150             If the reference is empty then nothing will be changed.  If the
 151             listener has been registered twice (or more) then all refrences
 152             will be removed.
 153     */
 154     [oneway] void removeTopWindowListener (
 155         [in] ::com::sun::star::awt::XTopWindowListener xListener);
 156
 157     //-------------------------------------------------------------------------
 158
 159     /** Add a new listener that is called on <type
 160         scope="::com::sun::star::awt">KeyEvent</type>s.  Every listener is
 161         given the opportunity to consume the event, i.e. prevent the not yet
 162         called listeners from being called.
 163         @param xHandler
 164             If this is a valid reference it is inserted into the list of
 165             handlers.  It is the task of the caller to not register the
 166             same handler twice (otherwise that listener will be called
 167             twice.)
 168     */
 169     [oneway] void addKeyHandler (
 170         [in] ::com::sun::star::awt::XKeyHandler xHandler);
 171
 172     //-------------------------------------------------------------------------
 173
 174     /** Remove the specified listener from the list of listeners.
 175         @param xHandler
 176             If the reference is empty then nothing will be changed.  If the
 177             handler has been registered twice (or more) then all refrences
 178             will be removed.
 179     */
 180     [oneway] void removeKeyHandler (
 181         [in] ::com::sun::star::awt::XKeyHandler xHandler);
 182
 183     //-------------------------------------------------------------------------
 184
 185     /** Add a new listener that is called on <type
 186         scope="::com::sun::star::awt">FocusEvent</type>s.  Use this focus
 187         broadcaster to keep track of the object that currently has the input
 188         focus.
 189         @param xListener
 190             If this is a valid reference it is inserted into the list of
 191             listeners.  It is the task of the caller to not register the
 192             same listener twice (otherwise that listener will be called
 193             twice.)
 194     */
 195     [oneway] void addFocusListener (
 196         [in] ::com::sun::star::awt::XFocusListener xListener);
 197
 198     //-------------------------------------------------------------------------
 199
 200     /** Remove the specified listener from the list of listeners.
 201         @param xListener
 202             If the reference is empty then nothing will be changed.  If the
 203             listener has been registered twice (or more) then all refrences
 204             will be removed.
 205     */
 206     [oneway] void removeFocusListener (
 207         [in] ::com::sun::star::awt::XFocusListener xListener);
 208
 209     //-------------------------------------------------------------------------
 210
 211     /** Broadcasts the a focusGained on all registered focus listeners
 212         @param source
 213             The object that has gained the input focus. It should implement
 214             <type scope="com::sun::star::accessibility">XAccessible</type>.
 215     */
 216     [oneway] void fireFocusGained (
 217         [in] ::com::sun::star::uno::XInterface source);
 218
 219     //-------------------------------------------------------------------------
 220
 221     /** Broadcasts the a focusGained on all registered focus listeners
 222         @param source
 223             The object that has lost the input focus. It should implement
 224             <type scope="com::sun::star::accessibility">XAccessible</type>.
 225     */
 226     [oneway] void fireFocusLost (
 227         [in] ::com::sun::star::uno::XInterface source);
 228
 229 };
 230
 231 }; }; }; };
 232
 233 #endif