| author | ohair |
| Wed, 06 Apr 2011 22:06:11 -0700 | |
| changeset 9035 | 1255eb81cc2f |
| parent 8132 | 8686fda1829a |
| child 21254 | f6d36ee3f269 |
| permissions | -rw-r--r-- |
| 2 | 1 |
<!-- |
|
9035
1255eb81cc2f
7033660: Update copyright year to 2011 on any files changed in 2011
ohair
parents:
8132
diff
changeset
|
2 |
Copyright (c) 2001, 2011, Oracle and/or its affiliates. All rights reserved. |
| 2 | 3 |
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
4 |
||
5 |
This code is free software; you can redistribute it and/or modify it |
|
6 |
under the terms of the GNU General Public License version 2 only, as |
|
| 5506 | 7 |
published by the Free Software Foundation. Oracle designates this |
| 2 | 8 |
particular file as subject to the "Classpath" exception as provided |
| 5506 | 9 |
by Oracle in the LICENSE file that accompanied this code. |
| 2 | 10 |
|
11 |
This code is distributed in the hope that it will be useful, but WITHOUT |
|
12 |
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
13 |
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
14 |
version 2 for more details (a copy is included in the LICENSE file that |
|
15 |
accompanied this code). |
|
16 |
||
17 |
You should have received a copy of the GNU General Public License version |
|
18 |
2 along with this work; if not, write to the Free Software Foundation, |
|
19 |
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
20 |
||
| 5506 | 21 |
Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
22 |
or visit www.oracle.com if you need additional information or have any |
|
23 |
questions. |
|
| 2 | 24 |
--> |
25 |
||
26 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> |
|
27 |
||
28 |
<html> |
|
29 |
<head> |
|
30 |
<title align=center>The AWT Focus Subsystem</title> |
|
31 |
</head> |
|
32 |
||
33 |
<body bgcolor="white"> |
|
34 |
<h1 align=center>The AWT Focus Subsystem</h1> |
|
35 |
||
36 |
<p> |
|
37 |
Prior to Java 2 Standard Edition, JDK 1.4, the AWT focus subsystem |
|
38 |
was inadequate. It suffered from major design and API problems, |
|
39 |
as well as over a hundred open bugs. Many of these bugs were caused by |
|
40 |
platform inconsistencies, or incompatibilities between the native |
|
41 |
focus system for heavyweights and the Java focus system for |
|
42 |
lightweights. |
|
43 |
<p> |
|
44 |
The single worst problem with the AWT focus implementation was the |
|
45 |
inability to query for the currently focused Component. Not only was |
|
46 |
there no API for such a query, but also, because of an insufficient |
|
47 |
architecture, such information was not even maintained by the code. |
|
48 |
<p> |
|
49 |
Almost as bad was the inability of lightweight children of a Window |
|
50 |
(not a Frame or a Dialog) to receive keyboard input. This problem |
|
51 |
existed because Windows never received <code>WINDOW_ACTIVATED</code> |
|
52 |
events and thus could never be activated, and only active Windows |
|
53 |
could contain focused Components. |
|
54 |
<p> |
|
55 |
In addition, many developers noted that the APIs for FocusEvent and |
|
56 |
WindowEvent were insufficient because they did not provide a way for |
|
57 |
determining the "opposite" Component involved in the focus or |
|
58 |
activation change. For example, when a Component received a FOCUS_LOST |
|
59 |
event, it had no way of knowing which Component was gaining |
|
60 |
focus. Since Microsoft Windows provides this functionality for free, |
|
61 |
developers migrating from Microsoft Windows C/C++ or Visual Basic to |
|
62 |
Java had been frustrated by the omission. |
|
63 |
<p> |
|
64 |
To address these and other deficiencies, we have designed a new focus |
|
65 |
model for the AWT in JDK 1.4. The primary design changes were the |
|
66 |
construction of a new centralized KeyboardFocusManager class, and a |
|
67 |
lightweight focus architecture. The amount of focus-related, |
|
68 |
platform-dependent code has been minimized and replaced by fully |
|
69 |
pluggable and extensible public APIs in the AWT. While we have |
|
70 |
attempted to remain backward compatible with the existing |
|
71 |
implementation, we were forced to make minor incompatible changes in |
|
72 |
order to reach an elegant and workable conclusion. We anticipate that |
|
73 |
these incompatibilities will have only a trivial impact on existing |
|
74 |
applications. |
|
75 |
<p> |
|
76 |
This document is a formal specification both of the new APIs and of |
|
77 |
existing APIs which remain relevant in the new model. Combined with |
|
78 |
the javadoc for focus-related classes and methods, this document |
|
79 |
should enable developers to create substantial AWT and Swing |
|
80 |
applications with a focus behavior that is customized yet consistent |
|
81 |
across platforms. This document has the following sections: |
|
82 |
<ul> |
|
83 |
<li><a href=#Overview>Overview of KeyboardFocusManager</a> |
|
84 |
<li><a href=#BrowserContexts>KeyboardFocusManager and Browser Contexts</a> |
|
85 |
<li><a href=#KeyEventDispatcher>KeyEventDispatcher</a> |
|
86 |
<li><a href=#FocusEventAndWindowEvent>FocusEvent and WindowEvent</a> |
|
87 |
<li><a href=#EventDelivery>Event Delivery</a> |
|
88 |
<li><a href=#OppositeComponents>Opposite Components and Windows</a> |
|
89 |
<li><a href=#TemporaryFocusEvents>Temporary FocusEvents</a> |
|
90 |
<li><a href=#FocusTraversal>Focus Traversal</a> |
|
91 |
<li><a href=#FocusTraversalPolicy>Focus Traversal Policy</a> |
|
92 |
<li><a href=#FocusTraversalPolicyProviders>Focus Traversal Policy Providers</a> |
|
93 |
<li><a href=#ProgrammaticTraversal>Programmatic Traversal</a> |
|
94 |
<li><a href=#Focusability>Focusability</a> |
|
95 |
<li><a href=#FocusableWindows>Focusable Windows</a> |
|
96 |
<li><a href=#RequestingFocus>Requesting Focus</a> |
|
97 |
<li><a href=#FocusAndPropertyChangeListener>Focus and PropertyChangeListener</a> |
|
98 |
<li><a href=#FocusAndVetoableChangeListener>Focus and VetoableChangeListener</a> |
|
99 |
<li><a href=#ZOrder>Z-Order</a> |
|
100 |
<li><a href=#ReplacingDefaultKeyboardFocusManager>Replacing DefaultKeyboardFocusManager</a> |
|
101 |
<li><a href=#Incompatibilities>Incompatibilities with Previous Releases</a> |
|
102 |
</ul> |
|
103 |
||
104 |
<a name="Overview"></a> |
|
105 |
<h3>Overview of KeyboardFocusManager</h3> |
|
106 |
<p> |
|
107 |
The focus model is centralized around a single class, |
|
108 |
KeyboardFocusManager, that provides a set of APIs for client code to |
|
109 |
inquire about the current focus state, initiate focus changes, and |
|
110 |
replace default focus event dispatching with a custom dispatcher. |
|
111 |
Clients can inquire about the focus state directly, or can register a |
|
112 |
PropertyChangeListener that will receive PropertyChangeEvents when a |
|
113 |
change to the focus state occurs. |
|
114 |
<p> |
|
115 |
KeyboardFocusManager introduces the following main concepts and their |
|
116 |
terminology: |
|
117 |
<ol> |
|
118 |
<li>The "focus owner" -- the Component which typically receives |
|
119 |
keyboard input. |
|
120 |
<li>The "permanent focus owner" -- the last Component to receive |
|
121 |
focus permanently. The "focus owner" and the "permanent focus |
|
122 |
owner" are equivalent unless a temporary focus change is |
|
123 |
currently in effect. In such a situation, the "permanent focus |
|
124 |
owner" will again be the "focus owner" when the temporary focus |
|
125 |
change ends. |
|
126 |
<li>The "focused Window" -- the Window which contains the "focus |
|
127 |
owner". |
|
128 |
<li>The "active Window" -- the Frame or Dialog that is either the |
|
129 |
"focused Window", or the first Frame or Dialog that is an owner |
|
130 |
of the "focused Window". |
|
131 |
<li>"Focus traversal" -- the user's ability to change the "focus |
|
132 |
owner" without moving the cursor. Typically, this is done using |
|
133 |
the keyboard (for example, by using the TAB key), or an |
|
134 |
equivalent device in an accessible environment. Client code can |
|
135 |
also initiate traversal programmatically. Normal focus traversal |
|
136 |
can be either "forward" to the "next" Component, or "backward" to |
|
137 |
the "previous" Component. |
|
138 |
<li>"Focus traversal cycle" -- a portion of the Component hierarchy, |
|
139 |
such that normal focus traversal "forward" (or "backward") will |
|
140 |
traverse through all of the Components in the focus cycle, but no |
|
141 |
other Components. This cycle provides a mapping from an arbitrary |
|
142 |
Component in the cycle to its "next" (forward traversal) and |
|
143 |
"previous" (backward traversal) Components. |
|
144 |
<li>"Traversable Component" -- Component that is in the focus traversal |
|
145 |
cycle. |
|
146 |
<li>"Non-traversable Component" -- Component that is not in the focus |
|
147 |
traversal cycle. Note that a non-traversable Component can nevertheless |
|
148 |
be focused in other way (e.g. by direct focus request). |
|
149 |
<li>"Focus cycle root" -- Container that is the root of the Component |
|
150 |
hierarchy for a particular "focus traversal cycle". When the |
|
151 |
"focus owner" is a Component inside a particular cycle, normal |
|
152 |
forward and backward focus traversal cannot move the "focus |
|
153 |
owner" above the focus cycle root in the Component hierarchy. |
|
154 |
Instead, two additional traversal operations, "up cycle" and |
|
155 |
"down cycle", are defined to allow keyboard and programmatic |
|
156 |
navigation up and down the focus traversal cycle hierarchy. </li> |
|
157 |
<li>"Focus traversal policy provider" - Container which has |
|
158 |
"FocusTraversalPolicyProvider" property as true. This Container will |
|
159 |
be used to acquire focus traversal policy. This container doesn't |
|
160 |
define new focus cycle but only modifies the order by which its |
|
161 |
children are traversed "forward" and "backward". Focus traversal |
|
162 |
policy provider can be set using |
|
163 |
<code>setFocusTraversalPolicyProvider</code> on the Container. |
|
164 |
</ol> |
|
165 |
||
166 |
<p> |
|
167 |
Every Window and JInternalFrame is, by default, a "focus cycle |
|
168 |
root". If it's the only focus cycle root, then all of its |
|
169 |
focusable descendants should be in its focus cycle, and its focus |
|
170 |
traversal policy should enforce that they are by making sure that |
|
171 |
all will be reached during normal forward (or backward) |
|
172 |
traversal. If, on the other hand, the Window or JInternalFrame |
|
173 |
has descendants that are also focus cycle roots, then each such |
|
174 |
descendant is a member of two focus cycles: the one that it is |
|
175 |
the root of, and the one of its nearest focus-cycle-root |
|
176 |
ancestor. In order to traverse the focusable components belonging |
|
177 |
to the focus cycle of such a "descendant" focus cycle root, one |
|
178 |
first traverses (forward or backward) to reach the descendant, |
|
179 |
and then uses the "down cycle" operation to reach, in turn, its |
|
180 |
descendants. |
|
181 |
||
182 |
<p> |
|
183 |
Here is an example:<br> <img src="FocusCycle.gif" align=middle |
|
184 |
alt="Three groups as described below: ABCF BDE and DGH. "><br> |
|
185 |
||
186 |
<p>Assume the following: |
|
187 |
<ul> |
|
188 |
<li><b>A</b> is a <code>Window</code>, which means that it |
|
189 |
must be a focus cycle root. |
|
190 |
<li><b>B</b> and <b>D</b> are <code>Container</code>s that |
|
191 |
are focus cycle roots. |
|
192 |
<li><b>C</b> is a <code>Container</code> that is not a focus cycle root. |
|
193 |
<li><b>G</b>, <b>H</b>, <b>E</b>, and <b>F</b> are all |
|
194 |
<code>Component</code>s. |
|
195 |
</ul> |
|
196 |
||
197 |
There are a total of three focus cycle roots in this example: |
|
198 |
||
199 |
<ol> |
|
200 |
<li><b>A</b> is a root, and <b>A</b>, <b>B</b>, <b>C</b>, |
|
201 |
and <b>F</b> are members of <b>A</b>'s cycle. |
|
202 |
<li><b>B</b> is a root, and <b>B</b>, <b>D</b>, and |
|
203 |
<b>E</b> are members of <b>B</b>'s cycle. |
|
204 |
<li><b>D</b> is a root, and <b>D</b>, <b>G</b>, |
|
205 |
and <b>H</b> are members of <b>D</b>'s cycle. |
|
206 |
</ol> |
|
207 |
||
208 |
Windows are the only Containers which, by default, are focus cycle |
|
209 |
roots. |
|
210 |
||
211 |
||
212 |
<code>KeyboardFocusManager</code> is an abstract class. AWT provides a default |
|
213 |
implementation in the <code>DefaultKeyboardFocusManager</code> class. |
|
214 |
||
215 |
||
216 |
<a name="BrowserContexts"></a> |
|
217 |
<h3>KeyboardFocusManager and Browser Contexts</h3> |
|
218 |
<p> |
|
219 |
Some browsers partition applets in different code bases into separate |
|
220 |
contexts, and establish walls between these contexts. Each thread and |
|
221 |
each Component is associated with a particular context and cannot |
|
222 |
interfere with threads or access Components in other contexts. In such |
|
223 |
a scenario, there will be one KeyboardFocusManager per context. Other |
|
224 |
browsers place all applets into the same context, implying that there |
|
225 |
will be only a single, global KeyboardFocusManager for all |
|
226 |
applets. This behavior is implementation-dependent. Consult your |
|
227 |
browser's documentation for more information. No matter how many |
|
228 |
contexts there may be, however, there can never be more than one focus |
|
229 |
owner, focused Window, or active Window, per ClassLoader. |
|
230 |
||
231 |
||
232 |
<a name="KeyEventDispatcher"></a> |
|
233 |
<h3>KeyEventDispatcher and KeyEventPostProcessor</h3> |
|
234 |
<p> |
|
235 |
While the user's KeyEvents should generally be delivered to the focus |
|
236 |
owner, there are rare cases where this is not desirable. An input |
|
237 |
method is an example of a specialized Component that should receive |
|
238 |
KeyEvents even though its associated text Component is and should |
|
239 |
remain the focus owner. |
|
240 |
<p> |
|
241 |
A KeyEventDispatcher is a lightweight interface that allows client |
|
242 |
code to pre-listen to all KeyEvents in a particular context. Instances |
|
243 |
of classes that implement the interface and are registered with the |
|
244 |
current KeyboardFocusManager will receive KeyEvents before they are |
|
245 |
dispatched to the focus owner, allowing the KeyEventDispatcher to |
|
246 |
retarget the event, consume it, dispatch it itself, or make other |
|
247 |
changes. |
|
248 |
<p> |
|
249 |
For consistency, KeyboardFocusManager itself is a |
|
250 |
KeyEventDispatcher. By default, the current KeyboardFocusManager will |
|
251 |
be the sink for all KeyEvents not dispatched by the registered |
|
252 |
KeyEventDispatchers. The current KeyboardFocusManager cannot be |
|
253 |
completely deregistered as a KeyEventDispatcher. However, if a |
|
254 |
KeyEventDispatcher reports that it dispatched the KeyEvent, regardless |
|
255 |
of whether it actually did so, the KeyboardFocusManager will take no |
|
256 |
further action with regard to the KeyEvent. (While it is possible for |
|
257 |
client code to register the current KeyboardFocusManager as a |
|
258 |
KeyEventDispatcher one or more times, there is no obvious reason why |
|
259 |
this would be necessary, and therefore it is not recommended.) |
|
260 |
<p> |
|
261 |
Client-code may also post-listen to KeyEvents in a particular context |
|
262 |
using the KeyEventPostProcessor interface. KeyEventPostProcessors |
|
263 |
registered with the current KeyboardFocusManager will receive |
|
264 |
KeyEvents after the KeyEvents have been dispatched to and handled by |
|
265 |
the focus owner. The KeyEventPostProcessors will also receive |
|
266 |
KeyEvents that would have been otherwise discarded because no |
|
267 |
Component in the application currently owns the focus. This will allow |
|
268 |
applications to implement features that require global KeyEvent post- |
|
269 |
handling, such as menu shortcuts. |
|
270 |
<p> |
|
271 |
Like KeyEventDispatcher, KeyboardFocusManager also implements |
|
272 |
KeyEventPostProcessor, and similar restrictions apply to its use in |
|
273 |
that capacity. |
|
274 |
||
275 |
<a name="FocusEventAndWindowEvent"></a> |
|
276 |
<h3>FocusEvent and WindowEvent</h3> |
|
277 |
<p> |
|
278 |
The AWT defines the following six event types central to the focus |
|
279 |
model in two different <code>java.awt.event</code> classes: |
|
280 |
<ol> |
|
281 |
<li><code>WindowEvent.WINDOW_ACTIVATED</code>: This event is |
|
282 |
dispatched to a Frame or Dialog (but never a Window which |
|
283 |
is not a Frame or Dialog) when it becomes the active Window. |
|
284 |
<li><code>WindowEvent.WINDOW_GAINED_FOCUS</code>: This event is |
|
285 |
dispatched to a Window when it becomes the focused Window. |
|
286 |
Only focusable Windows can receive this event. |
|
287 |
<li><code>FocusEvent.FOCUS_GAINED</code>: This event is dispatched |
|
288 |
to a Component when it becomes the focus owner. Only focusable |
|
289 |
Components can receive this event. |
|
290 |
<li><code>FocusEvent.FOCUS_LOST</code>: This event is dispatched |
|
291 |
to a Component when it is no longer the focus owner. |
|
292 |
<li><code>WindowEvent.WINDOW_LOST_FOCUS</code>: This event is |
|
293 |
dispatched to a Window when it is no longer the focused Window. |
|
294 |
<li><code>WindowEvent.WINDOW_DEACTIVATED</code>: This event is |
|
295 |
dispatched to a Frame or Dialog (but never a Window which is |
|
296 |
not a Frame or Dialog) when it is no longer the active Window. |
|
297 |
</ol> |
|
298 |
||
299 |
<a name="EventDelivery"></a> |
|
300 |
<h3>Event Delivery</h3> |
|
301 |
<p> |
|
302 |
If the focus is not in java application and the user clicks on a focusable |
|
303 |
child Component<b>a</b> of an inactive Frame <b>b</b>, the following events |
|
304 |
will be dispatched and handled in order: |
|
305 |
||
306 |
<ol> |
|
307 |
<li><b>b</b> will receive a <code>WINDOW_ACTIVATED</code> event. |
|
308 |
<li>Next, <b>b</b> will receive a <code>WINDOW_GAINED_FOCUS</code> event. |
|
309 |
<li>Finally, <b>a</b> will receive a <code>FOCUS_GAINED</code> event. |
|
310 |
</ol> |
|
311 |
||
312 |
If the user later clicks on a focusable child Component <b>c</b> of another |
|
313 |
Frame <b>d</b>, the following events will be dispatched and handled in |
|
314 |
order: |
|
315 |
<ol> |
|
316 |
<li><b>a</b> will receive a <code>FOCUS_LOST</code> event. |
|
317 |
<li><b>b</b> will receive a <code>WINDOW_LOST_FOCUS</code> event. |
|
318 |
<li><b>b</b> will receive a <code>WINDOW_DEACTIVATED</code> event. |
|
319 |
<li><b>d</b> will receive a <code>WINDOW_ACTIVATED</code> event. |
|
320 |
<li><b>d</b> will receive a <code>WINDOW_GAINED_FOCUS</code> event. |
|
321 |
<li><b>c</b> will receive a <code>FOCUS_GAINED</code> event. |
|
322 |
</ol> |
|
323 |
||
324 |
Note that each event will be fully handled before the next event is |
|
325 |
dispatched. This restriction will be enforced even if the Components |
|
326 |
are in different contexts and are handled on different event |
|
327 |
dispatching threads. |
|
328 |
<p> |
|
329 |
In addition, each event type will be dispatched in 1-to-1 |
|
330 |
correspondence with its opposite event type. For example, if a |
|
331 |
Component receives a <code>FOCUS_GAINED</code> event, under no |
|
332 |
circumstances can it ever receive another <code>FOCUS_GAINED</code> |
|
333 |
event without an intervening <code>FOCUS_LOST</code> event. |
|
334 |
<p> |
|
335 |
Finally, it is important to note that these events are delivered for |
|
336 |
informational purposes only. It is impossible, for example, to prevent |
|
337 |
the delivery of a pending <code>FOCUS_GAINED</code> event by requesting |
|
338 |
focus back to the Component losing focus while handling the preceding |
|
339 |
<code>FOCUS_LOST</code> event. While client code may make such a request, |
|
340 |
the pending <code>FOCUS_GAINED</code> will still be delivered, |
|
341 |
followed later by the events transferring focus back to the original |
|
342 |
focus owner. |
|
343 |
<p> |
|
344 |
If it is absolutely necessary to suppress the <code>FOCUS_GAINED</code> event, |
|
345 |
client code can install a <code>VetoableChangeListener</code> which |
|
346 |
rejects the focus change. See <a href="#FocusAndVetoableChangeListener">Focus |
|
347 |
and VetoableChangeListener</a>. |
|
348 |
||
349 |
||
350 |
<a name="OppositeComponents"></a> |
|
351 |
<h3>Opposite Components and Windows</h3> |
|
352 |
<p> |
|
353 |
Each event includes information about the "opposite" Component or |
|
354 |
Window involved in the focus or activation change. For example, for a |
|
355 |
<code>FOCUS_GAINED</code> event, the opposite Component is the Component |
|
356 |
that lost focus. If the focus or activation change occurs with a native |
|
357 |
application, with a Java application in a different VM or context, or |
|
358 |
with no other Component, then the opposite Component or Window is |
|
359 |
null. This information is accessible using |
|
360 |
<code>FocusEvent.getOppositeComponent</code> or |
|
361 |
<code>WindowEvent.getOppositeWindow</code>. |
|
362 |
<p> |
|
363 |
On some platforms, it is not possible to discern the opposite |
|
364 |
Component or Window when the focus or activation change occurs between |
|
365 |
two different heavyweight Components. In these cases, the opposite |
|
366 |
Component or Window may be set to null on some platforms, and to a |
|
367 |
valid non-null value on other platforms. However, for a focus change |
|
368 |
between two lightweight Components which share the same heavyweight |
|
369 |
Container, the opposite Component will always be set correctly. Thus, |
|
370 |
a pure Swing application can ignore this platform restriction when |
|
371 |
using the opposite Component of a focus change that occurred within a |
|
372 |
top-level Window. |
|
373 |
||
374 |
<a name="TemporaryFocusEvents"></a> |
|
375 |
<h3>Temporary FocusEvents</h3> |
|
376 |
<p> |
|
377 |
<code>FOCUS_GAINED</code> and <code>FOCUS_LOST</code> events are |
|
378 |
marked as either temporary or permanent. |
|
379 |
<p> |
|
380 |
Temporary <code>FOCUS_LOST</code> events are sent when a Component is |
|
381 |
losing the focus, but will regain the focus shortly. These events |
|
382 |
can be useful when focus changes are used as triggers for validation |
|
383 |
of data. For instance, a text Component may want to commit its |
|
384 |
contents when the user begins interacting with another Component, |
|
385 |
and can accomplish this by responding to <code>FOCUS_LOST</code> events. |
|
386 |
However, if the <code>FocusEvent</code> received is temporary, |
|
387 |
the commit should not be done, since the text field will be receiving |
|
388 |
the focus again shortly. |
|
389 |
<p> |
|
390 |
A permanent focus transfer typically occurs as the result of a user |
|
391 |
clicking on a selectable, heavyweight Component, focus traversal with |
|
392 |
the keyboard or an equivalent input device, or from a call to |
|
393 |
<code>requestFocus()</code> or <code>requestFocusInWindow()</code>. |
|
394 |
<p> |
|
395 |
A temporary focus transfer typically occurs as the result of showing a |
|
396 |
Menu or PopupMenu, clicking or dragging a Scrollbar, moving a Window |
|
397 |
by dragging the title bar, or making another Window the focused |
|
398 |
Window. Note that on some platforms, these actions may not generate |
|
399 |
any FocusEvents at all. On others, temporary focus transfers will |
|
400 |
occur. |
|
401 |
<p> |
|
402 |
When a Component receives a temporary <code>FOCUS_LOST</code> event, |
|
403 |
the event's opposite Component (if any) may receive a temporary |
|
404 |
<code>FOCUS_GAINED</code> event, but could also receive a permanent |
|
405 |
<code>FOCUS_GAINED</code> event. Showing a Menu or PopupMenu, or |
|
406 |
clicking or dragging a Scrollbar, should generate a temporary |
|
407 |
<code>FOCUS_GAINED</code> event. Changing the focused Window, |
|
408 |
however, will yield a permanent <code>FOCUS_GAINED</code> event |
|
409 |
for the new focus owner. |
|
410 |
<p> |
|
411 |
The Component class includes variants of <code>requestFocus</code> and |
|
412 |
<code>requestFocusInWindow</code> which take a desired temporary state as a |
|
413 |
parameter. However, because specifying an arbitrary temporary state |
|
414 |
may not be implementable on all native windowing systems, correct |
|
415 |
behavior for this method can be guaranteed only for lightweight |
|
416 |
Components. This method is not intended for general use, but exists |
|
417 |
instead as a hook for lightweight Component libraries, such as Swing. |
|
418 |
||
419 |
<a name="FocusTraversal"></a> |
|
420 |
<h3>Focus Traversal</h3> |
|
421 |
<p> |
|
422 |
Each Component defines its own Set of focus traversal keys for a given |
|
423 |
focus traversal operation. Components support separate Sets of keys |
|
424 |
for forward and backward traversal, and also for traversal up one |
|
425 |
focus traversal cycle. Containers which are focus cycle roots also |
|
426 |
support a Set of keys for traversal down one focus traversal cycle. If |
|
427 |
a Set is not explicitly defined for a Component, that Component |
|
428 |
recursively inherits a Set from its parent, and ultimately from a |
|
429 |
context-wide default set on the current <code>KeyboardFocusManager</code>. |
|
430 |
<p> |
|
431 |
Using the <code>AWTKeyStroke</code> API, client code can specify |
|
432 |
on which of two specific KeyEvents, <code>KEY_PRESSED</code> or |
|
433 |
<code>KEY_RELEASED</code>, the focus traversal operation will occur. |
|
434 |
Regardless of which KeyEvent is specified, however, all KeyEvents |
|
435 |
related to the focus traversal key, including the associated |
|
436 |
<code>KEY_TYPED</code> event, will be consumed, and will not be |
|
437 |
dispatched to any Component. It is a runtime error to specify a |
|
438 |
<code>KEY_TYPED</code> event as mapping to a focus traversal operation, |
|
439 |
or to map the same event to multiple focus traversal operations for any |
|
440 |
particular Component or for a <code>KeyboardFocusManager</code>'s defaults. |
|
441 |
<p> |
|
442 |
The default focus traversal keys are implementation-dependent. Sun |
|
443 |
recommends that the all implementations for a particular native |
|
444 |
platform use the same keys. For Windows and Unix, the recommendations |
|
445 |
are: |
|
446 |
||
447 |
<ul> |
|
448 |
<li>traverse forward to the next Component: |
|
449 |
<br><i>TextAreas</i>: <code>CTRL-TAB</code> on <code>KEY_PRESSED</code> |
|
450 |
<br><i>All others</i>: <code>TAB</code> on <code>KEY_PRESSED</code> and |
|
451 |
<code>CTRL-TAB</code> on <code>KEY_PRESSED</code> |
|
452 |
<li>traverse backward to the previous Component: |
|
453 |
<br><i>TextAreas</i>: <code>CTRL-SHIFT-TAB</code> on |
|
454 |
<code>KEY_PRESSED</code> |
|
455 |
<br><i>All others</i>: <code>SHIFT-TAB</code> on <code>KEY_PRESSED</code> |
|
456 |
and <code>CTRL-SHIFT-TAB</code> on |
|
457 |
<code>KEY_PRESSED</code> |
|
458 |
<li>traverse up one focus traversal cycle : <none> |
|
459 |
<li>traverse down one focus traversal cycle : <none> |
|
460 |
</ul> |
|
461 |
<p> |
|
462 |
Components can enable and disable all of their focus traversal keys en |
|
463 |
masse using <code>Component.setFocusTraversalKeysEnabled</code>. When focus |
|
464 |
traversal keys are disabled, the Component receives all KeyEvents for |
|
465 |
those keys. When focus traversal keys are enabled, the Component never |
|
466 |
receives KeyEvents for traversal keys; instead, the KeyEvents are |
|
467 |
automatically mapped to focus traversal operations. |
|
468 |
<p> |
|
469 |
For normal forward and backward traversal, the AWT focus |
|
470 |
implementation determines which Component to focus next based on the |
|
471 |
<a href=#FocusTraversalPolicy><code>FocusTraversalPolicy</code></a> of |
|
472 |
the focus owner's focus cycle root or focus traversal policy provider. If the |
|
473 |
focus owner is a focus cycle root, then it may be ambiguous as to which |
|
474 |
Components represent the next and previous Components to focus during |
|
475 |
normal focus traversal. Thus, the current |
|
476 |
<code>KeyboardFocusManager</code> maintains a reference to the |
|
477 |
"current" focus cycle root, which is global across all contexts. The |
|
478 |
current focus cycle root is used to resolve the ambiguity. |
|
479 |
<p> |
|
480 |
For up-cycle traversal, the focus owner is set to the current focus |
|
481 |
owner's focus cycle root, and the current focus cycle root is set to |
|
482 |
the new focus owner's focus cycle root. If, however, the current focus |
|
483 |
owner's focus cycle root is a top-level window, then the focus owner |
|
484 |
is set to the focus cycle root's default component to focus, and the |
|
485 |
current focus cycle root is unchanged. |
|
486 |
<p> |
|
487 |
For down-cycle traversal, if the current focus owner is a focus cycle |
|
488 |
root, then the focus owner is set to the current focus owner's default |
|
489 |
component to focus, and the current focus cycle root is set to the |
|
490 |
current focus owner. If the current focus owner is not a focus cycle |
|
491 |
root, then no focus traversal operation occurs. |
|
492 |
||
493 |
||
494 |
<a name="FocusTraversalPolicy"></a> |
|
495 |
<h3>FocusTraversalPolicy</h3> |
|
496 |
<p> |
|
497 |
||
498 |
A <code>FocusTraversalPolicy</code> defines the order in which Components within |
|
499 |
a particular focus cycle root or focus traversal policy provider are |
|
500 |
traversed. Instances of <code>FocusTraversalPolicy</code> can be shared across |
|
501 |
Containers, allowing those Containers to implement the same traversal policy. |
|
502 |
FocusTraversalPolicies do not need to be reinitialized when the |
|
503 |
focus-traversal-cycle hierarchy changes. |
|
504 |
||
505 |
<p> |
|
506 |
Each <code>FocusTraversalPolicy</code> must define the following |
|
507 |
five algorithms: |
|
508 |
||
509 |
<ol> |
|
510 |
<li>Given a focus cycle root and a Component <b>a</b> in that cycle, the |
|
511 |
next Component after <b>a</b>. |
|
512 |
<li>Given a focus cycle root and a Component <b>a</b> in that cycle, the |
|
513 |
previous Component before <b>a</b>. |
|
514 |
<li>Given a focus cycle root, the "first" Component in that cycle. |
|
515 |
The "first" Component is the Component to focus when traversal |
|
516 |
wraps in the forward direction. |
|
517 |
<li>Given a focus cycle root, the "last" Component in that cycle. |
|
518 |
The "last" Component is the Component to focus when traversal |
|
519 |
wraps in the reverse direction. |
|
520 |
<li>Given a focus cycle root, the "default" Component in that cycle. |
|
521 |
The "default" Component will be the first to receive focus when |
|
522 |
traversing down into a new focus traversal cycle. This may be the |
|
523 |
same as the "first" Component, but need not be. |
|
524 |
</ol> |
|
525 |
||
526 |
<p> |
|
527 |
A <code>FocusTraversalPolicy</code> may optionally provide an |
|
528 |
algorithm for the following: |
|
529 |
<blockquote> |
|
530 |
Given a Window, the "initial" Component in that Window. The initial |
|
531 |
Component will be the first to receive focus when the Window is |
|
532 |
first made visible. By default, this is the same as the "default" |
|
533 |
Component. |
|
534 |
</blockquote> |
|
535 |
||
536 |
In addition, Swing provides a subclass of <code>FocusTraversalPolicy</code>, |
|
537 |
<code>InternalFrameFocusTraversalPolicy</code>, which allows developers |
|
538 |
to provide an algorithm for the following: |
|
539 |
||
540 |
<blockquote> |
|
541 |
Given a <code>JInternalFrame</code>, the "initial" Component in that |
|
542 |
<code>JInternalFrame</code>. The initial Component is the first to |
|
543 |
receive focus when the <code>JInternalFrame</code> is first selected. |
|
544 |
By default, this is the same as the <code>JInternalFrame</code>'s |
|
545 |
default Component to focus. |
|
546 |
</blockquote> |
|
547 |
||
548 |
A <code>FocusTraversalPolicy</code> is installed on a Container using |
|
549 |
Container.<code>setFocusTraversalPolicy</code>. If a policy is not explicitly |
|
550 |
set, then a Container inherits its policy from its nearest focus-cycle-root |
|
551 |
ancestor. Top-levels initialize their focus traversal policies using the context |
|
552 |
default policy. The context default policy is established by using |
|
553 |
KeyboardFocusManager. <code>setDefaultFocusTraversalPolicy</code>. |
|
554 |
||
555 |
<p> |
|
556 |
AWT provides two standard <code>FocusTraversalPolicy</code> |
|
557 |
implementations for use by client code. |
|
558 |
||
559 |
<ol> |
|
560 |
<li><code>ContainerOrderFocusTraversalPolicy</code>: Iterates across the |
|
561 |
Components in a focus traversal cycle in the order they were added |
|
562 |
to their Containers. Each Component is tested for fitness using the |
|
563 |
accept(Component) method. By default, a Component is fit only if it |
|
564 |
is visible, displayable, enabled, and focusable. |
|
565 |
<li>By default, ContainerOrderFocusTraversalPolicy implicitly transfers |
|
566 |
focus down-cycle. That is, during normal forward focus traversal, |
|
567 |
the Component traversed after a focus cycle root will be the |
|
568 |
focus-cycle-root's default Component to focus, regardless of whether |
|
569 |
the focus cycle root is a traversable or non-traversable Container |
|
570 |
(see the pic.1,2 below). Such behavior provides backward compatibility |
|
571 |
with applications designed without the concepts of up- and down-cycle |
|
572 |
traversal. |
|
573 |
<li><code>DefaultFocusTraversalPolicy</code>: A subclass of |
|
574 |
<code>ContainerOrderFocusTraversalPolicy</code> which redefines |
|
575 |
the fitness test. If client code has explicitly set the |
|
576 |
focusability of a Component by either overriding |
|
577 |
<code>Component.isFocusTraversable()</code> or |
|
578 |
<code>Component.isFocusable()</code>, or by calling |
|
579 |
<code>Component.setFocusable(boolean)</code>, then a |
|
580 |
<code>DefaultFocusTraversalPolicy</code> behaves exactly |
|
581 |
like a <code>ContainerOrderFocusTraversalPolicy</code>. If, |
|
582 |
however, the Component is relying on default focusability, then a |
|
583 |
<code>DefaultFocusTraversalPolicy</code> will reject all |
|
584 |
Components with non-focusable peers. |
|
585 |
<br> |
|
586 |
The focusability of a peer is implementation-dependent. Sun |
|
587 |
recommends that all implementations for a particular native platform |
|
588 |
construct peers with the same focusability. The recommendations for |
|
589 |
Windows and Unix are that Canvases, Labels, Panels, Scrollbars, |
|
590 |
ScrollPanes, Windows, and lightweight Components have non-focusable |
|
591 |
peers, and all other Components have focusable peers. These |
|
592 |
recommendations are used in the Sun AWT implementations. Note that |
|
593 |
the focusability of a Component's peer is different from, and does |
|
594 |
not impact, the focusability of the Component itself. |
|
595 |
</ol> |
|
596 |
<p> |
|
597 |
Swing provides two additional, standard FocusTraversalPolicy |
|
598 |
implementations for use by client code. Each implementation is an |
|
599 |
InternalFrameFocusTraversalPolicy. |
|
600 |
||
601 |
<ol> |
|
602 |
<li>SortingFocusTraversalPolicy: Determines traversal order by |
|
603 |
sorting the Components of a focus traversal cycle based on a given |
|
604 |
Comparator. Each Component is tested for fitness using the |
|
605 |
accept(Component) method. By default, a Component is fit only if it |
|
606 |
is visible, displayable, enabled, and focusable. |
|
607 |
<li>By default, SortingFocusTraversalPolicy implicitly transfers focus |
|
608 |
down-cycle. That is, during normal forward focus traversal, the |
|
609 |
Component traversed after a focus cycle root will be the |
|
610 |
focus-cycle-root's default Component to focus, regardless of |
|
611 |
whether the focus cycle root is a traversable or non-traversable |
|
612 |
Container (see the pic.1,2 below). Such behavior provides backward |
|
613 |
compatibility with applications designed without the concepts of |
|
614 |
up- and down-cycle traversal. |
|
615 |
<li>LayoutFocusTraversalPolicy: A subclass of |
|
616 |
SortingFocusTraversalPolicy which sorts Components based on their |
|
617 |
size, position, and orientation. Based on their size and position, |
|
618 |
Components are roughly categorized into rows and columns. For a |
|
619 |
Container with horizontal orientation, columns run left-to-right or |
|
620 |
right-to-left, and rows run top-to-bottom. For a Container with |
|
621 |
vertical orientation, columns run top-to-bottom and rows run |
|
622 |
left-to-right or right-to-left. All columns in a row are fully |
|
623 |
traversed before proceeding to the next row. |
|
624 |
<br> |
|
625 |
In addition, the fitness test is extended to exclude JComponents |
|
626 |
that have or inherit empty InputMaps. |
|
627 |
</ol> |
|
628 |
<p> |
|
629 |
The figure below shows an implicit focus transfer: |
|
630 |
<br><img src="ImplicitFocusTransfer.gif" align=middle alt="Implicit focus transfer."><br> |
|
631 |
||
632 |
Assume the following: |
|
633 |
<ul> |
|
634 |
<li><b>A</b>, <b>B</b> and <b>C</b> are components in some window (a container) |
|
635 |
<li><b>R</b> is a container in the window and it is a parent of <b>B</b> and <b>C</b>. |
|
636 |
Besides, <b>R</b> is a focus cycle root. |
|
637 |
<li><b>B</b> is the default component in the focul traversal cycle of <b>R</b> |
|
638 |
<li><b>R</b> is a traversable Container in the pic.1, and it is a non-traversable |
|
639 |
Container in the pic.2. |
|
640 |
<li>In such a case a forward traversal will look as follows: |
|
641 |
<ul> |
|
642 |
<li> pic.1 : <b>A</b> -> <b>R</b> -> <b>B</b> -> <b>C</b> |
|
643 |
<li> pic.2 : <b>A</b> -> <b>B</b> -> <b>C</b> |
|
644 |
</ul> |
|
645 |
</ul> |
|
646 |
||
647 |
<p> |
|
648 |
Swing applications, or mixed Swing/AWT applications, that use one of |
|
649 |
the standard look and feels, or any other look and feel derived from |
|
650 |
BasicLookAndFeel, will use LayoutFocusTraversalPolicy for all |
|
651 |
Containers by default. |
|
652 |
<p> |
|
653 |
All other applications, including pure AWT applications, will use |
|
654 |
<code>DefaultFocusTraversalPolicy</code> by default. |
|
655 |
||
656 |
<a name="FocusTraversalPolicyProviders"></a> |
|
657 |
<h3>Focus Traversal Policy Providers</h3> |
|
658 |
<p> |
|
659 |
A Container that isn't a focus cycle root has an option to provide a |
|
660 |
FocusTraversalPolicy of its own. To do so, one needs to set Container's focus |
|
661 |
traversal policy provider property to <code>true</code> with the call to |
|
662 |
||
663 |
<ul> |
|
664 |
<code>Container.setFocusTraversalPolicyProvider(boolean)</code> |
|
665 |
</ul> |
|
666 |
||
667 |
To determine whether a Container is a focus traversal policy provider, the |
|
668 |
following method should be used: |
|
669 |
||
670 |
<ul> |
|
671 |
<code>Container.isFocusTraversalPolicyProvider()</code> |
|
672 |
</ul> |
|
673 |
||
674 |
If focus traversal policy provider property is set on a focus cycle root, it |
|
675 |
isn't considered a focus traversal policy provider and behaves just like any |
|
676 |
other focus cycle root. |
|
677 |
||
678 |
<p> |
|
679 |
The main difference between focus cycle roots and focus traversal policy |
|
680 |
providers is that the latter allow focus to enter and leave them just as all other |
|
681 |
Containers. However, children inside focus traversal policy provider are |
|
682 |
traversed in the order determined by provider's FocusTraversalPolicy. In order |
|
683 |
to enable focus traversal policy providers to behave this way, |
|
684 |
FocusTraversalPolicies treat them in the following manner: |
|
685 |
||
686 |
<ul> |
|
687 |
<li> Focus traversal policy providers can be passed to FocusTraversalPolicy |
|
688 |
methods instead of focus cycle roots. |
|
689 |
<li> When calculating next or previous Component in |
|
690 |
<code>FocusTraversalPolicy.getComponentAfter</code> or |
|
691 |
<code>FocusTraversalPolicy.getComponentBefore</code>, |
|
692 |
<ul> |
|
693 |
<li>if a Component is a child of a focus traversal policy provider, |
|
694 |
the next and previous for this Component are determined using this |
|
695 |
focus traversal policy provider's FocusTraversalPolicy. However, |
|
696 |
in order for focus to leave the provider, the following rules are |
|
697 |
applied: |
|
698 |
<ul> |
|
699 |
<li> if at some point the <code>next</code> found Component is |
|
700 |
the <code>first</code> Component of focus traversal policy |
|
701 |
provider, the Component after the focus traversal policy |
|
702 |
provider is returned |
|
703 |
<li> if at some point the <code>previous</code> found Component is |
|
704 |
the <code>last</code> Component of focus traversal policy |
|
705 |
provider, the Component before the focus traversal policy |
|
706 |
provider is returned |
|
707 |
</ul> |
|
708 |
<li> When calculating the next Component in |
|
709 |
<code>FocusTraversalPolicy.getComponentAfter</code>, |
|
710 |
<ul> |
|
711 |
<li> if an obtained Component is a non-traversable Container and |
|
712 |
it is a focus traversal policy provider, then the default Component |
|
713 |
of that provider is returned |
|
714 |
<li> if the Component passed to the <code>FocusTraversalPolicy.getComponentAfter</code> |
|
715 |
method is a traversable Container and it is a focus |
|
716 |
traversal policy provider, then the default Component of this provider |
|
717 |
is returned |
|
718 |
</ul> |
|
719 |
<li> When calculating the previous Component in |
|
720 |
<code>FocusTraversalPolicy.getComponentBefore</code>, |
|
721 |
<ul> |
|
722 |
<li> if an obtained Component is a Container (traversable or |
|
723 |
non-traversable) and it is a focus traversal policy provider, then |
|
724 |
the last Component of that provider is returned |
|
725 |
</ul> |
|
726 |
</ul> |
|
727 |
<li> When calculating the first Component in FocusTraversalPolicy.getFirstComponent, |
|
728 |
<ul> |
|
729 |
<li> if an obtained Component is a non-traversable Container and it is a focus |
|
730 |
traversal policy provider, then the default Component of that provider is |
|
731 |
returned |
|
732 |
<li> if an obtained Component is a traversable Container and it is a focus traversal |
|
733 |
policy provider, then that Container itself is returned |
|
734 |
</ul> |
|
735 |
<li> When calculating the last Component in FocusTraversalPolicy.getLastComponent, |
|
736 |
<ul> |
|
737 |
<li> if an obtained Component is a Container (traversable or non-traversable) |
|
738 |
and it is a focus traversal policy provider, then the last Component of |
|
739 |
that provider is returned |
|
740 |
</ul> |
|
741 |
</ul> |
|
742 |
||
743 |
<a name="ProgrammaticTraversal"></a> |
|
744 |
<h3>Programmatic Traversal</h3> |
|
745 |
<p> |
|
746 |
In addition to user-initiated focus traversal, client code can |
|
747 |
initiate a focus traversal operation programmatically. To client code, |
|
748 |
programmatic traversals are indistinguishable from user-initiated |
|
749 |
traversals. The preferred way to initiate a programmatic traversal is |
|
750 |
to use one of the following methods on <code>KeyboardFocusManager</code>: |
|
751 |
||
752 |
<ul> |
|
753 |
<code>KeyboardFocusManager.focusNextComponent()</code> |
|
754 |
<code>KeyboardFocusManager.focusPreviousComponent()</code> |
|
755 |
<code>KeyboardFocusManager.upFocusCycle()</code> |
|
756 |
<code>KeyboardFocusManager.downFocusCycle()</code> |
|
757 |
</ul> |
|
758 |
||
759 |
<p> |
|
760 |
Each of these methods initiates the traversal operation with the |
|
761 |
current focus owner. If there is currently no focus owner, then no |
|
762 |
traversal operation occurs. In addition, if the focus owner is not a |
|
763 |
focus cycle root, then downFocusCycle() performs no traversal |
|
764 |
operation. |
|
765 |
<p> |
|
766 |
<code>KeyboardFocusManager</code> also supports the following variants |
|
767 |
of these methods: |
|
768 |
||
769 |
<ul> |
|
770 |
<li><code>KeyboardFocusManager.focusNextComponent(Component)</code> |
|
771 |
<li><code>KeyboardFocusManager.focusPreviousComponent(Component)</code> |
|
772 |
<li><code>KeyboardFocusManager.upFocusCycle(Component)</code> |
|
773 |
<li><code>KeyboardFocusManager.downFocusCycle(Container)</code> |
|
774 |
</ul> |
|
775 |
||
776 |
Each of these methods initiates the traversal operation with the |
|
777 |
specified Component rather than the focus owner. That is, the |
|
778 |
traversal occurs as though the specified Component is the focus owner, |
|
779 |
though it need not be. |
|
780 |
<p> |
|
781 |
Alternate, but equivalent, APIs are defined on the Component and |
|
782 |
Container classes themselves: |
|
783 |
||
784 |
<ul> |
|
785 |
<li><code>Component.transferFocus()</code> |
|
786 |
<li><code>Component.transferFocusBackward()</code> |
|
787 |
<li><code>Component.transferFocusUpCycle()</code> |
|
788 |
<li><code>Container.transferFocusDownCycle()</code> |
|
789 |
</ul> |
|
790 |
||
791 |
As with the <code>KeyboardFocusManager</code> variants, each of these methods |
|
792 |
initiates the traversal operation as though the Component is the focus |
|
793 |
owner, though it need not be. |
|
794 |
<p> |
|
795 |
Also note that hiding or disabling the focus owner, directly or |
|
796 |
indirectly via an ancestor, or making the focus owner non-displayable |
|
797 |
or non-focusable, initiates an automatic, forward focus traversal. |
|
798 |
While hiding any ancestor, lightweight or heavyweight, will always |
|
799 |
indirectly hide its children, only disabling a heavyweight ancestor |
|
800 |
will disable its children. Thus, disabling a lightweight ancestor of |
|
801 |
the focus owner does not automatically initiate a focus traversal. |
|
802 |
<p> |
|
803 |
If client code initiates a focus traversal, and there is no other |
|
804 |
Component to focus, then the focus owner remains unchanged. If client |
|
805 |
code initiates an automatic focus traversal by hiding the focus owner, |
|
806 |
directly or indirectly, or by making the focus owner non-displayable or |
|
807 |
non-focusable, and there is no other Component to focus, then the |
|
808 |
global focus owner is cleared. If client code initiates an automatic |
|
809 |
focus traversal by disabling the focus owner, directly or indirectly, |
|
810 |
and there is no other Component to focus, then the focus owner remains |
|
811 |
unchanged. |
|
812 |
||
813 |
||
814 |
<a name="Focusability"></a> |
|
815 |
<h3>Focusability</h3> |
|
816 |
<p> |
|
817 |
A focusable Component can become the focus owner ("focusability") and
|
|
818 |
participates in keyboard focus traversal ("focus traversability") with
|
|
819 |
a FocusTraversalPolicy. There is no separation of these two concepts; |
|
820 |
a Component must either be both focusable and focus traversable, or |
|
821 |
neither. |
|
822 |
||
823 |
A Component expresses this state via the isFocusable() method. By |
|
824 |
default, all Components return true from this method. Client code can |
|
825 |
change this default by calling Component.setFocusable(boolean). |
|
826 |
||
827 |
||
828 |
<a name="FocusableWindows"></a> |
|
829 |
<h3>Focusable Windows</h3> |
|
830 |
<p> |
|
831 |
To support palette windows and input methods, client code can prevent |
|
832 |
a Window from becoming the focused Window. By transitivity, this |
|
833 |
prevents the Window or any of its descendants from becoming the focus |
|
834 |
owner. Non-focusable Windows may still own Windows that are |
|
835 |
focusable. By default, every Frame and Dialog is focusable. Every |
|
836 |
Window which is not a Frame or Dialog, but whose nearest owning Frame |
|
837 |
or Dialog is showing on the screen, and which has at least one |
|
838 |
Component in its focus traversal cycle, is also focusable by |
|
839 |
default. To make a Window non-focusable, use |
|
840 |
Window.setFocusableWindowState(false). |
|
841 |
<p> |
|
842 |
If a Window is non-focusable, this restriction is enforced when the |
|
843 |
<code>KeyboardFocusManager</code> sees a <code>WINDOW_GAINED_FOCUS</code> |
|
844 |
event for the Window. At this point, the focus change is rejected and |
|
845 |
focus is reset to a different Window. The rejection recovery scheme |
|
846 |
is the same as if a <code>VetoableChangeListener</code> rejected the |
|
847 |
focus change. See <a href="#FocusAndVetoableChangeListener">Focus |
|
848 |
and VetoableChangeListener</a>. |
|
849 |
<p> |
|
850 |
Because the new focus implementation requires that KeyEvents intended |
|
851 |
for a Window or its descendants be proxied through a child of the |
|
852 |
Window's owner, and because this proxy must be mapped on X11 in order |
|
853 |
to receive events, a Window whose nearest owning Frame or Dialog is |
|
854 |
not showing could never receive KeyEvents on X11. To support this |
|
855 |
restriction, we have made a distinction between a Window's "window |
|
856 |
focusability" and its "window focusability state". A Window's |
|
857 |
focusability state is combined with the showing state of the Window's |
|
858 |
nearest owning Frame or Dialog to determine the Window's focusability. |
|
859 |
By default, all Windows have a focusability state of true. Setting a |
|
860 |
Window's focusability state to false ensures that it will not become |
|
861 |
the focused Window regardless of the showing state of its nearest |
|
862 |
owning Frame or Dialog. |
|
863 |
<p> |
|
864 |
Swing allows applications to create JWindows with null owners. Swing |
|
865 |
constructs all such JWindows so that they are owned by a private, |
|
866 |
hidden Frame. Because the showing state of this Frame will always be |
|
867 |
false, a JWindow constructed will a null owner can never be the |
|
868 |
focused Window, even if it has a Window focusability state of true. |
|
869 |
<p> |
|
870 |
If the focused Window is made non-focusable, then the AWT will attempt |
|
871 |
to focus the most recently focused Component of the Window's |
|
872 |
owner. The Window's owner will thus become the new focused Window. If |
|
873 |
the Window's owner is also a non-focusable Window, then the focus |
|
874 |
change request will proceed up the ownership hierarchy recursively. |
|
875 |
Since not all platforms support cross-Window focus changes (see |
|
876 |
<a href=#RequestingFocus>Requesting Focus</a>), it is possible that |
|
877 |
all such focus change requests will fail. In this case, the global |
|
878 |
focus owner will be cleared and the focused Window will remain unchanged. |
|
879 |
||
880 |
<a name="RequestingFocus"></a> |
|
881 |
<h3>Requesting Focus</h3> |
|
882 |
||
883 |
<p> |
|
884 |
A Component can request that it become the focus owner by calling |
|
885 |
<code>Component.requestFocus()</code>. This initiates a permanent |
|
886 |
focus transfer to the Component only if the Component is displayable, |
|
887 |
focusable, visible and all of its ancestors (with the exception of the |
|
888 |
top-level Window) are visible. The request will be immediately denied if |
|
889 |
any of these conditions is not met. A disabled Component may be |
|
890 |
the focus owner; however, in this case, all KeyEvents will be discarded. |
|
891 |
<p> |
|
892 |
The request will also be denied if the Component's top-level Window is |
|
893 |
not the focused Window and the platform does not support requesting |
|
894 |
focus across Windows. If the request is denied for this reason, the |
|
895 |
request is remembered and will be granted when the Window is later |
|
896 |
focused by the user. Otherwise, the focus change request changes the |
|
|
8132
8686fda1829a
6693961: cross-window focus transfer ability in the Focus Spec should be revised
dav
parents:
5506
diff
changeset
|
897 |
focused Window as well. |
| 2 | 898 |
<p> |
899 |
There is no way to determine synchronously whether a focus change |
|
900 |
request has been granted. Instead, client code must install a |
|
901 |
FocusListener on the Component and watch for the delivery of a |
|
902 |
<code>FOCUS_GAINED</code> event. Client code must not assume that |
|
903 |
the Component is the focus owner until it receives this event. |
|
904 |
The event may or may not be delivered before <code>requestFocus()</code> |
|
905 |
returns. Developers must not assume one behavior or the other. |
|
906 |
<p> |
|
907 |
The AWT supports type-ahead if all focus change requests are made on |
|
908 |
the EventDispatchThread. If client code requests a focus change, and |
|
909 |
the AWT determines that this request might be granted by the native |
|
910 |
windowing system, then the AWT will notify the current |
|
911 |
KeyboardFocusManager that is should enqueue all KeyEvents with a |
|
912 |
timestamp later than the that of the event currently being handled. |
|
913 |
These KeyEvents will not be dispatched until the new Component becomes |
|
914 |
the focus owner. The AWT will cancel the delayed dispatching request |
|
915 |
if the focus change does not succeed at the native level, if the |
|
916 |
Component's peer is disposed, or if the focus change is vetoed by a |
|
917 |
VetoableChangeListener. KeyboardFocusManagers are not required to |
|
918 |
support type-ahead if a focus change request is made from a thread |
|
919 |
other than the EventDispatchThread. |
|
920 |
<p> |
|
921 |
Because <code>Component.requestFocus()</code> cannot be implemented |
|
922 |
consistently across platforms, developers are encouraged to use |
|
923 |
<code>Component.requestFocusInWindow()</code> instead. This method |
|
924 |
denies cross-Window focus transfers on all platforms automatically. |
|
925 |
By eliminating the only platform-specific element of the focus transfer, |
|
926 |
this method achieves consistent cross-platform behavior. |
|
927 |
<p> |
|
928 |
In addition, <code>requestFocusInWindow()</code> returns a boolean value. |
|
929 |
If 'false' is returned, the request is guaranteed to fail. If 'true' is |
|
930 |
returned, the request will succeed unless it is vetoed, or an |
|
931 |
extraordinary event, such as disposal of the Component's peer, occurs |
|
932 |
before the request can be granted by the native windowing |
|
933 |
system. Again, while a return value of 'true' indicates that the |
|
934 |
request is likely to succeed, developers must never assume that this |
|
935 |
Component is the focus owner until this Component receives a |
|
936 |
<code>FOCUS_GAINED</code> event. |
|
937 |
<p> |
|
938 |
If client code wants no Component in the application to be the focus |
|
939 |
owner, it can call the method <code>KeyboardFocusManager</code>. |
|
940 |
<code>clearGlobalFocusOwner()</code> on the current |
|
941 |
<code>KeyboardFocusManager</code>. If there exists a focus owner |
|
942 |
when this method is called, the focus owner will receive a permanent |
|
943 |
<code>FOCUS_LOST</code> event. After this point, the AWT |
|
944 |
focus implementation will discard all KeyEvents until the user or |
|
945 |
client code explicitly sets focus to a Component. |
|
946 |
<p> |
|
947 |
The Component class also supports variants of <code>requestFocus</code> and |
|
948 |
<code>requestFocusInWindow</code> that allow client code to specify |
|
949 |
a temporary state. |
|
950 |
See <a href="#TemporaryFocusEvents">Temporary FocusEvents</a> |
|
951 |
||
952 |
<a name="FocusAndPropertyChangeListener"></a> |
|
953 |
<h3>Focus and PropertyChangeListener</h3> |
|
954 |
<p> |
|
955 |
Client code can listen to changes in context-wide focus state, or to |
|
956 |
changes in focus-related state in Components, via |
|
957 |
PropertyChangeListeners. |
|
958 |
<p> |
|
959 |
The <code>KeyboardFocusManager</code> supports the following properties: |
|
960 |
||
961 |
<ol> |
|
962 |
<li><code>focusOwner</code>: the focus owner |
|
963 |
<li><code>focusedWindow</code>: the focused Window |
|
964 |
<li><code>activeWindow</code>: the active Window |
|
965 |
<li><code>defaultFocusTraversalPolicy</code>: the default focus |
|
966 |
traversal policy |
|
967 |
<li><code>forwardDefaultFocusTraversalKeys</code>: the Set of default |
|
968 |
<code>FORWARD_TRAVERSAL_KEYS</code> |
|
969 |
<li><code>backwardDefaultFocusTraversalKeys</code>: the Set of default |
|
970 |
<code>BACKWARD_TRAVERSAL_KEYS</code> |
|
971 |
<li><code>upCycleDefaultFocusTraversalKeys</code>: the Set of default |
|
972 |
<code>UP_CYCLE_TRAVERSAL_KEYS</code> |
|
973 |
<li><code>downCycleDefaultFocusTraversalKeys</code>: the Set of default |
|
974 |
<code>DOWN_CYCLE_TRAVERSAL_KEYS</code> |
|
975 |
<li><code>currentFocusCycleRoot</code>: the current focus cycle root |
|
976 |
</ol> |
|
977 |
<p> |
|
978 |
A <code>PropertyChangeListener</code> installed on the current |
|
979 |
<code>KeyboardFocusManager</code> will only see these changes within |
|
980 |
the <code>KeyboardFocusManager</code>'s context, even though the |
|
981 |
focus owner, focused Window, active Window, and current focus cycle |
|
982 |
root comprise the global focus state shared by all contexts. |
|
983 |
We believe this is less intrusive than requiring client code to pass |
|
984 |
a security check before installing a <code>PropertyChangeListener</code>. |
|
985 |
<p> |
|
986 |
Component supports the following focus-related properties: |
|
987 |
||
988 |
<ol> |
|
989 |
<li><code>focusable</code>: the Component's focusability |
|
990 |
<li><code>focusTraversalKeysEnabled</code>: the Component's |
|
991 |
focus traversal keys enabled state |
|
992 |
<li><code>forwardFocusTraversalKeys</code>: the Component's Set of |
|
993 |
<code>FORWARD_TRAVERSAL_KEYS</code> |
|
994 |
<li><code>backwardFocusTraversalKeys</code>: the Component's Set of |
|
995 |
<code>BACKWARD_TRAVERSAL_KEYS</code> |
|
996 |
<li><code>upCycleFocusTraversalKeys</code>: the Component's Set of |
|
997 |
<code>UP_CYCLE_TRAVERSAL_KEYS</code> |
|
998 |
</ol> |
|
999 |
<p> |
|
1000 |
In addition to the Component properties, Container supports the |
|
1001 |
following focus-related properties: |
|
1002 |
||
1003 |
<ol> |
|
1004 |
<li><code>downCycleFocusTraversalKeys</code>: the Container's Set of |
|
1005 |
<code>DOWN_CYCLE_TRAVERSAL_KEYS</code> |
|
1006 |
<li><code>focusTraversalPolicy</code>: the Container's focus |
|
1007 |
traversal policy |
|
1008 |
<li><code>focusCycleRoot</code>: the Container's focus-cycle-root state |
|
1009 |
</ol> |
|
1010 |
<p> |
|
1011 |
In addition to the Container properties, Window supports the following |
|
1012 |
focus-related property: |
|
1013 |
||
1014 |
<ol> |
|
1015 |
<li><code>focusableWindow</code>: the Window's focusable Window state |
|
1016 |
</ol> |
|
1017 |
<p> |
|
1018 |
Also note that a <code>PropertyChangeListener</code> installed on a |
|
1019 |
Window will never see a <code>PropertyChangeEvent</code> for the |
|
1020 |
<code>focusCycleRoot</code> property. |
|
1021 |
A Window is always a focus cycle root; this property cannot change. |
|
1022 |
<p> |
|
1023 |
<a name="FocusAndVetoableChangeListener"></a> |
|
1024 |
<h3>Focus and VetoableChangeListener</h3> |
|
1025 |
<p> |
|
1026 |
The <code>KeyboardFocusManager</code> also supports |
|
1027 |
<code>VetoableChangeListener</code>s for the following properties: |
|
1028 |
||
1029 |
<ol> |
|
1030 |
<li>"focusOwner": the focus owner |
|
1031 |
<li>"focusedWindow": the focused Window |
|
1032 |
<li>"activeWindow": the active Window |
|
1033 |
</ol> |
|
1034 |
||
1035 |
If a VetoableChangeListener vetoes a focus or activation change by |
|
1036 |
throwing a PropertyVetoException, the change is aborted. Any |
|
1037 |
VetoableChangeListeners which had already approved the change will |
|
1038 |
asynchronously receive PropertyChangeEvents indicating a reversion of |
|
1039 |
state to the previous value. |
|
1040 |
<p> |
|
1041 |
VetoableChangeListeners are notified of the state change before the |
|
1042 |
change is reflected in the KeyboardFocusManager. Conversely, |
|
1043 |
PropertyChangeListeners are notified after the change is reflected. |
|
1044 |
It follows that all VetoableChangeListeners will be notified before |
|
1045 |
any PropertyChangeListener. |
|
1046 |
<p> |
|
1047 |
VetoableChangeListeners must be idempotent, and must veto both loss |
|
1048 |
and gain events for a particular focus change (e.g., both |
|
1049 |
<code>FOCUS_LOST</code> and <code>FOCUS_GAINED</code>). For example, |
|
1050 |
if a <code>VetoableChangeListener</code> vetoes a <code>FOCUS_LOST</code> |
|
1051 |
event, a <code>KeyboardFocusManager</code> is not required to search the |
|
1052 |
<code>EventQueue</code> and remove the associated pending |
|
1053 |
<code>FOCUS_GAINED</code> event. Instead, the |
|
1054 |
<code>KeyboardFocusManager</code> is free to attempt to |
|
1055 |
dispatch this event and it is the responsibility of the |
|
1056 |
<code>VetoableChangeListener</code> to veto it as well. In addition, |
|
1057 |
during processing of the <code>FOCUS_GAINED</code> event, the |
|
1058 |
<code>KeyboardFocusManager</code> may attempt to resync the global |
|
1059 |
focus state by synthesizing another <code>FOCUS_LOST</code> event. |
|
1060 |
This event must be vetoed just as the first <code>FOCUS_LOST</code> event was. |
|
1061 |
<p> |
|
1062 |
A <code>KeyboardFocusManager</code> may not hold any locks while |
|
1063 |
notifying <code>PropertyChangeListener</code>s of a state change. |
|
1064 |
This requirement is relaxed for <code>VetoableChangeListeners</code>, |
|
1065 |
however. Therefore, client-definied <code>VetoableChangeListener</code>s |
|
1066 |
should avoid acquiring additional locks inside |
|
1067 |
<code>vetoableChange(PropertyChangeEvent)</code> as this may lead to deadlock. |
|
1068 |
||
1069 |
If a focus or activation change is rejected, the KeyboardFocusManager |
|
1070 |
will initiate rejection recovery as follows: |
|
1071 |
||
1072 |
<ul> |
|
1073 |
<li>If a focused or active Window change was rejected, then the |
|
1074 |
focused or active Window will be reset to the Window which was |
|
1075 |
previously the focused or active Window. If there is no such |
|
1076 |
Window, then the <code>KeyboardFocusManager</code> will clear |
|
1077 |
the global focus owner. |
|
1078 |
<li>If a focus owner change was rejected, then the focus owner will be |
|
1079 |
reset to the Component which was previously the focus owner. If |
|
1080 |
that is not possible, then it will be reset to the next Component |
|
1081 |
in the focus traversal cycle after the previous focus owner. If |
|
1082 |
that is also not possible, then the <code>KeyboardFocusManager</code> |
|
1083 |
will clear the global focus owner. |
|
1084 |
</ul> |
|
1085 |
||
1086 |
<code>VetoableChangeListener</code>s must be careful to avoid vetoing focus |
|
1087 |
changes initiated as a result of veto rejection recovery. Failure |
|
1088 |
to anticipate this situation could lead to an infinite cycle of |
|
1089 |
vetoed focus changes and recovery attempts. |
|
1090 |
||
1091 |
||
1092 |
<a name="ZOrder"></a> |
|
1093 |
<h3>Z-Order</h3> |
|
1094 |
<p> |
|
1095 |
On some native windowing systems, the Z-order of a Window can affect |
|
1096 |
its focused or active (if applicable) state. On Microsoft Windows, the |
|
1097 |
top-most Window is naturally the focused Window as well. However, on |
|
1098 |
Solaris, many window managers use a point-to-focus model that ignores |
|
1099 |
Z-order in determining the focused Window. |
|
1100 |
||
1101 |
When focusing or activating Windows, the AWT adheres to the UI |
|
1102 |
requirements of the native platform. Therefore, the focus behavior of |
|
1103 |
Z-order-related methods such as: |
|
1104 |
<ul> |
|
1105 |
<li><code>Window.toFront()</code> |
|
1106 |
<li><code>Window.toBack()</code> |
|
1107 |
<li><code>Window.show()</code> |
|
1108 |
<li><code>Window.hide()</code> |
|
1109 |
<li><code>Window.setVisible(boolean)</code> |
|
1110 |
<li><code>Window.dispose()</code> |
|
1111 |
<li><code>Frame.setState(int)</code> |
|
1112 |
</ul> |
|
1113 |
is platform-dependent. In JDK 1.4, the behavior of these methods on |
|
1114 |
Microsoft Windows and Solaris is as follows: |
|
1115 |
<ul> |
|
1116 |
<li><code>Window.toFront()</code>:<br> |
|
1117 |
<b>Microsoft Windows</b>: The Window is moved to front, if possible. |
|
1118 |
While we will always be able to move this Window in front of other |
|
1119 |
Windows in the same VM, Windows 98 and Windows 2000 do not allow an |
|
1120 |
application to bring any of its windows to the front unless one |
|
1121 |
of that application's windows is already in the foreground. In |
|
1122 |
this case, Windows will instead flash the Window's icon in the |
|
1123 |
taskbar. If the Window is moved to the front, it will be made |
|
1124 |
the focused and (if applicable) active Window. |
|
1125 |
<br> |
|
1126 |
<b>Solaris</b>: The Window is moved to front. In a point-to-focus |
|
1127 |
window manager, the Window will become the focused Window if it |
|
1128 |
is the top-most Window underneath the cursor. In a click-to-focus |
|
1129 |
window manager, the focused Window will remain unchanged. |
|
1130 |
||
1131 |
<li><code>Window.toBack()</code>:<br> |
|
1132 |
<b>Microsoft Windows</b>: The Window is moved to back. Note however |
|
1133 |
that Microsoft Windows insists that an owned Window always be in |
|
1134 |
front of all of its recursive owners. Thus, after the completion of |
|
1135 |
this operation, the Window may not be the lowest Java Window in the |
|
1136 |
Z-order. If the Window, or any of its owners, was the focused Window, |
|
1137 |
then the focused Window is reset to the top-most Window in the VM. |
|
1138 |
<br> |
|
1139 |
<b>Solaris</b>: The Window is moved to back. Like Microsoft Windows, |
|
1140 |
some window managers insist than an owned Window always be in front |
|
1141 |
of all of its recursive owners. Thus, after the completion of this |
|
1142 |
operation, the Window may not be the lowest Java Window in the |
|
1143 |
Z-order. If the Window was the focused Window, it will lose |
|
1144 |
focus in a point-to-focus window manager if it is no longer the |
|
1145 |
top-most Window under the cursor. In a click-to-focus window |
|
1146 |
manager, the focused Window will remain unchanged. |
|
1147 |
||
1148 |
<li><code>Window.show()/Window.setVisible(true)/Frame.setState(NORMAL)</code>:<br> |
|
1149 |
<b>Microsoft Windows</b>: The Window is moved to front and becomes the focused |
|
1150 |
Window. |
|
1151 |
<br> |
|
1152 |
</b>Solaris</b>: The Window is moved to front. In a point-to-focus focus |
|
1153 |
window manager, the Window will be focused if it is now the |
|
1154 |
top-most Window under the cursor. In a click-to-focus window |
|
1155 |
manager, the Window will become the focused Window. |
|
1156 |
||
1157 |
<li><code>Window.hide()/Window.setVisible(false)/Window.dispose()/ |
|
1158 |
Frame.setState(ICONIFIED)</code>:<br> |
|
1159 |
<b>Microsoft Windows</b>: If the Window was the focused Window, the focused |
|
1160 |
Window is reset to a window chosen by the OS, or to no window. The |
|
1161 |
window may be in a native application, or a Java application in |
|
1162 |
another VM. |
|
1163 |
<br> |
|
1164 |
<b>Solaris</b>: If the Window was the focused Window, in a point-to- |
|
1165 |
focus window manager, the top-most Window under the cursor will |
|
1166 |
become the focused Window. In a click-to-focus window manager, |
|
1167 |
the focused Window is reset to a window chosen by the window |
|
1168 |
manager. The window may be in a native application, or a Java |
|
1169 |
application in another VM. |
|
1170 |
</ul> |
|
1171 |
||
1172 |
<a name="ReplacingDefaultKeyboardFocusManager"></a> |
|
1173 |
<h3>Replacing DefaultKeyboardFocusManager</h3> |
|
1174 |
<p> |
|
1175 |
<code>KeyboardFocusManager</code>s are pluggable at the browser context |
|
1176 |
level. Client code can subclass <code>KeyboardFocusManager</code> or |
|
1177 |
<code>DefaultKeyboardFocusManager</code> to modify the way that WindowEvents |
|
1178 |
related to focus, FocusEvents, and KeyEvents are handled and |
|
1179 |
dispatched, and to examine and modify the global focus state. A custom |
|
1180 |
<code>KeyboardFocusManager</code> can also reject focus changes at a more |
|
1181 |
fundamental level then a FocusListener or WindowListener ever could. |
|
1182 |
<p> |
|
1183 |
While giving a developer ultimate control over the focus model, |
|
1184 |
replacing the entire <code>KeyboardFocusManager</code> is a difficult process |
|
1185 |
requiring a thorough understanding of the peer focus layer. |
|
1186 |
Fortunately, most applications do not need this much control. |
|
1187 |
Developers are encouraged to use KeyEventDispatchers, |
|
1188 |
KeyEventPostProcessors, FocusTraversalPolicies, |
|
1189 |
VetoableChangeListeners, and other concepts discussed in this document |
|
1190 |
before resorting to a full replacement of the <code>KeyboardFocusManager</code>. |
|
1191 |
<p> |
|
1192 |
First note that, because unhindered access to Components in other |
|
1193 |
contexts represents a security hole, the SecurityManager must grant a |
|
1194 |
new permission, "replaceKeyboardFocusManager", before client code is |
|
1195 |
permitted to replace the <code>KeyboardFocusManager</code> with an arbitrary |
|
1196 |
subclass instance. Because of the security check, replacing the |
|
1197 |
<code>KeyboardFocusManager</code> is not an option for applications that will be |
|
1198 |
deployed in environments with a SecurityManager, such as applets in a |
|
1199 |
browser. |
|
1200 |
<p> |
|
1201 |
Once installed, a <code>KeyboardFocusManager</code> instance has |
|
1202 |
access to the global focus state via a set of protected functions. |
|
1203 |
The <code>KeyboardFocusManager</code> can only call these functions |
|
1204 |
if it is installed in the calling thread's context. This ensures |
|
1205 |
that malicious code cannot circumvent the security check in |
|
1206 |
<code>KeyboardFocusManager.setCurrentFocusManager</code>. |
|
1207 |
A <code>KeyboardFocusManager</code> should always work with |
|
1208 |
the global focus state instead of the context focus state. |
|
1209 |
Failure to do this will lead to incorrect behavior of the |
|
1210 |
<code>KeyboardFocusManager</code>. |
|
1211 |
<p> |
|
1212 |
The primary responsibility of a <code>KeyboardFocusManager</code> |
|
1213 |
is the dispatch of the following events: |
|
1214 |
||
1215 |
<ul> |
|
1216 |
<li>all <code>KeyEvent</code>s |
|
1217 |
<li>all <code>FocusEvent</code>s |
|
1218 |
<li><code>WindowEvent.WINDOW_GAINED_FOCUS</code> |
|
1219 |
<li><code>WindowEvent.WINDOW_LOST_FOCUS</code> |
|
1220 |
<li><code>WindowEvent.WINDOW_ACTIVATED</code> |
|
1221 |
<li><code>WindowEvent.WINDOW_DEACTIVATED</code> |
|
1222 |
</ul> |
|
1223 |
||
1224 |
The peer layer will provide the <code>KeyboardFocusManager</code> |
|
1225 |
with all of the above events except <code>WINDOW_ACTIVATED</code> |
|
1226 |
and <code>WINDOW_DEACTIVATED</code>. The <code>KeyboardFocusManager</code> |
|
1227 |
must synthesize <code>WINDOW_ACTIVATED</code> and |
|
1228 |
<code>WINDOW_DEACTIVATED</code> events when appropriate and target them |
|
1229 |
accordingly. |
|
1230 |
<p> |
|
1231 |
The <code>KeyboardFocusManager</code> may need to retarget the events |
|
1232 |
provided by the peer layer to its own notion of the focus owner or |
|
1233 |
focused Window: |
|
1234 |
<ul> |
|
1235 |
<li>A KeyEvent must be retargeted to the focus owner. Because the peer |
|
1236 |
layer is unaware of any lightweight Components, KeyEvents will |
|
1237 |
arrive from the peer layer targeted to the focus owner's |
|
1238 |
heavyweight Container, not the focus owner. |
|
1239 |
<li>A <code>FOCUS_LOST</code> event must be retargeted to the focus |
|
1240 |
owner. Again, this is necessary because the peer layer is |
|
1241 |
unaware of lightweight Components. |
|
1242 |
<li>A <code>WINDOW_LOST_FOCUS</code> event must be retargeted to |
|
1243 |
the focused Window. The implementation of the Window class |
|
1244 |
may cause the native focused Window to differ from the Java |
|
1245 |
focused Window. |
|
1246 |
</ul> |
|
1247 |
<p> |
|
1248 |
A <code>KeyboardFocusManager</code> must ensure proper event ordering, |
|
1249 |
and a 1-to-1 correspondence between an event and its opposite event type. |
|
1250 |
The peer layer does not make any of these guarantees. For example, it is |
|
1251 |
possible for the peer layer to send a <code>FOCUS_GAINED</code> |
|
1252 |
event before a <code>WINDOW_GAINED_FOCUS</code> event. |
|
1253 |
The <code>KeyboardFocusManager</code> is responsible for |
|
1254 |
ensuring that the <code>WINDOW_GAINED_FOCUS</code> event is dispatched |
|
1255 |
before the <code>FOCUS_GAINED</code> event. |
|
1256 |
<p> |
|
1257 |
Before redispatching an event via <code>KeyboardFocusManager</code>. |
|
1258 |
<code>redispatchEvent</code>, a <code>KeyboardFocusManager</code> |
|
1259 |
must attempt to update the global focus state. Typically, this |
|
1260 |
is done using one of the <code>KeyboardFocusManager.setGlobal*</code> |
|
1261 |
methods; however, an implementation is free to implement its own methods. |
|
1262 |
After attempting an update, the <code>KeyboardFocusManager</code> |
|
1263 |
must verify that the global focus state change |
|
1264 |
was not rejected. A rejection is detected when a call to the |
|
1265 |
corresponding <code>getGlobal*</code> method returns a value different than the |
|
1266 |
value just set. Rejections occur in three standard cases: |
|
1267 |
<ul> |
|
1268 |
<li>If the <code>KeyboardFocusManager</code> attempts |
|
1269 |
to set the global focus owner to a non-focusable Component. |
|
1270 |
<li>If the <code>KeyboardFocusManager</code> attempts |
|
1271 |
to set the global focused Window to a non-focusable Window. |
|
1272 |
<li>If the change is rejected by an installed |
|
1273 |
<code>VetoableChangeListener</code>. |
|
1274 |
</ul> |
|
1275 |
<p> |
|
1276 |
Client-defined implementations of <code>KeyboardFocusManager</code> |
|
1277 |
can adjust the set of focus transfers which are rejected by overriding the |
|
1278 |
accessor and mutator methods for the global focus state. |
|
1279 |
<p> |
|
1280 |
If a request to change the global focus state is rejected, the |
|
1281 |
<code>KeyboardFocusManager</code> must discard the event which prompted |
|
1282 |
the focus change request. The Component to which the event was targeted |
|
1283 |
must not receive the event. |
|
1284 |
<p> |
|
1285 |
The <code>KeyboardFocusManager</code> is also expected to initiate rejection |
|
1286 |
recovery as outlined in <a href="#FocusAndVetoableChangeListener">Focus |
|
1287 |
and VetoableChangeListener</a>. |
|
1288 |
<p> |
|
1289 |
Finally, a KeyboardFocusManager must handle the following set of |
|
1290 |
special cases: |
|
1291 |
<ul> |
|
1292 |
<li>When handling a <code>WINDOW_GAINED_FOCUS</code> event, the |
|
1293 |
<code>KeyboardFocusManager</code> must set focus to the |
|
1294 |
appropriate child Component of the Window. If a child |
|
1295 |
Component of the Window previously requested focus, |
|
1296 |
but the focus change was rejected because the platform |
|
1297 |
does not support cross-Window focus change requests, |
|
1298 |
then focus should be set to that child Component. |
|
1299 |
Otherwise, if the Window has never been focused, focus should be |
|
1300 |
set to the Window's initial Component to focus. If the Window was |
|
1301 |
previously focused, focus should be set to the Window's most |
|
1302 |
recent focus owner. |
|
1303 |
<li>The <code>KeyboardFocusManager</code> must ensure that the |
|
1304 |
opposite Component or Window are as accurate as the native |
|
1305 |
windowing platform permits. For example, the |
|
1306 |
<code>KeyboardFocusManager</code> may need to |
|
1307 |
retarget the opposite Component to a lightweight child of the |
|
1308 |
heavyweight initially specified by the peer layer. |
|
1309 |
<br> |
|
1310 |
If the peer layer states that the opposite Component or Window is |
|
1311 |
<code>null</code>, it is acceptable for the |
|
1312 |
<code>KeyboardFocusManager</code> to propagate |
|
1313 |
this value. <code>null</code> indicates that it is highly |
|
1314 |
probably that no other Component or Window was involved |
|
1315 |
in the focus or activation change. Because of platform |
|
1316 |
limitations, this computation may be |
|
1317 |
subject to a heuristic and could be incorrect. Nevertheless, this |
|
1318 |
heuristic will be the best possible guess which the peer layer |
|
1319 |
could make. |
|
1320 |
<li>Focus and activation changes in which a Component or Window loses |
|
1321 |
focus or activation to itself must be discarded. |
|
1322 |
<li>Events posted by the peer layer claiming that the active Window |
|
1323 |
has lost focus to the focused Window must be discarded. The peer |
|
1324 |
implementation of the Window class may generate these spurious |
|
1325 |
events. |
|
1326 |
</ul> |
|
1327 |
||
1328 |
<a name="Incompatibilities"></a> |
|
1329 |
<h3>Incompatibilities with Previous Releases</h3> |
|
1330 |
<p><b>Cross-platform changes:</b> |
|
1331 |
<ol> |
|
1332 |
<li>The default focus traversability for all Components is now |
|
1333 |
'true'. Previously, some Components (in particular, all |
|
1334 |
lightweights), had a default focus traversability of 'false'. Note |
|
1335 |
that despite this change, however, the |
|
1336 |
<code>DefaultFocusTraversalPolicy</code> for all AWT Containers |
|
1337 |
will preserve the traversal order of previous releases. |
|
1338 |
<li>A request to focus a non-focus traversable (i.e., non-focusable) |
|
1339 |
Component will be denied. Previously, such requests were granted. |
|
1340 |
<li><code>Window.toFront()</code> and <code>Window.toBack()</code> |
|
1341 |
now perform no operation if the Window is not visible. |
|
1342 |
Previously, the behavior was platform-dependent. |
|
1343 |
<li>KeyListeners installed on <code>Component</code>s |
|
1344 |
will no longer see <code>KeyEvent</code>s that map to focus |
|
1345 |
traversal operations, and |
|
1346 |
<code>Component.handleEvent()</code> will no longer be invoked |
|
1347 |
for such events. Previously, AWT Components saw these events |
|
1348 |
and had an opportunity to consume them before AWT |
|
1349 |
initiated focus traversal. Code that requires this |
|
1350 |
functionality should instead disable focus traversal keys on |
|
1351 |
its <code>Component</code>s and handle focus traversal |
|
1352 |
itself. Alternately, the code can use an |
|
1353 |
<code>AWTEventListener</code> or |
|
1354 |
<code>KeyEventDispatcher</code> to pre-listen to all |
|
1355 |
<code>KeyEvent</code>s. |
|
1356 |
</ol> |
|
1357 |
<p><b>Changes specific to Microsoft Windows:</b> |
|
1358 |
<ol> |
|
1359 |
<li><code>Window.toBack()</code> changes the focused Window to |
|
1360 |
the top-most Window after the Z-order change. |
|
1361 |
<li><code>requestFocus()</code> now allows cross-Window focus |
|
1362 |
change requests in all cases. Previously, requests were granted |
|
1363 |
for heavyweights, but denied for lightweights. |
|
1364 |
</ol> |
|
1365 |
||
1366 |
</body> |
|
1367 |
</html> |