<!--

 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 This code is free software; you can redistribute it and/or modify it

 under the terms of the GNU General Public License version 2 only, as

 published by the Free Software Foundation.  Oracle designates this

 particular file as subject to the "Classpath" exception as provided

 by Oracle in the LICENSE file that accompanied this code.

 This code is distributed in the hope that it will be useful, but WITHOUT

 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

 version 2 for more details (a copy is included in the LICENSE file that

 accompanied this code).

 You should have received a copy of the GNU General Public License version

 2 along with this work; if not, write to the Free Software Foundation,

 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 or visit www.oracle.com if you need additional information or have any

 questions.

-->

    <p>

      Prior to Java 2 Standard Edition, JDK 1.4, the AWT focus subsystem

      was inadequate. It suffered from major design and API problems,

      as well as over a hundred open bugs. Many of these bugs were caused by

      platform inconsistencies, or incompatibilities between the native

      focus system for heavyweights and the Java focus system for

      lightweights.

    <p>

      The single worst problem with the AWT focus implementation was the

      inability to query for the currently focused Component. Not only was

      there no API for such a query, but also, because of an insufficient

      architecture, such information was not even maintained by the code.

    <p>

      Almost as bad was the inability of lightweight children of a Window

      (not a Frame or a Dialog) to receive keyboard input. This problem

      existed because Windows never received <code>WINDOW_ACTIVATED</code>

      events and thus could never be activated, and only active Windows

      could contain focused Components.

    <p>

      In addition, many developers noted that the APIs for FocusEvent and

      WindowEvent were insufficient because they did not provide a way for

      determining the "opposite" Component involved in the focus or

      activation change. For example, when a Component received a FOCUS_LOST

      event, it had no way of knowing which Component was gaining

      Java had been frustrated by the omission.

    <p>

      To address these and other deficiencies, we have designed a new focus

      model for the AWT in JDK 1.4. The primary design changes were the

      construction of a new centralized KeyboardFocusManager class, and a

      lightweight focus architecture. The amount of focus-related,

      platform-dependent code has been minimized and replaced by fully

      pluggable and extensible public APIs in the AWT. While we have

      attempted to remain backward compatible with the existing

      implementation, we were forced to make minor incompatible changes in

      order to reach an elegant and workable conclusion. We anticipate that

      these incompatibilities will have only a trivial impact on existing

      applications.

    <p>

      This document is a formal specification both of the new APIs and of

      existing APIs which remain relevant in the new model. Combined with

      the javadoc for focus-related classes and methods, this document

      should enable developers to create substantial AWT and Swing

      applications with a focus behavior that is customized yet consistent

      across platforms.  This document has the following sections:

    <ul>

      <li><a href=#Overview>Overview of KeyboardFocusManager</a>

      <li><a href=#BrowserContexts>KeyboardFocusManager and Browser Contexts</a>

      <li><a href=#KeyEventDispatcher>KeyEventDispatcher</a>

      <li><a href=#FocusEventAndWindowEvent>FocusEvent and WindowEvent</a>

      <li><a href=#EventDelivery>Event Delivery</a>

      <li><a href=#OppositeComponents>Opposite Components and Windows</a>

      <li><a href=#TemporaryFocusEvents>Temporary FocusEvents</a>

      <li><a href=#FocusTraversal>Focus Traversal</a>

      <li><a href=#FocusTraversalPolicy>Focus Traversal Policy</a>

      <li><a href=#FocusTraversalPolicyProviders>Focus Traversal Policy Providers</a>

      <li><a href=#ProgrammaticTraversal>Programmatic Traversal</a>

      <li><a href=#Focusability>Focusability</a>

      <li><a href=#FocusableWindows>Focusable Windows</a>

      <li><a href=#RequestingFocus>Requesting Focus</a>

      <li><a href=#FocusAndPropertyChangeListener>Focus and PropertyChangeListener</a>

      <li><a href=#FocusAndVetoableChangeListener>Focus and VetoableChangeListener</a>

      <li><a href=#ZOrder>Z-Order</a>

      <li><a href=#ReplacingDefaultKeyboardFocusManager>Replacing DefaultKeyboardFocusManager</a>

      <li><a href=#Incompatibilities>Incompatibilities with Previous Releases</a>

     </ul>

      <h3>Overview of KeyboardFocusManager</h3>

    <p>

      The focus model is centralized around a single class,

      KeyboardFocusManager, that provides a set of APIs for client code to

      inquire about the current focus state, initiate focus changes, and

      replace default focus event dispatching with a custom dispatcher.

      Clients can inquire about the focus state directly, or can register a

      PropertyChangeListener that will receive PropertyChangeEvents when a

      change to the focus state occurs.

    <p>

      KeyboardFocusManager introduces the following main concepts and their

      terminology:

    <ol>

      <li>The "focus owner" -- the Component which typically receives

          keyboard input.

      <li>The "permanent focus owner" -- the last Component to receive

          focus permanently. The "focus owner" and the "permanent focus

          owner" are equivalent unless a temporary focus change is

          currently in effect. In such a situation, the "permanent focus

          owner" will again be the "focus owner" when the temporary focus

          change ends.

      <li>The "focused Window" -- the Window which contains the "focus

          owner".

      <li>The "active Window" -- the Frame or Dialog that is either the

          "focused Window", or the first Frame or Dialog that is an owner

          of the "focused Window".

      <li>"Focus traversal" -- the user's ability to change the "focus

          owner" without moving the cursor. Typically, this is done using

          the keyboard (for example, by using the TAB key), or an

          equivalent device in an accessible environment. Client code can

          also initiate traversal programmatically. Normal focus traversal

          can be either "forward" to the "next" Component, or "backward" to

          the "previous" Component.

      <li>"Focus traversal cycle" -- a portion of the Component hierarchy,

          such that normal focus traversal "forward" (or "backward") will

          traverse through all of the Components in the focus cycle, but no

          other Components. This cycle provides a mapping from an arbitrary

          Component in the cycle to its "next" (forward traversal) and

          "previous" (backward traversal) Components.

      <li>"Traversable Component" -- Component that is in the focus traversal

          cycle.

      <li>"Non-traversable Component" -- Component that is not in the focus

          traversal cycle. Note that a non-traversable Component can nevertheless

          be focused in other way (e.g. by direct focus request).

      <li>"Focus cycle root" -- Container that is the root of the Component

          hierarchy for a particular "focus traversal cycle". When the

          "focus owner" is a Component inside a particular cycle, normal

          forward and backward focus traversal cannot move the "focus

          owner" above the focus cycle root in the Component hierarchy.

          Instead, two additional traversal operations, "up cycle" and

          "down cycle", are defined to allow keyboard and programmatic

          navigation up and down the focus traversal cycle hierarchy. </li>

      <li>"Focus traversal policy provider" - Container which has

          "FocusTraversalPolicyProvider" property as true. This Container will

          be used to acquire focus traversal policy. This container doesn't

          define new focus cycle but only modifies the order by which its

          children are traversed "forward" and "backward". Focus traversal

          policy provider can be set using

    </ol>

    <p>

      Every Window and JInternalFrame is, by default, a "focus cycle

      root". If it's the only focus cycle root, then all of its

      focusable descendants should be in its focus cycle, and its focus

      traversal policy should enforce that they are by making sure that

      all will be reached during normal forward (or backward)

      traversal. If, on the other hand, the Window or JInternalFrame

      has descendants that are also focus cycle roots, then each such

      descendant is a member of two focus cycles: the one that it is

      the root of, and the one of its nearest focus-cycle-root

      ancestor. In order to traverse the focusable components belonging

      to the focus cycle of such a "descendant" focus cycle root, one

      first traverses (forward or backward) to reach the descendant,

      and then uses the "down cycle" operation to reach, in turn, its

      descendants.

     <p>

     alt="Three groups as described below: ABCF BDE and DGH. "><br>

     <p>Assume the following:

      <ul>

        <li><b>A</b> is a <code>Window</code>, which means that it

            must be a focus cycle root.

        <li><b>B</b> and <b>D</b> are <code>Container</code>s that

            are focus cycle roots.

        <li><b>C</b> is a <code>Container</code> that is not a focus cycle root.

        <li><b>G</b>, <b>H</b>, <b>E</b>, and <b>F</b> are all

            <code>Component</code>s.

      </ul>

     There are a total of three focus cycle roots in this example:

      <ol>

        <li><b>A</b> is a root, and <b>A</b>, <b>B</b>, <b>C</b>,

            and <b>F</b> are members of <b>A</b>'s cycle.

        <li><b>B</b> is a root, and <b>B</b>, <b>D</b>, and

            <b>E</b> are members of <b>B</b>'s cycle.

        <li><b>D</b> is a root, and <b>D</b>, <b>G</b>,

            and <b>H</b> are members of <b>D</b>'s cycle.

      </ol>

     Windows are the only Containers which, by default, are focus cycle

     roots.

