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