< prev index next >

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

Print this page

        

@@ -1,7 +1,13 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8"/>
+  <title>The AWT Focus Subsystem</title>
+</head>
 <!--
- Copyright (c) 2001, 2013, Oracle and/or its affiliates. All rights reserved.
+ 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,19 +27,12 @@
  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>
+    <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,11 +98,11 @@
       <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>
+      <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,11 +177,11 @@
       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 
+     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,11 +210,11 @@
 
 <code>KeyboardFocusManager</code> is an abstract class. AWT provides a default
 implementation in the <code>DefaultKeyboardFocusManager</code> class.
 
 
-<a name="BrowserContexts"></a>
+<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,11 +226,11 @@
 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>
+<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,11 +269,11 @@
 <p>
 Like KeyEventDispatcher, KeyboardFocusManager also implements
 KeyEventPostProcessor, and similar restrictions apply to its use in
 that capacity.
 
-<a name="FocusEventAndWindowEvent"></a>
+<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,11 +293,11 @@
     <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>
+<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,11 +344,11 @@
 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>
+<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,11 +368,11 @@
 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>
+<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,11 +413,11 @@
 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>
+<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,11 +488,11 @@
 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>
+<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,11 +624,11 @@
         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>
+<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,11 +650,11 @@
 Containers by default.
 <p>
 All other applications, including pure AWT applications, will use
 <code>DefaultFocusTraversalPolicy</code> by default.
 
-<a name="FocusTraversalPolicyProviders"></a>
+<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,11 +737,11 @@
                and it is a focus traversal policy provider, then the last Component of
                that provider is returned
         </ul>
   </ul>
 
-<a name="ProgrammaticTraversal"></a>
+<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,11 +808,11 @@
 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>
+<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,11 +822,11 @@
 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>
+<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,11 +874,11 @@
 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>
+<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,11 +946,11 @@
 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>
+<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,11 +1017,11 @@
 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>
+<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,11 +1086,11 @@
 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>
+<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,11 +1166,11 @@
         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>
+<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,11 +1322,11 @@
           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>
+<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 >