<code>KeyboardFocusManager</code> is an abstract class. AWT provides a default

implementation in the <code>DefaultKeyboardFocusManager</code> class.

<h3>KeyboardFocusManager and Browser Contexts</h3>

<p>

Some browsers partition applets in different code bases into separate

contexts, and establish walls between these contexts. Each thread and

each Component is associated with a particular context and cannot

interfere with threads or access Components in other contexts. In such

a scenario, there will be one KeyboardFocusManager per context. Other

browsers place all applets into the same context, implying that there

will be only a single, global KeyboardFocusManager for all

applets. This behavior is implementation-dependent. Consult your

browser's documentation for more information. No matter how many

contexts there may be, however, there can never be more than one focus

owner, focused Window, or active Window, per ClassLoader.

<h3>KeyEventDispatcher and KeyEventPostProcessor</h3>

<p>

While the user's KeyEvents should generally be delivered to the focus

owner, there are rare cases where this is not desirable. An input

method is an example of a specialized Component that should receive

KeyEvents even though its associated text Component is and should

remain the focus owner.

<p>

A KeyEventDispatcher is a lightweight interface that allows client

code to pre-listen to all KeyEvents in a particular context. Instances

of classes that implement the interface and are registered with the

current KeyboardFocusManager will receive KeyEvents before they are

