--- old/src/java.desktop/share/classes/java/awt/doc-files/FocusSpec.html 2017-10-23 13:51:02.000000000 -0700 +++ new/src/java.desktop/share/classes/java/awt/doc-files/FocusSpec.html 2017-10-23 13:51:02.000000000 -0700 @@ -1,5 +1,11 @@ + + +
+ +Prior to Java 2 Standard Edition, JDK 1.4, the AWT focus subsystem @@ -57,8 +56,8 @@ 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 - focus. Since Microsoft Windows provides this functionality for free, - developers migrating from Microsoft Windows C/C++ or Visual Basic to + focus. Since Microsoft Windows provides this functionality for free, + developers migrating from Microsoft Windows C/C++ or Visual Basic to Java had been frustrated by the omission.
To address these and other deficiencies, we have designed a new focus @@ -101,7 +100,7 @@
The focus model is centralized around a single class,
@@ -160,7 +159,7 @@
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
- setFocusTraversalPolicyProvider
on the Container.
+ setFocusTraversalPolicyProvider
on the Container.
@@ -180,7 +179,7 @@ descendants.
- Here is an example:
Assume the following: @@ -193,7 +192,7 @@
Component
s.
-
+
There are a total of three focus cycle roots in this example:
DefaultKeyboardFocusManager
class.
-
+
Some browsers partition applets in different code bases into separate @@ -229,7 +228,7 @@ owner, focused Window, or active Window, per ClassLoader. - +
While the user's KeyEvents should generally be delivered to the focus @@ -272,7 +271,7 @@ KeyEventPostProcessor, and similar restrictions apply to its use in that capacity. - +
The AWT defines the following six event types central to the focus @@ -296,7 +295,7 @@ not a Frame or Dialog) when it is no longer the active Window.
If the focus is not in java application and the user clicks on a focusable @@ -347,7 +346,7 @@ and VetoableChangeListener. - +
Each event includes information about the "opposite" Component or @@ -371,7 +370,7 @@ using the opposite Component of a focus change that occurred within a top-level Window. - +
FOCUS_GAINED
and FOCUS_LOST
events are
@@ -380,7 +379,7 @@
Temporary FOCUS_LOST
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
-of data. For instance, a text Component may want to commit its
+of data. For instance, a text Component may want to commit its
contents when the user begins interacting with another Component,
and can accomplish this by responding to FOCUS_LOST
events.
However, if the FocusEvent
received is temporary,
@@ -402,8 +401,8 @@
When a Component receives a temporary FOCUS_LOST
event,
the event's opposite Component (if any) may receive a temporary
FOCUS_GAINED
event, but could also receive a permanent
-FOCUS_GAINED
event. Showing a Menu or PopupMenu, or
-clicking or dragging a Scrollbar, should generate a temporary
+FOCUS_GAINED
event. Showing a Menu or PopupMenu, or
+clicking or dragging a Scrollbar, should generate a temporary
FOCUS_GAINED
event. Changing the focused Window,
however, will yield a permanent FOCUS_GAINED
event
for the new focus owner.
@@ -416,7 +415,7 @@
Components. This method is not intended for general use, but exists
instead as a hook for lightweight Component libraries, such as Swing.
-
+
Each Component defines its own Set of focus traversal keys for a given
@@ -428,11 +427,11 @@
recursively inherits a Set from its parent, and ultimately from a
context-wide default set on the current KeyboardFocusManager
.
-Using the AWTKeyStroke
API, client code can specify
-on which of two specific KeyEvents, KEY_PRESSED
or
+Using the AWTKeyStroke
API, client code can specify
+on which of two specific KeyEvents, KEY_PRESSED
or
KEY_RELEASED
, the focus traversal operation will occur.
Regardless of which KeyEvent is specified, however, all KeyEvents
-related to the focus traversal key, including the associated
+related to the focus traversal key, including the associated
KEY_TYPED
event, will be consumed, and will not be
dispatched to any Component. It is a runtime error to specify a
KEY_TYPED
event as mapping to a focus traversal operation,
@@ -475,7 +474,7 @@
normal focus traversal. Thus, the current
KeyboardFocusManager
maintains a reference to the
"current" focus cycle root, which is global across all contexts. The
-current focus cycle root is used to resolve the ambiguity.
+current focus cycle root is used to resolve the ambiguity.
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 @@ -491,10 +490,10 @@ root, then no focus traversal operation occurs. - +
-
+
A FocusTraversalPolicy
defines the order in which Components within
a particular focus cycle root or focus traversal policy provider are
traversed. Instances of FocusTraversalPolicy
can be shared across
@@ -524,7 +523,7 @@
-A FocusTraversalPolicy
may optionally provide an
+A FocusTraversalPolicy
may optionally provide an
algorithm for the following:
Given a Window, the "initial" Component in that Window. The initial @@ -551,7 +550,7 @@ ancestor. Top-levels initialize their focus traversal policies using the context default policy. The context default policy is established by using KeyboardFocusManager.setDefaultFocusTraversalPolicy
. - +AWT provides two standard
FocusTraversalPolicy
implementations for use by client code. @@ -573,14 +572,14 @@DefaultFocusTraversalPolicy
: A subclass ofContainerOrderFocusTraversalPolicy
which redefines the fitness test. If client code has explicitly set the - focusability of a Component by either overriding + focusability of a Component by either overridingComponent.isFocusTraversable()
orComponent.isFocusable()
, or by calling -Component.setFocusable(boolean)
, then a +Component.setFocusable(boolean)
, then aDefaultFocusTraversalPolicy
behaves exactly like aContainerOrderFocusTraversalPolicy
. If, however, the Component is relying on default focusability, then a -DefaultFocusTraversalPolicy
will reject all +DefaultFocusTraversalPolicy
will reject all Components with non-focusable peers.
The focusability of a peer is implementation-dependent. Sun @@ -627,7 +626,7 @@The figure below shows an implicit focus transfer: -
+
Assume the following:@@ -653,7 +652,7 @@ All other applications, including pure AWT applications, will use
- +DefaultFocusTraversalPolicy
by default. - +Focus Traversal Policy Providers
A Container that isn't a focus cycle root has an option to provide a @@ -674,7 +673,7 @@ If focus traversal policy provider property is set on a focus cycle root, it isn't considered a focus traversal policy provider and behaves just like any other focus cycle root. - +
The main difference between focus cycle roots and focus traversal policy providers is that the latter allow focus to enter and leave them just as all other @@ -740,7 +739,7 @@
Programmatic Traversal
In addition to user-initiated focus traversal, client code can @@ -811,7 +810,7 @@ unchanged. - +
Focusability
A focusable Component can become the focus owner ("focusability") and @@ -825,7 +824,7 @@ change this default by calling Component.setFocusable(boolean). - +
Focusable Windows
To support palette windows and input methods, client code can prevent @@ -877,7 +876,7 @@ all such focus change requests will fail. In this case, the global focus owner will be cleared and the focused Window will remain unchanged. - +
Requesting Focus
@@ -949,7 +948,7 @@ a temporary state. See Temporary FocusEvents - +
Focus and PropertyChangeListener
Client code can listen to changes in context-wide focus state, or to @@ -957,7 +956,7 @@ PropertyChangeListeners.
The
KeyboardFocusManager
supports the following properties: - +
focusOwner
: the focus ownerfocusedWindow
: the focused Window @@ -977,7 +976,7 @@A
PropertyChangeListener
installed on the currentKeyboardFocusManager
will only see these changes within -theKeyboardFocusManager
's context, even though the +theKeyboardFocusManager
's context, even though the focus owner, focused Window, active Window, and current focus cycle root comprise the global focus state shared by all contexts. We believe this is less intrusive than requiring client code to pass @@ -1001,7 +1000,7 @@ following focus-related properties:-
downCycleFocusTraversalKeys
: the Container's Set of +downCycleFocusTraversalKeys
: the Container's Set ofDOWN_CYCLE_TRAVERSAL_KEYS
focusTraversalPolicy
: the Container's focus traversal policy @@ -1020,10 +1019,10 @@focusCycleRoot
property. A Window is always a focus cycle root; this property cannot change.Focus and VetoableChangeListener
-The
KeyboardFocusManager
also supports +TheKeyboardFocusManager
also supportsVetoableChangeListener
s for the following properties:@@ -1054,13 +1053,13 @@
KeyboardFocusManager
is free to attempt to dispatch this event and it is the responsibility of theVetoableChangeListener
to veto it as well. In addition, -during processing of theFOCUS_GAINED
event, the +during processing of theFOCUS_GAINED
event, theKeyboardFocusManager
may attempt to resync the global focus state by synthesizing anotherFOCUS_LOST
event. This event must be vetoed just as the firstFOCUS_LOST
event was.-A
KeyboardFocusManager
may not hold any locks while -notifyingPropertyChangeListener
s of a state change. +AKeyboardFocusManager
may not hold any locks while +notifyingPropertyChangeListener
s of a state change. This requirement is relaxed forVetoableChangeListeners
, however. Therefore, client-definiedVetoableChangeListener
s should avoid acquiring additional locks inside @@ -1089,13 +1088,13 @@ vetoed focus changes and recovery attempts. - +Z-Order
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 -Solaris, many window managers use a point-to-focus model that ignores +its focused or active (if applicable) state. On Microsoft Windows, the +top-most Window is naturally the focused Window as well. However, on +Solaris, many window managers use a point-to-focus model that ignores Z-order in determining the focused Window. When focusing or activating Windows, the AWT adheres to the UI @@ -1114,8 +1113,8 @@ Microsoft Windows and Solaris is as follows:
- +
Window.toFront()
:
- Microsoft Windows: The Window is moved to front, if possible. - While we will always be able to move this Window in front of other + Microsoft Windows: The Window is moved to front, if possible. + While we will always be able to move this Window in front of other Windows in the same VM, Windows 98 and Windows 2000 do not allow an application to bring any of its windows to the front unless one of that application's windows is already in the foreground. In @@ -1129,15 +1128,15 @@ window manager, the focused Window will remain unchanged.Window.toBack()
:
- Microsoft Windows: The Window is moved to back. Note however - that Microsoft Windows insists that an owned Window always be in - front of all of its recursive owners. Thus, after the completion of - this operation, the Window may not be the lowest Java Window in the - Z-order. If the Window, or any of its owners, was the focused Window, + Microsoft Windows: The Window is moved to back. Note however + that Microsoft Windows insists that an owned Window always be in + front of all of its recursive owners. Thus, after the completion of + this operation, the Window may not be the lowest Java Window in the + Z-order. If the Window, or any of its owners, was the focused Window, then the focused Window is reset to the top-most Window in the VM.
- Solaris: The Window is moved to back. Like Microsoft Windows, - some window managers insist than an owned Window always be in front + Solaris: The Window is moved to back. Like Microsoft Windows, + some window managers insist than an owned Window always be in front of all of its recursive owners. Thus, after the completion of this operation, the Window may not be the lowest Java Window in the Z-order. If the Window was the focused Window, it will lose @@ -1156,7 +1155,7 @@Window.hide()/Window.setVisible(false)/Window.dispose()/ Frame.setState(ICONIFIED)
:
- Microsoft Windows: If the Window was the focused Window, the focused + Microsoft Windows: If the Window was the focused Window, the focused Window is reset to a window chosen by the OS, or to no window. The window may be in a native application, or a Java application in another VM. @@ -1169,7 +1168,7 @@ application in another VM.Replacing DefaultKeyboardFocusManager
KeyboardFocusManager
s are pluggable at the browser context @@ -1238,7 +1237,7 @@ heavyweight Container, not the focus owner.- A
FOCUS_LOST
event must be retargeted to the focus owner. Again, this is necessary because the peer layer is - unaware of lightweight Components. + unaware of lightweight Components.- A
WINDOW_LOST_FOCUS
event must be retargeted to the focused Window. The implementation of the Window class may cause the native focused Window to differ from the Java @@ -1269,7 +1268,7 @@ to set the global focus owner to a non-focusable Component.- If the
KeyboardFocusManager
attempts to set the global focused Window to a non-focusable Window. -- If the change is rejected by an installed +
- If the change is rejected by an installed
VetoableChangeListener
.@@ -1302,13 +1301,13 @@ recent focus owner.
- The
KeyboardFocusManager
must ensure that the opposite Component or Window are as accurate as the native - windowing platform permits. For example, the + windowing platform permits. For example, theKeyboardFocusManager
may need to retarget the opposite Component to a lightweight child of the heavyweight initially specified by the peer layer.
If the peer layer states that the opposite Component or Window is -null
, it is acceptable for the +null
, it is acceptable for theKeyboardFocusManager
to propagate this value.null
indicates that it is highly probably that no other Component or Window was involved @@ -1325,7 +1324,7 @@ events. - +Incompatibilities with Previous Releases
Cross-platform changes:
@@ -1343,7 +1342,7 @@
- KeyListeners installed on
Component
s will no longer seeKeyEvent
s that map to focus traversal operations, and -Component.handleEvent()
will no longer be invoked +Component.handleEvent()
will no longer be invoked for such events. Previously, AWT Components saw these events and had an opportunity to consume them before AWT initiated focus traversal. Code that requires this @@ -1352,7 +1351,7 @@ itself. Alternately, the code can use anAWTEventListener
orKeyEventDispatcher
to pre-listen to all -KeyEvent
s. +KeyEvent
s.Changes specific to Microsoft Windows: