< prev index next >

src/java.desktop/share/classes/java/awt/doc-files/FocusSpec.html

Print this page








   1 <!--
   2  Copyright (c) 2001, 2013, Oracle and/or its affiliates. All rights reserved.
   3  DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4 
   5  This code is free software; you can redistribute it and/or modify it
   6  under the terms of the GNU General Public License version 2 only, as
   7  published by the Free Software Foundation.  Oracle designates this
   8  particular file as subject to the "Classpath" exception as provided
   9  by Oracle in the LICENSE file that accompanied this code.
  10 
  11  This code is distributed in the hope that it will be useful, but WITHOUT
  12  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  version 2 for more details (a copy is included in the LICENSE file that
  15  accompanied this code).
  16 
  17  You should have received a copy of the GNU General Public License version
  18  2 along with this work; if not, write to the Free Software Foundation,
  19  Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20 
  21  Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  or visit www.oracle.com if you need additional information or have any
  23  questions.
  24 -->
  25 
  26 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  27 
  28 <html>
  29     <head>
  30        <title>The AWT Focus Subsystem</title>
  31     </head>
  32 
  33     <body bgcolor="white">
  34       <h1 align=center>The AWT Focus Subsystem</h1>
  35 
  36     <p>
  37       Prior to Java 2 Standard Edition, JDK 1.4, the AWT focus subsystem
  38       was inadequate. It suffered from major design and API problems,
  39       as well as over a hundred open bugs. Many of these bugs were caused by
  40       platform inconsistencies, or incompatibilities between the native
  41       focus system for heavyweights and the Java focus system for
  42       lightweights.
  43     <p>
  44       The single worst problem with the AWT focus implementation was the
  45       inability to query for the currently focused Component. Not only was
  46       there no API for such a query, but also, because of an insufficient
  47       architecture, such information was not even maintained by the code.
  48     <p>
  49       Almost as bad was the inability of lightweight children of a Window
  50       (not a Frame or a Dialog) to receive keyboard input. This problem
  51       existed because Windows never received <code>WINDOW_ACTIVATED</code>
  52       events and thus could never be activated, and only active Windows
  53       could contain focused Components.
  54     <p>


  84       <li><a href=#BrowserContexts>KeyboardFocusManager and Browser Contexts</a>
  85       <li><a href=#KeyEventDispatcher>KeyEventDispatcher</a>
  86       <li><a href=#FocusEventAndWindowEvent>FocusEvent and WindowEvent</a>
  87       <li><a href=#EventDelivery>Event Delivery</a>
  88       <li><a href=#OppositeComponents>Opposite Components and Windows</a>
  89       <li><a href=#TemporaryFocusEvents>Temporary FocusEvents</a>
  90       <li><a href=#FocusTraversal>Focus Traversal</a>
  91       <li><a href=#FocusTraversalPolicy>Focus Traversal Policy</a>
  92       <li><a href=#FocusTraversalPolicyProviders>Focus Traversal Policy Providers</a>
  93       <li><a href=#ProgrammaticTraversal>Programmatic Traversal</a>
  94       <li><a href=#Focusability>Focusability</a>
  95       <li><a href=#FocusableWindows>Focusable Windows</a>
  96       <li><a href=#RequestingFocus>Requesting Focus</a>
  97       <li><a href=#FocusAndPropertyChangeListener>Focus and PropertyChangeListener</a>
  98       <li><a href=#FocusAndVetoableChangeListener>Focus and VetoableChangeListener</a>
  99       <li><a href=#ZOrder>Z-Order</a>
 100       <li><a href=#ReplacingDefaultKeyboardFocusManager>Replacing DefaultKeyboardFocusManager</a>
 101       <li><a href=#Incompatibilities>Incompatibilities with Previous Releases</a>
 102      </ul>
 103 
 104       <a name="Overview"></a>
 105       <h3>Overview of KeyboardFocusManager</h3>
 106     <p>
 107       The focus model is centralized around a single class,
 108       KeyboardFocusManager, that provides a set of APIs for client code to
 109       inquire about the current focus state, initiate focus changes, and
 110       replace default focus event dispatching with a custom dispatcher.
 111       Clients can inquire about the focus state directly, or can register a
 112       PropertyChangeListener that will receive PropertyChangeEvents when a
 113       change to the focus state occurs.
 114     <p>
 115       KeyboardFocusManager introduces the following main concepts and their
 116       terminology:
 117     <ol>
 118       <li>The "focus owner" -- the Component which typically receives
 119           keyboard input.
 120       <li>The "permanent focus owner" -- the last Component to receive
 121           focus permanently. The "focus owner" and the "permanent focus
 122           owner" are equivalent unless a temporary focus change is
 123           currently in effect. In such a situation, the "permanent focus
 124           owner" will again be the "focus owner" when the temporary focus


 163           <code>setFocusTraversalPolicyProvider</code> on the Container. 
 164     </ol>
 165 
 166     <p>
 167       Every Window and JInternalFrame is, by default, a "focus cycle
 168       root". If it's the only focus cycle root, then all of its
 169       focusable descendants should be in its focus cycle, and its focus
 170       traversal policy should enforce that they are by making sure that
 171       all will be reached during normal forward (or backward)
 172       traversal. If, on the other hand, the Window or JInternalFrame
 173       has descendants that are also focus cycle roots, then each such
 174       descendant is a member of two focus cycles: the one that it is
 175       the root of, and the one of its nearest focus-cycle-root
 176       ancestor. In order to traverse the focusable components belonging
 177       to the focus cycle of such a "descendant" focus cycle root, one
 178       first traverses (forward or backward) to reach the descendant,
 179       and then uses the "down cycle" operation to reach, in turn, its
 180       descendants.
 181 
 182      <p>
 183      Here is an example:<br> <img src="FocusCycle.gif" align=middle 
 184      alt="Three groups as described below: ABCF BDE and DGH. "><br>
 185 
 186      <p>Assume the following:
 187       <ul>
 188         <li><b>A</b> is a <code>Window</code>, which means that it
 189             must be a focus cycle root.
 190         <li><b>B</b> and <b>D</b> are <code>Container</code>s that
 191             are focus cycle roots.
 192         <li><b>C</b> is a <code>Container</code> that is not a focus cycle root.
 193         <li><b>G</b>, <b>H</b>, <b>E</b>, and <b>F</b> are all
 194             <code>Component</code>s.
 195       </ul>
 196   
 197      There are a total of three focus cycle roots in this example:
 198 
 199       <ol>
 200         <li><b>A</b> is a root, and <b>A</b>, <b>B</b>, <b>C</b>,
 201             and <b>F</b> are members of <b>A</b>'s cycle.
 202         <li><b>B</b> is a root, and <b>B</b>, <b>D</b>, and
 203             <b>E</b> are members of <b>B</b>'s cycle.
 204         <li><b>D</b> is a root, and <b>D</b>, <b>G</b>,
 205             and <b>H</b> are members of <b>D</b>'s cycle.
 206       </ol>
 207 
 208      Windows are the only Containers which, by default, are focus cycle
 209      roots.
 210 
 211 
 212 <code>KeyboardFocusManager</code> is an abstract class. AWT provides a default
 213 implementation in the <code>DefaultKeyboardFocusManager</code> class.
 214 
 215 
 216 <a name="BrowserContexts"></a>
 217 <h3>KeyboardFocusManager and Browser Contexts</h3>
 218 <p>
 219 Some browsers partition applets in different code bases into separate
 220 contexts, and establish walls between these contexts. Each thread and
 221 each Component is associated with a particular context and cannot
 222 interfere with threads or access Components in other contexts. In such
 223 a scenario, there will be one KeyboardFocusManager per context. Other
 224 browsers place all applets into the same context, implying that there
 225 will be only a single, global KeyboardFocusManager for all
 226 applets. This behavior is implementation-dependent. Consult your
 227 browser's documentation for more information. No matter how many
 228 contexts there may be, however, there can never be more than one focus
 229 owner, focused Window, or active Window, per ClassLoader.
 230 
 231 
 232 <a name="KeyEventDispatcher"></a>
 233 <h3>KeyEventDispatcher and KeyEventPostProcessor</h3>
 234 <p>
 235 While the user's KeyEvents should generally be delivered to the focus
 236 owner, there are rare cases where this is not desirable. An input
 237 method is an example of a specialized Component that should receive
 238 KeyEvents even though its associated text Component is and should
 239 remain the focus owner.
 240 <p>
 241 A KeyEventDispatcher is a lightweight interface that allows client
 242 code to pre-listen to all KeyEvents in a particular context. Instances
 243 of classes that implement the interface and are registered with the
 244 current KeyboardFocusManager will receive KeyEvents before they are
 245 dispatched to the focus owner, allowing the KeyEventDispatcher to
 246 retarget the event, consume it, dispatch it itself, or make other
 247 changes.
 248 <p>
 249 For consistency, KeyboardFocusManager itself is a
 250 KeyEventDispatcher. By default, the current KeyboardFocusManager will
 251 be the sink for all KeyEvents not dispatched by the registered
 252 KeyEventDispatchers. The current KeyboardFocusManager cannot be


 255 of whether it actually did so, the KeyboardFocusManager will take no
 256 further action with regard to the KeyEvent. (While it is possible for
 257 client code to register the current KeyboardFocusManager as a
 258 KeyEventDispatcher one or more times, there is no obvious reason why
 259 this would be necessary, and therefore it is not recommended.)
 260 <p>
 261 Client-code may also post-listen to KeyEvents in a particular context
 262 using the KeyEventPostProcessor interface. KeyEventPostProcessors
 263 registered with the current KeyboardFocusManager will receive
 264 KeyEvents after the KeyEvents have been dispatched to and handled by
 265 the focus owner. The KeyEventPostProcessors will also receive
 266 KeyEvents that would have been otherwise discarded because no
 267 Component in the application currently owns the focus. This will allow
 268 applications to implement features that require global KeyEvent post-
 269 handling, such as menu shortcuts.
 270 <p>
 271 Like KeyEventDispatcher, KeyboardFocusManager also implements
 272 KeyEventPostProcessor, and similar restrictions apply to its use in
 273 that capacity.
 274 
 275 <a name="FocusEventAndWindowEvent"></a>
 276 <h3>FocusEvent and WindowEvent</h3>
 277 <p>
 278 The AWT defines the following six event types central to the focus
 279 model in two different <code>java.awt.event</code> classes:
 280   <ol>
 281     <li><code>WindowEvent.WINDOW_ACTIVATED</code>: This event is
 282         dispatched to a Frame or Dialog (but never a Window which
 283         is not a Frame or Dialog) when it becomes the active Window.
 284     <li><code>WindowEvent.WINDOW_GAINED_FOCUS</code>: This event is
 285         dispatched to a Window when it becomes the focused Window.
 286         Only focusable Windows can receive this event.
 287     <li><code>FocusEvent.FOCUS_GAINED</code>: This event is dispatched
 288         to a Component when it becomes the focus owner. Only focusable
 289         Components can receive this event.
 290     <li><code>FocusEvent.FOCUS_LOST</code>: This event is dispatched
 291         to a Component when it is no longer the focus owner.
 292     <li><code>WindowEvent.WINDOW_LOST_FOCUS</code>: This event is
 293         dispatched to a Window when it is no longer the focused Window.
 294     <li><code>WindowEvent.WINDOW_DEACTIVATED</code>: This event is
 295         dispatched to a Frame or Dialog (but never a Window which is
 296         not a Frame or Dialog) when it is no longer the active Window.
 297   </ol>
 298 
 299 <a name="EventDelivery"></a>
 300 <h3>Event Delivery</h3>
 301 <p>
 302 If the focus is not in java application and the user clicks on a focusable
 303 child Component<b>a</b> of an inactive Frame <b>b</b>, the following events
 304 will be dispatched and handled in order:
 305 
 306   <ol>
 307     <li><b>b</b> will receive a <code>WINDOW_ACTIVATED</code> event.
 308     <li>Next, <b>b</b> will receive a <code>WINDOW_GAINED_FOCUS</code> event.
 309     <li>Finally, <b>a</b> will receive a <code>FOCUS_GAINED</code> event.
 310   </ol>
 311 
 312 If the user later clicks on a focusable child Component <b>c</b> of another
 313 Frame <b>d</b>, the following events will be dispatched and handled in
 314 order:
 315   <ol>
 316    <li><b>a</b> will receive a <code>FOCUS_LOST</code> event.
 317    <li><b>b</b> will receive a <code>WINDOW_LOST_FOCUS</code> event.
 318    <li><b>b</b> will receive a <code>WINDOW_DEACTIVATED</code> event.
 319    <li><b>d</b> will receive a <code>WINDOW_ACTIVATED</code> event.


 330 correspondence with its opposite event type. For example, if a
 331 Component receives a <code>FOCUS_GAINED</code> event, under no
 332 circumstances can it ever receive another <code>FOCUS_GAINED</code>
 333 event without an intervening <code>FOCUS_LOST</code> event.
 334 <p>
 335 Finally, it is important to note that these events are delivered for
 336 informational purposes only. It is impossible, for example, to prevent
 337 the delivery of a pending <code>FOCUS_GAINED</code> event by requesting
 338 focus back to the Component losing focus while handling the preceding
 339 <code>FOCUS_LOST</code> event. While client code may make such a request,
 340 the pending <code>FOCUS_GAINED</code> will still be delivered,
 341 followed later by the events transferring focus back to the original
 342 focus owner.
 343 <p>
 344 If it is absolutely necessary to suppress the <code>FOCUS_GAINED</code> event,
 345 client code can install a <code>VetoableChangeListener</code> which
 346 rejects the focus change. See <a href="#FocusAndVetoableChangeListener">Focus
 347 and VetoableChangeListener</a>.
 348 
 349 
 350 <a name="OppositeComponents"></a>
 351 <h3>Opposite Components and Windows</h3>
 352 <p>
 353 Each event includes information about the "opposite" Component or
 354 Window involved in the focus or activation change. For example, for a
 355 <code>FOCUS_GAINED</code> event, the opposite Component is the Component
 356 that lost focus. If the focus or activation change occurs with a native
 357 application, with a Java application in a different VM or context, or
 358 with no other Component, then the opposite Component or Window is
 359 null. This information is accessible using
 360 <code>FocusEvent.getOppositeComponent</code> or
 361 <code>WindowEvent.getOppositeWindow</code>.
 362 <p>
 363 On some platforms, it is not possible to discern the opposite
 364 Component or Window when the focus or activation change occurs between
 365 two different heavyweight Components. In these cases, the opposite
 366 Component or Window may be set to null on some platforms, and to a
 367 valid non-null value on other platforms. However, for a focus change
 368 between two lightweight Components which share the same heavyweight
 369 Container, the opposite Component will always be set correctly. Thus,
 370 a pure Swing application can ignore this platform restriction when
 371 using the opposite Component of a focus change that occurred within a
 372 top-level Window.
 373 
 374 <a name="TemporaryFocusEvents"></a>
 375 <h3>Temporary FocusEvents</h3>
 376 <p>
 377 <code>FOCUS_GAINED</code> and <code>FOCUS_LOST</code> events are
 378 marked as either temporary or permanent.
 379 <p>
 380 Temporary <code>FOCUS_LOST</code> events are sent when a Component is
 381 losing the focus, but will regain the focus shortly. These events
 382 can be useful when focus changes are used as triggers for validation
 383 of data. For instance, a text Component may want to commit its 
 384 contents when the user begins interacting with another Component,
 385 and can accomplish this by responding to <code>FOCUS_LOST</code> events.
 386 However, if the <code>FocusEvent</code> received is temporary,
 387 the commit should not be done, since the text field will be receiving
 388 the focus again shortly.
 389 <p>
 390 A permanent focus transfer typically occurs as the result of a user
 391 clicking on a selectable, heavyweight Component, focus traversal with
 392 the keyboard or an equivalent input device, or from a call to
 393 <code>requestFocus()</code> or <code>requestFocusInWindow()</code>.
 394 <p>


 399 any FocusEvents at all. On others, temporary focus transfers will
 400 occur.
 401 <p>
 402 When a Component receives a temporary <code>FOCUS_LOST</code> event,
 403 the event's opposite Component (if any) may receive a temporary
 404 <code>FOCUS_GAINED</code> event, but could also receive a permanent
 405 <code>FOCUS_GAINED</code> event. Showing a Menu or PopupMenu, or 
 406 clicking or dragging a Scrollbar, should generate a temporary 
 407 <code>FOCUS_GAINED</code> event. Changing the focused Window,
 408 however, will yield a permanent <code>FOCUS_GAINED</code> event
 409 for the new focus owner.
 410 <p>
 411 The Component class includes variants of <code>requestFocus</code> and
 412 <code>requestFocusInWindow</code> which take a desired temporary state as a
 413 parameter. However, because specifying an arbitrary temporary state
 414 may not be implementable on all native windowing systems, correct
 415 behavior for this method can be guaranteed only for lightweight
 416 Components. This method is not intended for general use, but exists
 417 instead as a hook for lightweight Component libraries, such as Swing.
 418 
 419 <a name="FocusTraversal"></a>
 420 <h3>Focus Traversal</h3>
 421 <p>
 422 Each Component defines its own Set of focus traversal keys for a given
 423 focus traversal operation. Components support separate Sets of keys
 424 for forward and backward traversal, and also for traversal up one
 425 focus traversal cycle. Containers which are focus cycle roots also
 426 support a Set of keys for traversal down one focus traversal cycle. If
 427 a Set is not explicitly defined for a Component, that Component
 428 recursively inherits a Set from its parent, and ultimately from a
 429 context-wide default set on the current <code>KeyboardFocusManager</code>.
 430 <p>
 431 Using the <code>AWTKeyStroke</code> API, client code can specify 
 432 on which of two specific KeyEvents, <code>KEY_PRESSED</code> or 
 433 <code>KEY_RELEASED</code>, the focus traversal operation will occur.
 434 Regardless of which KeyEvent is specified, however, all KeyEvents
 435 related to the focus traversal key, including the associated 
 436 <code>KEY_TYPED</code> event, will be consumed, and will not be
 437 dispatched to any Component. It is a runtime error to specify a
 438 <code>KEY_TYPED</code> event as mapping to a focus traversal operation,
 439 or to map the same event to multiple focus traversal operations for any


 474 Components represent the next and previous Components to focus during
 475 normal focus traversal. Thus, the current
 476 <code>KeyboardFocusManager</code> maintains a reference to the
 477 "current" focus cycle root, which is global across all contexts. The
 478 current focus cycle root is used to resolve the ambiguity.  
 479 <p>
 480 For up-cycle traversal, the focus owner is set to the current focus
 481 owner's focus cycle root, and the current focus cycle root is set to
 482 the new focus owner's focus cycle root. If, however, the current focus
 483 owner's focus cycle root is a top-level window, then the focus owner
 484 is set to the focus cycle root's default component to focus, and the
 485 current focus cycle root is unchanged.
 486 <p>
 487 For down-cycle traversal, if the current focus owner is a focus cycle
 488 root, then the focus owner is set to the current focus owner's default
 489 component to focus, and the current focus cycle root is set to the
 490 current focus owner. If the current focus owner is not a focus cycle
 491 root, then no focus traversal operation occurs.
 492 
 493 
 494 <a name="FocusTraversalPolicy"></a>
 495 <h3>FocusTraversalPolicy</h3>
 496 <p>
 497   
 498 A <code>FocusTraversalPolicy</code> defines the order in which Components within
 499 a particular focus cycle root or focus traversal policy provider are
 500 traversed. Instances of <code>FocusTraversalPolicy</code> can be shared across
 501 Containers, allowing those Containers to implement the same traversal policy.
 502 FocusTraversalPolicies do not need to be reinitialized when the
 503 focus-traversal-cycle hierarchy changes.
 504 
 505 <p>
 506 Each <code>FocusTraversalPolicy</code> must define the following
 507 five algorithms:
 508 
 509   <ol>
 510     <li>Given a focus cycle root and a Component <b>a</b> in that cycle, the
 511         next Component after <b>a</b>.
 512     <li>Given a focus cycle root and a Component <b>a</b> in that cycle, the
 513         previous Component before <b>a</b>.
 514     <li>Given a focus cycle root, the "first" Component in that cycle.


 610         focus-cycle-root's default Component to focus, regardless of
 611         whether the focus cycle root is a traversable or non-traversable
 612         Container (see the pic.1,2 below). Such behavior provides backward
 613         compatibility with applications designed without the concepts of
 614         up- and down-cycle traversal.
 615     <li>LayoutFocusTraversalPolicy: A subclass of
 616         SortingFocusTraversalPolicy which sorts Components based on their
 617         size, position, and orientation. Based on their size and position,
 618         Components are roughly categorized into rows and columns. For a
 619         Container with horizontal orientation, columns run left-to-right or
 620         right-to-left, and rows run top-to-bottom. For a Container with
 621         vertical orientation, columns run top-to-bottom and rows run
 622         left-to-right or right-to-left. All columns in a row are fully
 623         traversed before proceeding to the next row.
 624         <br>
 625         In addition, the fitness test is extended to exclude JComponents
 626         that have or inherit empty InputMaps.
 627   </ol>
 628 <p>
 629 The figure below shows an implicit focus transfer:
 630 <br><img src="ImplicitFocusTransfer.gif" align=middle alt="Implicit focus transfer."><br>
 631 
 632 Assume the following:
 633  <ul>
 634    <li><b>A</b>, <b>B</b> and <b>C</b> are components in some window (a container)
 635    <li><b>R</b> is a container in the window and it is a parent of <b>B</b> and <b>C</b>.
 636        Besides, <b>R</b> is a focus cycle root.
 637    <li><b>B</b> is the default component in the focul traversal cycle of <b>R</b>
 638    <li><b>R</b> is a traversable Container in the pic.1, and it is a non-traversable
 639        Container in the pic.2.
 640    <li>In such a case a forward traversal will look as follows:
 641    <ul>
 642      <li> pic.1 : <b>A</b> -> <b>R</b> -> <b>B</b> -> <b>C</b>
 643      <li> pic.2 : <b>A</b> -> <b>B</b> -> <b>C</b>
 644    </ul>
 645  </ul>
 646 
 647 <p>
 648 Swing applications, or mixed Swing/AWT applications, that use one of
 649 the standard look and feels, or any other look and feel derived from
 650 BasicLookAndFeel, will use LayoutFocusTraversalPolicy for all
 651 Containers by default.
 652 <p>
 653 All other applications, including pure AWT applications, will use
 654 <code>DefaultFocusTraversalPolicy</code> by default.
 655 
 656 <a name="FocusTraversalPolicyProviders"></a>
 657 <h3>Focus Traversal Policy Providers</h3>
 658 <p>
 659   A Container that isn't a focus cycle root has an option to provide a
 660   FocusTraversalPolicy of its own. To do so, one needs to set Container's focus
 661   traversal policy provider property to <code>true</code> with the call to
 662 
 663   <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.


 723                      non-traversable) and it is a focus traversal policy provider, then
 724                      the last Component of that provider is returned
 725               </ul>
 726         </ul>
 727     <li> When calculating the first Component in FocusTraversalPolicy.getFirstComponent,
 728         <ul>
 729           <li> if an obtained Component is a non-traversable Container and it is a focus
 730                traversal policy provider, then the default Component of that provider is
 731                returned
 732           <li> if an obtained Component is a traversable Container and it is a focus traversal
 733                policy provider, then that Container itself is returned
 734         </ul>
 735     <li> When calculating the last Component in FocusTraversalPolicy.getLastComponent,
 736         <ul>
 737           <li> if an obtained Component is a Container (traversable or non-traversable)
 738                and it is a focus traversal policy provider, then the last Component of
 739                that provider is returned
 740         </ul>
 741   </ul>
 742 
 743 <a name="ProgrammaticTraversal"></a>
 744 <h3>Programmatic Traversal</h3>
 745 <p>
 746 In addition to user-initiated focus traversal, client code can
 747 initiate a focus traversal operation programmatically. To client code,
 748 programmatic traversals are indistinguishable from user-initiated
 749 traversals. The preferred way to initiate a programmatic traversal is
 750 to use one of the following methods on <code>KeyboardFocusManager</code>:
 751 
 752   <ul>
 753     <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


 794 <p>
 795 Also note that hiding or disabling the focus owner, directly or
 796 indirectly via an ancestor, or making the focus owner non-displayable
 797 or non-focusable, initiates an automatic, forward focus traversal.
 798 While hiding any ancestor, lightweight or heavyweight, will always
 799 indirectly hide its children, only disabling a heavyweight ancestor
 800 will disable its children. Thus, disabling a lightweight ancestor of
 801 the focus owner does not automatically initiate a focus traversal.
 802 <p>
 803 If client code initiates a focus traversal, and there is no other
 804 Component to focus, then the focus owner remains unchanged. If client
 805 code initiates an automatic focus traversal by hiding the focus owner,
 806 directly or indirectly, or by making the focus owner non-displayable or
 807 non-focusable, and there is no other Component to focus, then the
 808 global focus owner is cleared. If client code initiates an automatic
 809 focus traversal by disabling the focus owner, directly or indirectly,
 810 and there is no other Component to focus, then the focus owner remains
 811 unchanged.
 812 
 813 
 814 <a name="Focusability"></a>
 815 <h3>Focusability</h3>
 816 <p>
 817 A focusable Component can become the focus owner ("focusability") and
 818 participates in keyboard focus traversal ("focus traversability") with
 819 a FocusTraversalPolicy. There is no separation of these two concepts;
 820 a Component must either be both focusable and focus traversable, or
 821 neither.
 822 
 823 A Component expresses this state via the isFocusable() method. By
 824 default, all Components return true from this method. Client code can
 825 change this default by calling Component.setFocusable(boolean).
 826 
 827 
 828 <a name="FocusableWindows"></a>
 829 <h3>Focusable Windows</h3>
 830 <p>
 831 To support palette windows and input methods, client code can prevent
 832 a Window from becoming the focused Window. By transitivity, this
 833 prevents the Window or any of its descendants from becoming the focus
 834 owner. Non-focusable Windows may still own Windows that are
 835 focusable. By default, every Frame and Dialog is focusable. Every
 836 Window which is not a Frame or Dialog, but whose nearest owning Frame
 837 or Dialog is showing on the screen, and which has at least one
 838 Component in its focus traversal cycle, is also focusable by
 839 default. To make a Window non-focusable, use
 840 Window.setFocusableWindowState(false).
 841 <p>
 842 If a Window is non-focusable, this restriction is enforced when the
 843 <code>KeyboardFocusManager</code> sees a <code>WINDOW_GAINED_FOCUS</code>
 844 event for the Window.  At this point, the focus change is rejected and
 845 focus is reset to a different Window. The rejection recovery scheme
 846 is the same as if a <code>VetoableChangeListener</code> rejected the
 847 focus change.  See <a href="#FocusAndVetoableChangeListener">Focus
 848 and VetoableChangeListener</a>.


 860 Window's focusability state to false ensures that it will not become
 861 the focused Window regardless of the showing state of its nearest
 862 owning Frame or Dialog.
 863 <p>
 864 Swing allows applications to create JWindows with null owners. Swing
 865 constructs all such JWindows so that they are owned by a private,
 866 hidden Frame. Because the showing state of this Frame will always be
 867 false, a JWindow constructed will a null owner can never be the
 868 focused Window, even if it has a Window focusability state of true.
 869 <p>
 870 If the focused Window is made non-focusable, then the AWT will attempt
 871 to focus the most recently focused Component of the Window's
 872 owner. The Window's owner will thus become the new focused Window. If
 873 the Window's owner is also a non-focusable Window, then the focus
 874 change request will proceed up the ownership hierarchy recursively.
 875 Since not all platforms support cross-Window focus changes (see
 876 <a href=#RequestingFocus>Requesting Focus</a>), it is possible that
 877 all such focus change requests will fail. In this case, the global
 878 focus owner will be cleared and the focused Window will remain unchanged.
 879 
 880 <a name="RequestingFocus"></a>
 881 <h3>Requesting Focus</h3>
 882 
 883 <p>
 884 A Component can request that it become the focus owner by calling
 885 <code>Component.requestFocus()</code>. This initiates a permanent
 886 focus transfer to the Component only if the Component is displayable,
 887 focusable, visible and all of its ancestors (with the exception of the
 888 top-level Window) are visible. The request will be immediately denied if
 889 any of these conditions is not met. A disabled Component may be
 890 the focus owner; however, in this case, all KeyEvents will be discarded.
 891 <p>
 892 The request will also be denied if the Component's top-level Window is
 893 not the focused Window and the platform does not support requesting
 894 focus across Windows. If the request is denied for this reason, the
 895 request is remembered and will be granted when the Window is later
 896 focused by the user. Otherwise, the focus change request changes the
 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


 932 before the request can be granted by the native windowing
 933 system. Again, while a return value of 'true' indicates that the
 934 request is likely to succeed, developers must never assume that this
 935 Component is the focus owner until this Component receives a
 936 <code>FOCUS_GAINED</code> event.
 937 <p>
 938 If client code wants no Component in the application to be the focus
 939 owner, it can call the method <code>KeyboardFocusManager</code>.
 940 <code>clearGlobalFocusOwner()</code> on the current
 941 <code>KeyboardFocusManager</code>. If there exists a focus owner
 942 when this method is called, the focus owner will receive a permanent
 943 <code>FOCUS_LOST</code> event. After this point, the AWT
 944 focus implementation will discard all KeyEvents until the user or
 945 client code explicitly sets focus to a Component.
 946 <p>
 947 The Component class also supports variants of <code>requestFocus</code> and
 948 <code>requestFocusInWindow</code> that allow client code to specify
 949 a temporary state.
 950 See <a href="#TemporaryFocusEvents">Temporary FocusEvents</a>
 951 
 952 <a name="FocusAndPropertyChangeListener"></a>
 953 <h3>Focus and PropertyChangeListener</h3>
 954 <p>
 955 Client code can listen to changes in context-wide focus state, or to
 956 changes in focus-related state in Components, via
 957 PropertyChangeListeners.
 958 <p>
 959 The <code>KeyboardFocusManager</code> supports the following properties:
 960   
 961   <ol>
 962     <li><code>focusOwner</code>: the focus owner
 963     <li><code>focusedWindow</code>: the focused Window
 964     <li><code>activeWindow</code>: the active Window
 965     <li><code>defaultFocusTraversalPolicy</code>: the default focus
 966         traversal policy
 967     <li><code>forwardDefaultFocusTraversalKeys</code>: the Set of default
 968         <code>FORWARD_TRAVERSAL_KEYS</code>
 969     <li><code>backwardDefaultFocusTraversalKeys</code>: the Set of default
 970         <code>BACKWARD_TRAVERSAL_KEYS</code>
 971     <li><code>upCycleDefaultFocusTraversalKeys</code>: the Set of default
 972         <code>UP_CYCLE_TRAVERSAL_KEYS</code>


1003   <ol>
1004     <li><code>downCycleFocusTraversalKeys</code>: the Container's Set of 
1005         <code>DOWN_CYCLE_TRAVERSAL_KEYS</code>
1006     <li><code>focusTraversalPolicy</code>: the Container's focus
1007         traversal policy
1008     <li><code>focusCycleRoot</code>: the Container's focus-cycle-root state
1009   </ol>
1010 <p>
1011 In addition to the Container properties, Window supports the following
1012 focus-related property:
1013 
1014   <ol>
1015     <li><code>focusableWindow</code>: the Window's focusable Window state
1016   </ol>
1017 <p>
1018 Also note that a <code>PropertyChangeListener</code> installed on a
1019 Window will never see a <code>PropertyChangeEvent</code> for the
1020 <code>focusCycleRoot</code> property.
1021 A Window is always a focus cycle root; this property cannot change.
1022 <p>
1023 <a name="FocusAndVetoableChangeListener"></a>
1024 <h3>Focus and VetoableChangeListener</h3>
1025 <p>
1026 The <code>KeyboardFocusManager</code> also supports 
1027 <code>VetoableChangeListener</code>s for the following properties:
1028 
1029   <ol>
1030     <li>"focusOwner": the focus owner
1031     <li>"focusedWindow": the focused Window
1032     <li>"activeWindow": the active Window
1033   </ol>
1034 
1035 If a VetoableChangeListener vetoes a focus or activation change by
1036 throwing a PropertyVetoException, the change is aborted. Any
1037 VetoableChangeListeners which had already approved the change will
1038 asynchronously receive PropertyChangeEvents indicating a reversion of
1039 state to the previous value.
1040 <p>
1041 VetoableChangeListeners are notified of the state change before the
1042 change is reflected in the KeyboardFocusManager. Conversely,
1043 PropertyChangeListeners are notified after the change is reflected.


1072   <ul>
1073     <li>If a focused or active Window change was rejected, then the
1074         focused or active Window will be reset to the Window which was
1075         previously the focused or active Window. If there is no such
1076         Window, then the <code>KeyboardFocusManager</code> will clear
1077         the global focus owner.
1078     <li>If a focus owner change was rejected, then the focus owner will be
1079         reset to the Component which was previously the focus owner. If
1080         that is not possible, then it will be reset to the next Component
1081         in the focus traversal cycle after the previous focus owner. If
1082         that is also not possible, then the <code>KeyboardFocusManager</code>
1083         will clear the global focus owner.
1084   </ul>
1085 
1086 <code>VetoableChangeListener</code>s must be careful to avoid vetoing focus
1087 changes initiated as a result of veto rejection recovery. Failure
1088 to anticipate this situation could lead to an infinite cycle of
1089 vetoed focus changes and recovery attempts.
1090 
1091 
1092 <a name="ZOrder"></a>
1093 <h3>Z-Order</h3>
1094 <p>
1095 On some native windowing systems, the Z-order of a Window can affect
1096 its focused or active (if applicable) state. On Microsoft Windows, the 
1097 top-most Window is naturally the focused Window as well. However, on 
1098 Solaris, many window managers use a point-to-focus model that ignores 
1099 Z-order in determining the focused Window.
1100 
1101 When focusing or activating Windows, the AWT adheres to the UI
1102 requirements of the native platform. Therefore, the focus behavior of
1103 Z-order-related methods such as:
1104   <ul>
1105     <li><code>Window.toFront()</code>
1106     <li><code>Window.toBack()</code>
1107     <li><code>Window.show()</code>
1108     <li><code>Window.hide()</code>
1109     <li><code>Window.setVisible(boolean)</code>
1110     <li><code>Window.dispose()</code>
1111     <li><code>Frame.setState(int)</code>
1112   </ul>


1152         <b>Solaris</b>: The Window is moved to front. In a point-to-focus focus
1153         window manager, the Window will be focused if it is now the
1154         top-most Window under the cursor. In a click-to-focus window
1155         manager, the Window will become the focused Window.
1156 
1157      <li><code>Window.hide()/Window.setVisible(false)/Window.dispose()/
1158     Frame.setState(ICONIFIED)</code>:<br>
1159         <b>Microsoft Windows</b>: If the Window was the focused Window, the focused 
1160         Window is reset to a window chosen by the OS, or to no window. The
1161         window may be in a native application, or a Java application in
1162         another VM.
1163        <br>
1164         <b>Solaris</b>: If the Window was the focused Window, in a point-to-
1165         focus window manager, the top-most Window under the cursor will
1166         become the focused Window. In a click-to-focus window manager,
1167         the focused Window is reset to a window chosen by the window
1168         manager. The window may be in a native application, or a Java
1169         application in another VM.
1170   </ul>
1171 
1172 <a name="ReplacingDefaultKeyboardFocusManager"></a>
1173 <h3>Replacing DefaultKeyboardFocusManager</h3>
1174 <p>
1175 <code>KeyboardFocusManager</code>s are pluggable at the browser context
1176 level. Client code can subclass <code>KeyboardFocusManager</code> or
1177 <code>DefaultKeyboardFocusManager</code> to modify the way that WindowEvents
1178 related to focus, FocusEvents, and KeyEvents are handled and
1179 dispatched, and to examine and modify the global focus state. A custom
1180 <code>KeyboardFocusManager</code> can also reject focus changes at a more
1181 fundamental level then a FocusListener or WindowListener ever could.
1182 <p>
1183 While giving a developer ultimate control over the focus model,
1184 replacing the entire <code>KeyboardFocusManager</code> is a difficult process
1185 requiring a thorough understanding of the peer focus layer.
1186 Fortunately, most applications do not need this much control.
1187 Developers are encouraged to use KeyEventDispatchers,
1188 KeyEventPostProcessors, FocusTraversalPolicies,
1189 VetoableChangeListeners, and other concepts discussed in this document
1190 before resorting to a full replacement of the <code>KeyboardFocusManager</code>.
1191 <p>
1192 First note that, because unhindered access to Components in other


1308           heavyweight initially specified by the peer layer.
1309           <br>
1310           If the peer layer states that the opposite Component or Window is
1311           <code>null</code>, it is acceptable for the 
1312           <code>KeyboardFocusManager</code> to propagate
1313           this value. <code>null</code> indicates that it is highly
1314           probably that no other Component or Window was involved
1315           in the focus or activation change. Because of platform
1316           limitations, this computation may be
1317           subject to a heuristic and could be incorrect. Nevertheless, this
1318           heuristic will be the best possible guess which the peer layer
1319           could make.
1320        <li>Focus and activation changes in which a Component or Window loses
1321           focus or activation to itself must be discarded.
1322        <li>Events posted by the peer layer claiming that the active Window
1323           has lost focus to the focused Window must be discarded. The peer
1324           implementation of the Window class may generate these spurious
1325           events.
1326     </ul>
1327 
1328 <a name="Incompatibilities"></a>
1329 <h3>Incompatibilities with Previous Releases</h3>
1330   <p><b>Cross-platform changes:</b>
1331     <ol>
1332       <li>The default focus traversability for all Components is now
1333           'true'. Previously, some Components (in particular, all
1334           lightweights), had a default focus traversability of 'false'. Note
1335           that despite this change, however, the
1336           <code>DefaultFocusTraversalPolicy</code> for all AWT Containers
1337           will preserve the traversal order of previous releases.
1338       <li>A request to focus a non-focus traversable (i.e., non-focusable)
1339           Component will be denied. Previously, such requests were granted.
1340       <li><code>Window.toFront()</code> and <code>Window.toBack()</code>
1341           now perform no operation if the Window is not visible.
1342           Previously, the behavior was platform-dependent.
1343       <li>KeyListeners installed on <code>Component</code>s
1344           will no longer see <code>KeyEvent</code>s that map to focus
1345           traversal operations, and
1346           <code>Component.handleEvent()</code> will no longer be invoked 
1347           for such events. Previously, AWT Components saw these events
1348           and had an opportunity to consume them before AWT
   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>


  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


 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


 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.


 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>


 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


 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.


 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.


 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


 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>.


 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


 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>


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.


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>


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


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
< prev index next >