dispatched to the focus owner, allowing the KeyEventDispatcher to

retarget the event, consume it, dispatch it itself, or make other

changes.

<p>

For consistency, KeyboardFocusManager itself is a

KeyEventDispatcher. By default, the current KeyboardFocusManager will

be the sink for all KeyEvents not dispatched by the registered

KeyEventDispatchers. The current KeyboardFocusManager cannot be

completely deregistered as a KeyEventDispatcher. However, if a

KeyEventDispatcher reports that it dispatched the KeyEvent, regardless

of whether it actually did so, the KeyboardFocusManager will take no

further action with regard to the KeyEvent. (While it is possible for

client code to register the current KeyboardFocusManager as a

KeyEventDispatcher one or more times, there is no obvious reason why

this would be necessary, and therefore it is not recommended.)

<p>

Client-code may also post-listen to KeyEvents in a particular context

using the KeyEventPostProcessor interface. KeyEventPostProcessors

registered with the current KeyboardFocusManager will receive

KeyEvents after the KeyEvents have been dispatched to and handled by

the focus owner. The KeyEventPostProcessors will also receive

KeyEvents that would have been otherwise discarded because no

Component in the application currently owns the focus. This will allow

applications to implement features that require global KeyEvent post-

handling, such as menu shortcuts.

<p>

Like KeyEventDispatcher, KeyboardFocusManager also implements

KeyEventPostProcessor, and similar restrictions apply to its use in

that capacity.

<h3>FocusEvent and WindowEvent</h3>

<p>

The AWT defines the following six event types central to the focus

model in two different <code>java.awt.event</code> classes:

  <ol>

    <li><code>WindowEvent.WINDOW_ACTIVATED</code>: This event is

        dispatched to a Frame or Dialog (but never a Window which

        is not a Frame or Dialog) when it becomes the active Window.

    <li><code>WindowEvent.WINDOW_GAINED_FOCUS</code>: This event is

        dispatched to a Window when it becomes the focused Window.

        Only focusable Windows can receive this event.

    <li><code>FocusEvent.FOCUS_GAINED</code>: This event is dispatched

        to a Component when it becomes the focus owner. Only focusable

        Components can receive this event.

    <li><code>FocusEvent.FOCUS_LOST</code>: This event is dispatched

        to a Component when it is no longer the focus owner.

    <li><code>WindowEvent.WINDOW_LOST_FOCUS</code>: This event is

        dispatched to a Window when it is no longer the focused Window.

    <li><code>WindowEvent.WINDOW_DEACTIVATED</code>: This event is

        dispatched to a Frame or Dialog (but never a Window which is

        not a Frame or Dialog) when it is no longer the active Window.

  </ol>

<h3>Event Delivery</h3>

<p>

If the focus is not in java application and the user clicks on a focusable

child Component<b>a</b> of an inactive Frame <b>b</b>, the following events

will be dispatched and handled in order:

  <ol>

    <li><b>b</b> will receive a <code>WINDOW_ACTIVATED</code> event.

    <li>Next, <b>b</b> will receive a <code>WINDOW_GAINED_FOCUS</code> event.

    <li>Finally, <b>a</b> will receive a <code>FOCUS_GAINED</code> event.

  </ol>

If the user later clicks on a focusable child Component <b>c</b> of another

Frame <b>d</b>, the following events will be dispatched and handled in

