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