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