order:

  <ol>

   <li><b>a</b> will receive a <code>FOCUS_LOST</code> event.

   <li><b>b</b> will receive a <code>WINDOW_LOST_FOCUS</code> event.

   <li><b>b</b> will receive a <code>WINDOW_DEACTIVATED</code> event.

   <li><b>d</b> will receive a <code>WINDOW_ACTIVATED</code> event.

   <li><b>d</b> will receive a <code>WINDOW_GAINED_FOCUS</code> event.

   <li><b>c</b> will receive a <code>FOCUS_GAINED</code> event.

  </ol>

Note that each event will be fully handled before the next event is

dispatched. This restriction will be enforced even if the Components

are in different contexts and are handled on different event

dispatching threads.

<p>

In addition, each event type will be dispatched in 1-to-1

correspondence with its opposite event type. For example, if a

Component receives a <code>FOCUS_GAINED</code> event, under no

circumstances can it ever receive another <code>FOCUS_GAINED</code>

event without an intervening <code>FOCUS_LOST</code> event.

<p>

Finally, it is important to note that these events are delivered for

informational purposes only. It is impossible, for example, to prevent

the delivery of a pending <code>FOCUS_GAINED</code> event by requesting

focus back to the Component losing focus while handling the preceding

<code>FOCUS_LOST</code> event. While client code may make such a request,

the pending <code>FOCUS_GAINED</code> will still be delivered,

followed later by the events transferring focus back to the original

focus owner.

<p>

If it is absolutely necessary to suppress the <code>FOCUS_GAINED</code> event,

client code can install a <code>VetoableChangeListener</code> which

rejects the focus change. See <a href="#FocusAndVetoableChangeListener">Focus

and VetoableChangeListener</a>.

<h3>Opposite Components and Windows</h3>

<p>

Each event includes information about the "opposite" Component or

Window involved in the focus or activation change. For example, for a

<code>FOCUS_GAINED</code> event, the opposite Component is the Component

that lost focus. If the focus or activation change occurs with a native

application, with a Java application in a different VM or context, or

with no other Component, then the opposite Component or Window is

null. This information is accessible using

<code>FocusEvent.getOppositeComponent</code> or

<code>WindowEvent.getOppositeWindow</code>.

<p>

On some platforms, it is not possible to discern the opposite

Component or Window when the focus or activation change occurs between

two different heavyweight Components. In these cases, the opposite

Component or Window may be set to null on some platforms, and to a

valid non-null value on other platforms. However, for a focus change

between two lightweight Components which share the same heavyweight

Container, the opposite Component will always be set correctly. Thus,

a pure Swing application can ignore this platform restriction when

using the opposite Component of a focus change that occurred within a

top-level Window.

<h3>Temporary FocusEvents</h3>

<p>

<code>FOCUS_GAINED</code> and <code>FOCUS_LOST</code> events are

marked as either temporary or permanent.

<p>

Temporary <code>FOCUS_LOST</code> events are sent when a Component is

losing the focus, but will regain the focus shortly. These events

can be useful when focus changes are used as triggers for validation

contents when the user begins interacting with another Component,

and can accomplish this by responding to <code>FOCUS_LOST</code> events.

However, if the <code>FocusEvent</code> received is temporary,

the commit should not be done, since the text field will be receiving

the focus again shortly.

<p>

A permanent focus transfer typically occurs as the result of a user

clicking on a selectable, heavyweight Component, focus traversal with

the keyboard or an equivalent input device, or from a call to

<code>requestFocus()</code> or <code>requestFocusInWindow()</code>.

<p>

A temporary focus transfer typically occurs as the result of showing a

Menu or PopupMenu, clicking or dragging a Scrollbar, moving a Window

by dragging the title bar, or making another Window the focused

Window. Note that on some platforms, these actions may not generate

any FocusEvents at all. On others, temporary focus transfers will

occur.

<p>

When a Component receives a temporary <code>FOCUS_LOST</code> event,

the event's opposite Component (if any) may receive a temporary

<code>FOCUS_GAINED</code> event, but could also receive a permanent

<code>FOCUS_GAINED</code> event. Changing the focused Window,

however, will yield a permanent <code>FOCUS_GAINED</code> event

for the new focus owner.

<p>

The Component class includes variants of <code>requestFocus</code> and

<code>requestFocusInWindow</code> which take a desired temporary state as a

parameter. However, because specifying an arbitrary temporary state

may not be implementable on all native windowing systems, correct

behavior for this method can be guaranteed only for lightweight

Components. This method is not intended for general use, but exists

instead as a hook for lightweight Component libraries, such as Swing.

<h3>Focus Traversal</h3>

<p>

Each Component defines its own Set of focus traversal keys for a given

focus traversal operation. Components support separate Sets of keys

for forward and backward traversal, and also for traversal up one

