< prev index next >
src/java.desktop/share/classes/java/awt/doc-files/FocusSpec.html
Print this page
*** 1,7 ****
<!--
! Copyright (c) 2001, 2013, Oracle and/or its affiliates. All rights reserved.
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
--- 1,13 ----
+ <!doctype html>
+ <html lang="en">
+ <head>
+ <meta charset="utf-8"/>
+ <title>The AWT Focus Subsystem</title>
+ </head>
<!--
! Copyright (c) 2001, 2017, Oracle and/or its affiliates. All rights reserved.
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
*** 21,39 ****
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.
-->
! <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
!
! <html>
! <head>
! <title>The AWT Focus Subsystem</title>
! </head>
!
! <body bgcolor="white">
! <h1 align=center>The AWT Focus Subsystem</h1>
<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
--- 27,38 ----
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.
-->
! <body>
! <h1>The AWT Focus Subsystem</h1>
<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
*** 99,109 ****
<li><a href=#ZOrder>Z-Order</a>
<li><a href=#ReplacingDefaultKeyboardFocusManager>Replacing DefaultKeyboardFocusManager</a>
<li><a href=#Incompatibilities>Incompatibilities with Previous Releases</a>
</ul>
! <a name="Overview"></a>
<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
--- 98,108 ----
<li><a href=#ZOrder>Z-Order</a>
<li><a href=#ReplacingDefaultKeyboardFocusManager>Replacing DefaultKeyboardFocusManager</a>
<li><a href=#Incompatibilities>Incompatibilities with Previous Releases</a>
</ul>
! <a id="Overview"></a>
<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
*** 178,188 ****
first traverses (forward or backward) to reach the descendant,
and then uses the "down cycle" operation to reach, in turn, its
descendants.
<p>
! Here is an example:<br> <img src="FocusCycle.gif" align=middle
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
--- 177,187 ----
first traverses (forward or backward) to reach the descendant,
and then uses the "down cycle" operation to reach, in turn, its
descendants.
<p>
! Here is an example:<br> <img src="FocusCycle.gif"
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
*** 211,221 ****
<code>KeyboardFocusManager</code> is an abstract class. AWT provides a default
implementation in the <code>DefaultKeyboardFocusManager</code> class.
! <a name="BrowserContexts"></a>
<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
--- 210,220 ----
<code>KeyboardFocusManager</code> is an abstract class. AWT provides a default
implementation in the <code>DefaultKeyboardFocusManager</code> class.
! <a id="BrowserContexts"></a>
<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
*** 227,237 ****
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.
! <a name="KeyEventDispatcher"></a>
<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
--- 226,236 ----
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.
! <a id="KeyEventDispatcher"></a>
<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
*** 270,280 ****
<p>
Like KeyEventDispatcher, KeyboardFocusManager also implements
KeyEventPostProcessor, and similar restrictions apply to its use in
that capacity.
! <a name="FocusEventAndWindowEvent"></a>
<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>
--- 269,279 ----
<p>
Like KeyEventDispatcher, KeyboardFocusManager also implements
KeyEventPostProcessor, and similar restrictions apply to its use in
that capacity.
! <a id="FocusEventAndWindowEvent"></a>
<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>
*** 294,304 ****
<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>
! <a name="EventDelivery"></a>
<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:
--- 293,303 ----
<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>
! <a id="EventDelivery"></a>
<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:
*** 345,355 ****
client code can install a <code>VetoableChangeListener</code> which
rejects the focus change. See <a href="#FocusAndVetoableChangeListener">Focus
and VetoableChangeListener</a>.
! <a name="OppositeComponents"></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
--- 344,354 ----
client code can install a <code>VetoableChangeListener</code> which
rejects the focus change. See <a href="#FocusAndVetoableChangeListener">Focus
and VetoableChangeListener</a>.
! <a id="OppositeComponents"></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
*** 369,379 ****
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.
! <a name="TemporaryFocusEvents"></a>
<h3>Temporary FocusEvents</h3>
<p>
<code>FOCUS_GAINED</code> and <code>FOCUS_LOST</code> events are
marked as either temporary or permanent.
<p>
--- 368,378 ----
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.
! <a id="TemporaryFocusEvents"></a>
<h3>Temporary FocusEvents</h3>
<p>
<code>FOCUS_GAINED</code> and <code>FOCUS_LOST</code> events are
marked as either temporary or permanent.
<p>
*** 414,424 ****
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.
! <a name="FocusTraversal"></a>
<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
--- 413,423 ----
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.
! <a id="FocusTraversal"></a>
<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
*** 489,499 ****
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.
! <a name="FocusTraversalPolicy"></a>
<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
--- 488,498 ----
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.
! <a id="FocusTraversalPolicy"></a>
<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
*** 625,635 ****
In addition, the fitness test is extended to exclude JComponents
that have or inherit empty InputMaps.
</ol>
<p>
The figure below shows an implicit focus transfer:
! <br><img src="ImplicitFocusTransfer.gif" align=middle alt="Implicit focus transfer."><br>
Assume the following:
<ul>
<li><b>A</b>, <b>B</b> and <b>C</b> are components in some window (a container)
<li><b>R</b> is a container in the window and it is a parent of <b>B</b> and <b>C</b>.
--- 624,634 ----
In addition, the fitness test is extended to exclude JComponents
that have or inherit empty InputMaps.
</ol>
<p>
The figure below shows an implicit focus transfer:
! <br><img src="ImplicitFocusTransfer.gif" alt="Implicit focus transfer."><br>
Assume the following:
<ul>
<li><b>A</b>, <b>B</b> and <b>C</b> are components in some window (a container)
<li><b>R</b> is a container in the window and it is a parent of <b>B</b> and <b>C</b>.
*** 651,661 ****
Containers by default.
<p>
All other applications, including pure AWT applications, will use
<code>DefaultFocusTraversalPolicy</code> by default.
! <a name="FocusTraversalPolicyProviders"></a>
<h3>Focus Traversal Policy Providers</h3>
<p>
A Container that isn't a focus cycle root has an option to provide a
FocusTraversalPolicy of its own. To do so, one needs to set Container's focus
traversal policy provider property to <code>true</code> with the call to
--- 650,660 ----
Containers by default.
<p>
All other applications, including pure AWT applications, will use
<code>DefaultFocusTraversalPolicy</code> by default.
! <a id="FocusTraversalPolicyProviders"></a>
<h3>Focus Traversal Policy Providers</h3>
<p>
A Container that isn't a focus cycle root has an option to provide a
FocusTraversalPolicy of its own. To do so, one needs to set Container's focus
traversal policy provider property to <code>true</code> with the call to
*** 738,748 ****
and it is a focus traversal policy provider, then the last Component of
that provider is returned
</ul>
</ul>
! <a name="ProgrammaticTraversal"></a>
<h3>Programmatic Traversal</h3>
<p>
In addition to user-initiated focus traversal, client code can
initiate a focus traversal operation programmatically. To client code,
programmatic traversals are indistinguishable from user-initiated
--- 737,747 ----
and it is a focus traversal policy provider, then the last Component of
that provider is returned
</ul>
</ul>
! <a id="ProgrammaticTraversal"></a>
<h3>Programmatic Traversal</h3>
<p>
In addition to user-initiated focus traversal, client code can
initiate a focus traversal operation programmatically. To client code,
programmatic traversals are indistinguishable from user-initiated
*** 809,819 ****
focus traversal by disabling the focus owner, directly or indirectly,
and there is no other Component to focus, then the focus owner remains
unchanged.
! <a name="Focusability"></a>
<h3>Focusability</h3>
<p>
A focusable Component can become the focus owner ("focusability") and
participates in keyboard focus traversal ("focus traversability") with
a FocusTraversalPolicy. There is no separation of these two concepts;
--- 808,818 ----
focus traversal by disabling the focus owner, directly or indirectly,
and there is no other Component to focus, then the focus owner remains
unchanged.
! <a id="Focusability"></a>
<h3>Focusability</h3>
<p>
A focusable Component can become the focus owner ("focusability") and
participates in keyboard focus traversal ("focus traversability") with
a FocusTraversalPolicy. There is no separation of these two concepts;
*** 823,833 ****
A Component expresses this state via the isFocusable() method. By
default, all Components return true from this method. Client code can
change this default by calling Component.setFocusable(boolean).
! <a name="FocusableWindows"></a>
<h3>Focusable Windows</h3>
<p>
To support palette windows and input methods, client code can prevent
a Window from becoming the focused Window. By transitivity, this
prevents the Window or any of its descendants from becoming the focus
--- 822,832 ----
A Component expresses this state via the isFocusable() method. By
default, all Components return true from this method. Client code can
change this default by calling Component.setFocusable(boolean).
! <a id="FocusableWindows"></a>
<h3>Focusable Windows</h3>
<p>
To support palette windows and input methods, client code can prevent
a Window from becoming the focused Window. By transitivity, this
prevents the Window or any of its descendants from becoming the focus
*** 875,885 ****
Since not all platforms support cross-Window focus changes (see
<a href=#RequestingFocus>Requesting Focus</a>), it is possible that
all such focus change requests will fail. In this case, the global
focus owner will be cleared and the focused Window will remain unchanged.
! <a name="RequestingFocus"></a>
<h3>Requesting Focus</h3>
<p>
A Component can request that it become the focus owner by calling
<code>Component.requestFocus()</code>. This initiates a permanent
--- 874,884 ----
Since not all platforms support cross-Window focus changes (see
<a href=#RequestingFocus>Requesting Focus</a>), it is possible that
all such focus change requests will fail. In this case, the global
focus owner will be cleared and the focused Window will remain unchanged.
! <a id="RequestingFocus"></a>
<h3>Requesting Focus</h3>
<p>
A Component can request that it become the focus owner by calling
<code>Component.requestFocus()</code>. This initiates a permanent
*** 947,957 ****
The Component class also supports variants of <code>requestFocus</code> and
<code>requestFocusInWindow</code> that allow client code to specify
a temporary state.
See <a href="#TemporaryFocusEvents">Temporary FocusEvents</a>
! <a name="FocusAndPropertyChangeListener"></a>
<h3>Focus and PropertyChangeListener</h3>
<p>
Client code can listen to changes in context-wide focus state, or to
changes in focus-related state in Components, via
PropertyChangeListeners.
--- 946,956 ----
The Component class also supports variants of <code>requestFocus</code> and
<code>requestFocusInWindow</code> that allow client code to specify
a temporary state.
See <a href="#TemporaryFocusEvents">Temporary FocusEvents</a>
! <a id="FocusAndPropertyChangeListener"></a>
<h3>Focus and PropertyChangeListener</h3>
<p>
Client code can listen to changes in context-wide focus state, or to
changes in focus-related state in Components, via
PropertyChangeListeners.
*** 1018,1028 ****
Also note that a <code>PropertyChangeListener</code> installed on a
Window will never see a <code>PropertyChangeEvent</code> for the
<code>focusCycleRoot</code> property.
A Window is always a focus cycle root; this property cannot change.
<p>
! <a name="FocusAndVetoableChangeListener"></a>
<h3>Focus and VetoableChangeListener</h3>
<p>
The <code>KeyboardFocusManager</code> also supports
<code>VetoableChangeListener</code>s for the following properties:
--- 1017,1027 ----
Also note that a <code>PropertyChangeListener</code> installed on a
Window will never see a <code>PropertyChangeEvent</code> for the
<code>focusCycleRoot</code> property.
A Window is always a focus cycle root; this property cannot change.
<p>
! <a id="FocusAndVetoableChangeListener"></a>
<h3>Focus and VetoableChangeListener</h3>
<p>
The <code>KeyboardFocusManager</code> also supports
<code>VetoableChangeListener</code>s for the following properties:
*** 1087,1097 ****
changes initiated as a result of veto rejection recovery. Failure
to anticipate this situation could lead to an infinite cycle of
vetoed focus changes and recovery attempts.
! <a name="ZOrder"></a>
<h3>Z-Order</h3>
<p>
On some native windowing systems, the Z-order of a Window can affect
its focused or active (if applicable) state. On Microsoft Windows, the
top-most Window is naturally the focused Window as well. However, on
--- 1086,1096 ----
changes initiated as a result of veto rejection recovery. Failure
to anticipate this situation could lead to an infinite cycle of
vetoed focus changes and recovery attempts.
! <a id="ZOrder"></a>
<h3>Z-Order</h3>
<p>
On some native windowing systems, the Z-order of a Window can affect
its focused or active (if applicable) state. On Microsoft Windows, the
top-most Window is naturally the focused Window as well. However, on
*** 1167,1177 ****
the focused Window is reset to a window chosen by the window
manager. The window may be in a native application, or a Java
application in another VM.
</ul>
! <a name="ReplacingDefaultKeyboardFocusManager"></a>
<h3>Replacing DefaultKeyboardFocusManager</h3>
<p>
<code>KeyboardFocusManager</code>s are pluggable at the browser context
level. Client code can subclass <code>KeyboardFocusManager</code> or
<code>DefaultKeyboardFocusManager</code> to modify the way that WindowEvents
--- 1166,1176 ----
the focused Window is reset to a window chosen by the window
manager. The window may be in a native application, or a Java
application in another VM.
</ul>
! <a id="ReplacingDefaultKeyboardFocusManager"></a>
<h3>Replacing DefaultKeyboardFocusManager</h3>
<p>
<code>KeyboardFocusManager</code>s are pluggable at the browser context
level. Client code can subclass <code>KeyboardFocusManager</code> or
<code>DefaultKeyboardFocusManager</code> to modify the way that WindowEvents
*** 1323,1333 ****
has lost focus to the focused Window must be discarded. The peer
implementation of the Window class may generate these spurious
events.
</ul>
! <a name="Incompatibilities"></a>
<h3>Incompatibilities with Previous Releases</h3>
<p><b>Cross-platform changes:</b>
<ol>
<li>The default focus traversability for all Components is now
'true'. Previously, some Components (in particular, all
--- 1322,1332 ----
has lost focus to the focused Window must be discarded. The peer
implementation of the Window class may generate these spurious
events.
</ul>
! <a id="Incompatibilities"></a>
<h3>Incompatibilities with Previous Releases</h3>
<p><b>Cross-platform changes:</b>
<ol>
<li>The default focus traversability for all Components is now
'true'. Previously, some Components (in particular, all
< prev index next >