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, 2018, 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 <main role="main"> 34 <h1>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 id="Overview"></a> 105 <h2>Overview of KeyboardFocusManager</h2> 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" 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 id="BrowserContexts"></a> 217 <h2>KeyboardFocusManager and Browser Contexts</h2> 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 id="KeyEventDispatcher"></a> 233 <h2>KeyEventDispatcher and KeyEventPostProcessor</h2> 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 id="FocusEventAndWindowEvent"></a> 276 <h2>FocusEvent and WindowEvent</h2> 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 id="EventDelivery"></a> 300 <h2>Event Delivery</h2> 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 id="OppositeComponents"></a> 351 <h2>Opposite Components and Windows</h2> 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 id="TemporaryFocusEvents"></a> 375 <h2>Temporary FocusEvents</h2> 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 id="FocusTraversal"></a> 420 <h2>Focus Traversal</h2> 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 id="FocusTraversalPolicy"></a> 495 <h2>FocusTraversalPolicy</h2> 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" 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 id="FocusTraversalPolicyProviders"></a> 657 <h2>Focus Traversal Policy Providers</h2> 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 <blockquote> 664 <code>Container.setFocusTraversalPolicyProvider(boolean)</code> 665 </blockquote> 666 667 To determine whether a Container is a focus traversal policy provider, the 668 following method should be used: 669 670 <blockquote> 671 <code>Container.isFocusTraversalPolicyProvider()</code> 672 </blockquote> 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 id="ProgrammaticTraversal"></a> 744 <h2>Programmatic Traversal</h2> 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 <li><code>KeyboardFocusManager.focusNextComponent()</code> 754 <li><code>KeyboardFocusManager.focusPreviousComponent()</code> 755 <li><code>KeyboardFocusManager.upFocusCycle()</code> 756 <li><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 id="Focusability"></a> 815 <h2>Focusability</h2> 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 id="FocusableWindows"></a> 829 <h2>Focusable Windows</h2> 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 id="RequestingFocus"></a> 881 <h2>Requesting Focus</h2> 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 897 focused Window as well. 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 id="FocusAndPropertyChangeListener"></a> 953 <h2>Focus and PropertyChangeListener</h2> 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 id="FocusAndVetoableChangeListener"></a> 1024 <h2>Focus and VetoableChangeListener</h2> 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 id="ZOrder"></a> 1093 <h2>Z-Order</h2> 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 id="ReplacingDefaultKeyboardFocusManager"></a> 1173 <h2>Replacing DefaultKeyboardFocusManager</h2> 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 id="Incompatibilities"></a> 1329 <h2>Incompatibilities with Previous Releases</h2> 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 </main> 1366 </body> 1367 </html>