focus traversal cycle. Containers which are focus cycle roots also

support a Set of keys for traversal down one focus traversal cycle. If

a Set is not explicitly defined for a Component, that Component

recursively inherits a Set from its parent, and ultimately from a

context-wide default set on the current <code>KeyboardFocusManager</code>.

<p>

<code>KEY_RELEASED</code>, the focus traversal operation will occur.

Regardless of which KeyEvent is specified, however, all KeyEvents

<code>KEY_TYPED</code> event, will be consumed, and will not be

dispatched to any Component. It is a runtime error to specify a

<code>KEY_TYPED</code> event as mapping to a focus traversal operation,

or to map the same event to multiple focus traversal operations for any

particular Component or for a <code>KeyboardFocusManager</code>'s defaults.

<p>

The default focus traversal keys are implementation-dependent. Sun

recommends that the all implementations for a particular native

platform use the same keys. For Windows and Unix, the recommendations

are:

  <ul>

     <li>traverse forward to the next Component:

      <br><i>TextAreas</i>: <code>CTRL-TAB</code> on <code>KEY_PRESSED</code>

      <br><i>All others</i>: <code>TAB</code> on <code>KEY_PRESSED</code> and

                       <code>CTRL-TAB</code> on <code>KEY_PRESSED</code>

     <li>traverse backward to the previous Component:

      <br><i>TextAreas</i>: <code>CTRL-SHIFT-TAB</code> on

                       <code>KEY_PRESSED</code>

      <br><i>All others</i>: <code>SHIFT-TAB</code> on <code>KEY_PRESSED</code>

                       and <code>CTRL-SHIFT-TAB</code> on

                       <code>KEY_PRESSED</code>

     <li>traverse up one focus traversal cycle : &lt;none&gt;

     <li>traverse down one focus traversal cycle : &lt;none&gt;

  </ul>

<p>

Components can enable and disable all of their focus traversal keys en

masse using <code>Component.setFocusTraversalKeysEnabled</code>. When focus

traversal keys are disabled, the Component receives all KeyEvents for

those keys. When focus traversal keys are enabled, the Component never

receives KeyEvents for traversal keys; instead, the KeyEvents are

automatically mapped to focus traversal operations.

<p>

For normal forward and backward traversal, the AWT focus

implementation determines which Component to focus next based on the

<a href=#FocusTraversalPolicy><code>FocusTraversalPolicy</code></a> of

the focus owner's focus cycle root or focus traversal policy provider. If the

focus owner is a focus cycle root, then it may be ambiguous as to which

Components represent the next and previous Components to focus during

normal focus traversal. Thus, the current

<code>KeyboardFocusManager</code> maintains a reference to the

"current" focus cycle root, which is global across all contexts. The

<p>

For up-cycle traversal, the focus owner is set to the current focus

owner's focus cycle root, and the current focus cycle root is set to

the new focus owner's focus cycle root. If, however, the current focus

owner's focus cycle root is a top-level window, then the focus owner

is set to the focus cycle root's default component to focus, and the

current focus cycle root is unchanged.

<p>

For down-cycle traversal, if the current focus owner is a focus cycle

root, then the focus owner is set to the current focus owner's default

component to focus, and the current focus cycle root is set to the

current focus owner. If the current focus owner is not a focus cycle

root, then no focus traversal operation occurs.

<h3>FocusTraversalPolicy</h3>

<p>

A <code>FocusTraversalPolicy</code> defines the order in which Components within

a particular focus cycle root or focus traversal policy provider are

traversed. Instances of <code>FocusTraversalPolicy</code> can be shared across

Containers, allowing those Containers to implement the same traversal policy.

FocusTraversalPolicies do not need to be reinitialized when the

focus-traversal-cycle hierarchy changes.

<p>

Each <code>FocusTraversalPolicy</code> must define the following

five algorithms:

  <ol>

    <li>Given a focus cycle root and a Component <b>a</b> in that cycle, the

        next Component after <b>a</b>.

    <li>Given a focus cycle root and a Component <b>a</b> in that cycle, the

        previous Component before <b>a</b>.

    <li>Given a focus cycle root, the "first" Component in that cycle.

        The "first" Component is the Component to focus when traversal

        wraps in the forward direction.

    <li>Given a focus cycle root, the "last" Component in that cycle.

        The "last" Component is the Component to focus when traversal

        wraps in the reverse direction.

    <li>Given a focus cycle root, the "default" Component in that cycle.

        The "default" Component will be the first to receive focus when

        traversing down into a new focus traversal cycle. This may be the

        same as the "first" Component, but need not be.

  </ol>