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