src/java.desktop/share/classes/java/awt/doc-files/FocusSpec.html
author serb
Wed, 29 Nov 2017 15:11:37 -0800
changeset 48264 efda6932a433
parent 47216 71c04702a3d5
child 50358 1ba28f0dbc33
permissions -rw-r--r--
8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html 8183508: multi_tsc.html should be updated 8181289: Invalid HTML 5 in AWT/Swing docs Reviewed-by: prr, jjg
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
     1
<!doctype html>
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
     2
<html lang="en">
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
     3
<head>
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
     4
  <meta charset="utf-8"/>
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
     5
  <title>The AWT Focus Subsystem</title>
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
     6
</head>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     7
<!--
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
     8
 Copyright (c) 2001, 2017, Oracle and/or its affiliates. All rights reserved.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
     9
 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    10
90ce3da70b43 Initial load
duke
parents:
diff changeset
    11
 This code is free software; you can redistribute it and/or modify it
90ce3da70b43 Initial load
duke
parents:
diff changeset
    12
 under the terms of the GNU General Public License version 2 only, as
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    13
 published by the Free Software Foundation.  Oracle designates this
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    14
 particular file as subject to the "Classpath" exception as provided
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    15
 by Oracle in the LICENSE file that accompanied this code.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    16
90ce3da70b43 Initial load
duke
parents:
diff changeset
    17
 This code is distributed in the hope that it will be useful, but WITHOUT
90ce3da70b43 Initial load
duke
parents:
diff changeset
    18
 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
90ce3da70b43 Initial load
duke
parents:
diff changeset
    19
 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
90ce3da70b43 Initial load
duke
parents:
diff changeset
    20
 version 2 for more details (a copy is included in the LICENSE file that
90ce3da70b43 Initial load
duke
parents:
diff changeset
    21
 accompanied this code).
90ce3da70b43 Initial load
duke
parents:
diff changeset
    22
90ce3da70b43 Initial load
duke
parents:
diff changeset
    23
 You should have received a copy of the GNU General Public License version
90ce3da70b43 Initial load
duke
parents:
diff changeset
    24
 2 along with this work; if not, write to the Free Software Foundation,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    25
 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    26
5506
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    27
 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    28
 or visit www.oracle.com if you need additional information or have any
202f599c92aa 6943119: Rebrand source copyright notices
ohair
parents: 2
diff changeset
    29
 questions.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    30
-->
90ce3da70b43 Initial load
duke
parents:
diff changeset
    31
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
    32
    <body>
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
    33
      <h1>The AWT Focus Subsystem</h1>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    34
90ce3da70b43 Initial load
duke
parents:
diff changeset
    35
    <p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    36
      Prior to Java 2 Standard Edition, JDK 1.4, the AWT focus subsystem
90ce3da70b43 Initial load
duke
parents:
diff changeset
    37
      was inadequate. It suffered from major design and API problems,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    38
      as well as over a hundred open bugs. Many of these bugs were caused by
90ce3da70b43 Initial load
duke
parents:
diff changeset
    39
      platform inconsistencies, or incompatibilities between the native
90ce3da70b43 Initial load
duke
parents:
diff changeset
    40
      focus system for heavyweights and the Java focus system for
90ce3da70b43 Initial load
duke
parents:
diff changeset
    41
      lightweights.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    42
    <p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    43
      The single worst problem with the AWT focus implementation was the
90ce3da70b43 Initial load
duke
parents:
diff changeset
    44
      inability to query for the currently focused Component. Not only was
90ce3da70b43 Initial load
duke
parents:
diff changeset
    45
      there no API for such a query, but also, because of an insufficient
90ce3da70b43 Initial load
duke
parents:
diff changeset
    46
      architecture, such information was not even maintained by the code.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    47
    <p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    48
      Almost as bad was the inability of lightweight children of a Window
90ce3da70b43 Initial load
duke
parents:
diff changeset
    49
      (not a Frame or a Dialog) to receive keyboard input. This problem
90ce3da70b43 Initial load
duke
parents:
diff changeset
    50
      existed because Windows never received <code>WINDOW_ACTIVATED</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    51
      events and thus could never be activated, and only active Windows
90ce3da70b43 Initial load
duke
parents:
diff changeset
    52
      could contain focused Components.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    53
    <p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    54
      In addition, many developers noted that the APIs for FocusEvent and
90ce3da70b43 Initial load
duke
parents:
diff changeset
    55
      WindowEvent were insufficient because they did not provide a way for
90ce3da70b43 Initial load
duke
parents:
diff changeset
    56
      determining the "opposite" Component involved in the focus or
90ce3da70b43 Initial load
duke
parents:
diff changeset
    57
      activation change. For example, when a Component received a FOCUS_LOST
90ce3da70b43 Initial load
duke
parents:
diff changeset
    58
      event, it had no way of knowing which Component was gaining
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
    59
      focus. Since Microsoft Windows provides this functionality for free,
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
    60
      developers migrating from Microsoft Windows C/C++ or Visual Basic to
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
    61
      Java had been frustrated by the omission.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    62
    <p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    63
      To address these and other deficiencies, we have designed a new focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
    64
      model for the AWT in JDK 1.4. The primary design changes were the
90ce3da70b43 Initial load
duke
parents:
diff changeset
    65
      construction of a new centralized KeyboardFocusManager class, and a
90ce3da70b43 Initial load
duke
parents:
diff changeset
    66
      lightweight focus architecture. The amount of focus-related,
90ce3da70b43 Initial load
duke
parents:
diff changeset
    67
      platform-dependent code has been minimized and replaced by fully
90ce3da70b43 Initial load
duke
parents:
diff changeset
    68
      pluggable and extensible public APIs in the AWT. While we have
90ce3da70b43 Initial load
duke
parents:
diff changeset
    69
      attempted to remain backward compatible with the existing
90ce3da70b43 Initial load
duke
parents:
diff changeset
    70
      implementation, we were forced to make minor incompatible changes in
90ce3da70b43 Initial load
duke
parents:
diff changeset
    71
      order to reach an elegant and workable conclusion. We anticipate that
90ce3da70b43 Initial load
duke
parents:
diff changeset
    72
      these incompatibilities will have only a trivial impact on existing
90ce3da70b43 Initial load
duke
parents:
diff changeset
    73
      applications.
90ce3da70b43 Initial load
duke
parents:
diff changeset
    74
    <p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    75
      This document is a formal specification both of the new APIs and of
90ce3da70b43 Initial load
duke
parents:
diff changeset
    76
      existing APIs which remain relevant in the new model. Combined with
90ce3da70b43 Initial load
duke
parents:
diff changeset
    77
      the javadoc for focus-related classes and methods, this document
90ce3da70b43 Initial load
duke
parents:
diff changeset
    78
      should enable developers to create substantial AWT and Swing
90ce3da70b43 Initial load
duke
parents:
diff changeset
    79
      applications with a focus behavior that is customized yet consistent
90ce3da70b43 Initial load
duke
parents:
diff changeset
    80
      across platforms.  This document has the following sections:
90ce3da70b43 Initial load
duke
parents:
diff changeset
    81
    <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    82
      <li><a href=#Overview>Overview of KeyboardFocusManager</a>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    83
      <li><a href=#BrowserContexts>KeyboardFocusManager and Browser Contexts</a>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    84
      <li><a href=#KeyEventDispatcher>KeyEventDispatcher</a>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    85
      <li><a href=#FocusEventAndWindowEvent>FocusEvent and WindowEvent</a>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    86
      <li><a href=#EventDelivery>Event Delivery</a>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    87
      <li><a href=#OppositeComponents>Opposite Components and Windows</a>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    88
      <li><a href=#TemporaryFocusEvents>Temporary FocusEvents</a>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    89
      <li><a href=#FocusTraversal>Focus Traversal</a>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    90
      <li><a href=#FocusTraversalPolicy>Focus Traversal Policy</a>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    91
      <li><a href=#FocusTraversalPolicyProviders>Focus Traversal Policy Providers</a>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    92
      <li><a href=#ProgrammaticTraversal>Programmatic Traversal</a>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    93
      <li><a href=#Focusability>Focusability</a>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    94
      <li><a href=#FocusableWindows>Focusable Windows</a>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    95
      <li><a href=#RequestingFocus>Requesting Focus</a>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    96
      <li><a href=#FocusAndPropertyChangeListener>Focus and PropertyChangeListener</a>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    97
      <li><a href=#FocusAndVetoableChangeListener>Focus and VetoableChangeListener</a>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    98
      <li><a href=#ZOrder>Z-Order</a>
90ce3da70b43 Initial load
duke
parents:
diff changeset
    99
      <li><a href=#ReplacingDefaultKeyboardFocusManager>Replacing DefaultKeyboardFocusManager</a>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   100
      <li><a href=#Incompatibilities>Incompatibilities with Previous Releases</a>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   101
     </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   102
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   103
      <a id="Overview"></a>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   104
      <h3>Overview of KeyboardFocusManager</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   105
    <p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   106
      The focus model is centralized around a single class,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   107
      KeyboardFocusManager, that provides a set of APIs for client code to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   108
      inquire about the current focus state, initiate focus changes, and
90ce3da70b43 Initial load
duke
parents:
diff changeset
   109
      replace default focus event dispatching with a custom dispatcher.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   110
      Clients can inquire about the focus state directly, or can register a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   111
      PropertyChangeListener that will receive PropertyChangeEvents when a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   112
      change to the focus state occurs.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   113
    <p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   114
      KeyboardFocusManager introduces the following main concepts and their
90ce3da70b43 Initial load
duke
parents:
diff changeset
   115
      terminology:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   116
    <ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   117
      <li>The "focus owner" -- the Component which typically receives
90ce3da70b43 Initial load
duke
parents:
diff changeset
   118
          keyboard input.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   119
      <li>The "permanent focus owner" -- the last Component to receive
90ce3da70b43 Initial load
duke
parents:
diff changeset
   120
          focus permanently. The "focus owner" and the "permanent focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
   121
          owner" are equivalent unless a temporary focus change is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   122
          currently in effect. In such a situation, the "permanent focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
   123
          owner" will again be the "focus owner" when the temporary focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
   124
          change ends.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   125
      <li>The "focused Window" -- the Window which contains the "focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
   126
          owner".
90ce3da70b43 Initial load
duke
parents:
diff changeset
   127
      <li>The "active Window" -- the Frame or Dialog that is either the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   128
          "focused Window", or the first Frame or Dialog that is an owner
90ce3da70b43 Initial load
duke
parents:
diff changeset
   129
          of the "focused Window".
90ce3da70b43 Initial load
duke
parents:
diff changeset
   130
      <li>"Focus traversal" -- the user's ability to change the "focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
   131
          owner" without moving the cursor. Typically, this is done using
90ce3da70b43 Initial load
duke
parents:
diff changeset
   132
          the keyboard (for example, by using the TAB key), or an
90ce3da70b43 Initial load
duke
parents:
diff changeset
   133
          equivalent device in an accessible environment. Client code can
90ce3da70b43 Initial load
duke
parents:
diff changeset
   134
          also initiate traversal programmatically. Normal focus traversal
90ce3da70b43 Initial load
duke
parents:
diff changeset
   135
          can be either "forward" to the "next" Component, or "backward" to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   136
          the "previous" Component.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   137
      <li>"Focus traversal cycle" -- a portion of the Component hierarchy,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   138
          such that normal focus traversal "forward" (or "backward") will
90ce3da70b43 Initial load
duke
parents:
diff changeset
   139
          traverse through all of the Components in the focus cycle, but no
90ce3da70b43 Initial load
duke
parents:
diff changeset
   140
          other Components. This cycle provides a mapping from an arbitrary
90ce3da70b43 Initial load
duke
parents:
diff changeset
   141
          Component in the cycle to its "next" (forward traversal) and
90ce3da70b43 Initial load
duke
parents:
diff changeset
   142
          "previous" (backward traversal) Components.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   143
      <li>"Traversable Component" -- Component that is in the focus traversal
90ce3da70b43 Initial load
duke
parents:
diff changeset
   144
          cycle.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   145
      <li>"Non-traversable Component" -- Component that is not in the focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
   146
          traversal cycle. Note that a non-traversable Component can nevertheless
90ce3da70b43 Initial load
duke
parents:
diff changeset
   147
          be focused in other way (e.g. by direct focus request).
90ce3da70b43 Initial load
duke
parents:
diff changeset
   148
      <li>"Focus cycle root" -- Container that is the root of the Component
90ce3da70b43 Initial load
duke
parents:
diff changeset
   149
          hierarchy for a particular "focus traversal cycle". When the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   150
          "focus owner" is a Component inside a particular cycle, normal
90ce3da70b43 Initial load
duke
parents:
diff changeset
   151
          forward and backward focus traversal cannot move the "focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
   152
          owner" above the focus cycle root in the Component hierarchy.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   153
          Instead, two additional traversal operations, "up cycle" and
90ce3da70b43 Initial load
duke
parents:
diff changeset
   154
          "down cycle", are defined to allow keyboard and programmatic
90ce3da70b43 Initial load
duke
parents:
diff changeset
   155
          navigation up and down the focus traversal cycle hierarchy. </li>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   156
      <li>"Focus traversal policy provider" - Container which has
90ce3da70b43 Initial load
duke
parents:
diff changeset
   157
          "FocusTraversalPolicyProvider" property as true. This Container will
90ce3da70b43 Initial load
duke
parents:
diff changeset
   158
          be used to acquire focus traversal policy. This container doesn't
90ce3da70b43 Initial load
duke
parents:
diff changeset
   159
          define new focus cycle but only modifies the order by which its
90ce3da70b43 Initial load
duke
parents:
diff changeset
   160
          children are traversed "forward" and "backward". Focus traversal
90ce3da70b43 Initial load
duke
parents:
diff changeset
   161
          policy provider can be set using
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   162
          <code>setFocusTraversalPolicyProvider</code> on the Container.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   163
    </ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   164
90ce3da70b43 Initial load
duke
parents:
diff changeset
   165
    <p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   166
      Every Window and JInternalFrame is, by default, a "focus cycle
90ce3da70b43 Initial load
duke
parents:
diff changeset
   167
      root". If it's the only focus cycle root, then all of its
90ce3da70b43 Initial load
duke
parents:
diff changeset
   168
      focusable descendants should be in its focus cycle, and its focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
   169
      traversal policy should enforce that they are by making sure that
90ce3da70b43 Initial load
duke
parents:
diff changeset
   170
      all will be reached during normal forward (or backward)
90ce3da70b43 Initial load
duke
parents:
diff changeset
   171
      traversal. If, on the other hand, the Window or JInternalFrame
90ce3da70b43 Initial load
duke
parents:
diff changeset
   172
      has descendants that are also focus cycle roots, then each such
90ce3da70b43 Initial load
duke
parents:
diff changeset
   173
      descendant is a member of two focus cycles: the one that it is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   174
      the root of, and the one of its nearest focus-cycle-root
90ce3da70b43 Initial load
duke
parents:
diff changeset
   175
      ancestor. In order to traverse the focusable components belonging
90ce3da70b43 Initial load
duke
parents:
diff changeset
   176
      to the focus cycle of such a "descendant" focus cycle root, one
90ce3da70b43 Initial load
duke
parents:
diff changeset
   177
      first traverses (forward or backward) to reach the descendant,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   178
      and then uses the "down cycle" operation to reach, in turn, its
90ce3da70b43 Initial load
duke
parents:
diff changeset
   179
      descendants.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   180
90ce3da70b43 Initial load
duke
parents:
diff changeset
   181
     <p>
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   182
     Here is an example:<br> <img src="FocusCycle.gif"
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   183
     alt="Three groups as described below: ABCF BDE and DGH. "><br>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   184
90ce3da70b43 Initial load
duke
parents:
diff changeset
   185
     <p>Assume the following:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   186
      <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   187
        <li><b>A</b> is a <code>Window</code>, which means that it
90ce3da70b43 Initial load
duke
parents:
diff changeset
   188
            must be a focus cycle root.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   189
        <li><b>B</b> and <b>D</b> are <code>Container</code>s that
90ce3da70b43 Initial load
duke
parents:
diff changeset
   190
            are focus cycle roots.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   191
        <li><b>C</b> is a <code>Container</code> that is not a focus cycle root.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   192
        <li><b>G</b>, <b>H</b>, <b>E</b>, and <b>F</b> are all
90ce3da70b43 Initial load
duke
parents:
diff changeset
   193
            <code>Component</code>s.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   194
      </ul>
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   195
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   196
     There are a total of three focus cycle roots in this example:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   197
90ce3da70b43 Initial load
duke
parents:
diff changeset
   198
      <ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   199
        <li><b>A</b> is a root, and <b>A</b>, <b>B</b>, <b>C</b>,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   200
            and <b>F</b> are members of <b>A</b>'s cycle.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   201
        <li><b>B</b> is a root, and <b>B</b>, <b>D</b>, and
90ce3da70b43 Initial load
duke
parents:
diff changeset
   202
            <b>E</b> are members of <b>B</b>'s cycle.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   203
        <li><b>D</b> is a root, and <b>D</b>, <b>G</b>,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   204
            and <b>H</b> are members of <b>D</b>'s cycle.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   205
      </ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   206
90ce3da70b43 Initial load
duke
parents:
diff changeset
   207
     Windows are the only Containers which, by default, are focus cycle
90ce3da70b43 Initial load
duke
parents:
diff changeset
   208
     roots.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   209
90ce3da70b43 Initial load
duke
parents:
diff changeset
   210
90ce3da70b43 Initial load
duke
parents:
diff changeset
   211
<code>KeyboardFocusManager</code> is an abstract class. AWT provides a default
90ce3da70b43 Initial load
duke
parents:
diff changeset
   212
implementation in the <code>DefaultKeyboardFocusManager</code> class.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   213
90ce3da70b43 Initial load
duke
parents:
diff changeset
   214
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   215
<a id="BrowserContexts"></a>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   216
<h3>KeyboardFocusManager and Browser Contexts</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   217
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   218
Some browsers partition applets in different code bases into separate
90ce3da70b43 Initial load
duke
parents:
diff changeset
   219
contexts, and establish walls between these contexts. Each thread and
90ce3da70b43 Initial load
duke
parents:
diff changeset
   220
each Component is associated with a particular context and cannot
90ce3da70b43 Initial load
duke
parents:
diff changeset
   221
interfere with threads or access Components in other contexts. In such
90ce3da70b43 Initial load
duke
parents:
diff changeset
   222
a scenario, there will be one KeyboardFocusManager per context. Other
90ce3da70b43 Initial load
duke
parents:
diff changeset
   223
browsers place all applets into the same context, implying that there
90ce3da70b43 Initial load
duke
parents:
diff changeset
   224
will be only a single, global KeyboardFocusManager for all
90ce3da70b43 Initial load
duke
parents:
diff changeset
   225
applets. This behavior is implementation-dependent. Consult your
90ce3da70b43 Initial load
duke
parents:
diff changeset
   226
browser's documentation for more information. No matter how many
90ce3da70b43 Initial load
duke
parents:
diff changeset
   227
contexts there may be, however, there can never be more than one focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
   228
owner, focused Window, or active Window, per ClassLoader.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   229
90ce3da70b43 Initial load
duke
parents:
diff changeset
   230
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   231
<a id="KeyEventDispatcher"></a>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   232
<h3>KeyEventDispatcher and KeyEventPostProcessor</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   233
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   234
While the user's KeyEvents should generally be delivered to the focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
   235
owner, there are rare cases where this is not desirable. An input
90ce3da70b43 Initial load
duke
parents:
diff changeset
   236
method is an example of a specialized Component that should receive
90ce3da70b43 Initial load
duke
parents:
diff changeset
   237
KeyEvents even though its associated text Component is and should
90ce3da70b43 Initial load
duke
parents:
diff changeset
   238
remain the focus owner.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   239
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   240
A KeyEventDispatcher is a lightweight interface that allows client
90ce3da70b43 Initial load
duke
parents:
diff changeset
   241
code to pre-listen to all KeyEvents in a particular context. Instances
90ce3da70b43 Initial load
duke
parents:
diff changeset
   242
of classes that implement the interface and are registered with the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   243
current KeyboardFocusManager will receive KeyEvents before they are
90ce3da70b43 Initial load
duke
parents:
diff changeset
   244
dispatched to the focus owner, allowing the KeyEventDispatcher to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   245
retarget the event, consume it, dispatch it itself, or make other
90ce3da70b43 Initial load
duke
parents:
diff changeset
   246
changes.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   247
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   248
For consistency, KeyboardFocusManager itself is a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   249
KeyEventDispatcher. By default, the current KeyboardFocusManager will
90ce3da70b43 Initial load
duke
parents:
diff changeset
   250
be the sink for all KeyEvents not dispatched by the registered
90ce3da70b43 Initial load
duke
parents:
diff changeset
   251
KeyEventDispatchers. The current KeyboardFocusManager cannot be
90ce3da70b43 Initial load
duke
parents:
diff changeset
   252
completely deregistered as a KeyEventDispatcher. However, if a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   253
KeyEventDispatcher reports that it dispatched the KeyEvent, regardless
90ce3da70b43 Initial load
duke
parents:
diff changeset
   254
of whether it actually did so, the KeyboardFocusManager will take no
90ce3da70b43 Initial load
duke
parents:
diff changeset
   255
further action with regard to the KeyEvent. (While it is possible for
90ce3da70b43 Initial load
duke
parents:
diff changeset
   256
client code to register the current KeyboardFocusManager as a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   257
KeyEventDispatcher one or more times, there is no obvious reason why
90ce3da70b43 Initial load
duke
parents:
diff changeset
   258
this would be necessary, and therefore it is not recommended.)
90ce3da70b43 Initial load
duke
parents:
diff changeset
   259
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   260
Client-code may also post-listen to KeyEvents in a particular context
90ce3da70b43 Initial load
duke
parents:
diff changeset
   261
using the KeyEventPostProcessor interface. KeyEventPostProcessors
90ce3da70b43 Initial load
duke
parents:
diff changeset
   262
registered with the current KeyboardFocusManager will receive
90ce3da70b43 Initial load
duke
parents:
diff changeset
   263
KeyEvents after the KeyEvents have been dispatched to and handled by
90ce3da70b43 Initial load
duke
parents:
diff changeset
   264
the focus owner. The KeyEventPostProcessors will also receive
90ce3da70b43 Initial load
duke
parents:
diff changeset
   265
KeyEvents that would have been otherwise discarded because no
90ce3da70b43 Initial load
duke
parents:
diff changeset
   266
Component in the application currently owns the focus. This will allow
90ce3da70b43 Initial load
duke
parents:
diff changeset
   267
applications to implement features that require global KeyEvent post-
90ce3da70b43 Initial load
duke
parents:
diff changeset
   268
handling, such as menu shortcuts.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   269
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   270
Like KeyEventDispatcher, KeyboardFocusManager also implements
90ce3da70b43 Initial load
duke
parents:
diff changeset
   271
KeyEventPostProcessor, and similar restrictions apply to its use in
90ce3da70b43 Initial load
duke
parents:
diff changeset
   272
that capacity.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   273
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   274
<a id="FocusEventAndWindowEvent"></a>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   275
<h3>FocusEvent and WindowEvent</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   276
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   277
The AWT defines the following six event types central to the focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
   278
model in two different <code>java.awt.event</code> classes:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   279
  <ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   280
    <li><code>WindowEvent.WINDOW_ACTIVATED</code>: This event is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   281
        dispatched to a Frame or Dialog (but never a Window which
90ce3da70b43 Initial load
duke
parents:
diff changeset
   282
        is not a Frame or Dialog) when it becomes the active Window.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   283
    <li><code>WindowEvent.WINDOW_GAINED_FOCUS</code>: This event is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   284
        dispatched to a Window when it becomes the focused Window.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   285
        Only focusable Windows can receive this event.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   286
    <li><code>FocusEvent.FOCUS_GAINED</code>: This event is dispatched
90ce3da70b43 Initial load
duke
parents:
diff changeset
   287
        to a Component when it becomes the focus owner. Only focusable
90ce3da70b43 Initial load
duke
parents:
diff changeset
   288
        Components can receive this event.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   289
    <li><code>FocusEvent.FOCUS_LOST</code>: This event is dispatched
90ce3da70b43 Initial load
duke
parents:
diff changeset
   290
        to a Component when it is no longer the focus owner.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   291
    <li><code>WindowEvent.WINDOW_LOST_FOCUS</code>: This event is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   292
        dispatched to a Window when it is no longer the focused Window.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   293
    <li><code>WindowEvent.WINDOW_DEACTIVATED</code>: This event is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   294
        dispatched to a Frame or Dialog (but never a Window which is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   295
        not a Frame or Dialog) when it is no longer the active Window.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   296
  </ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   297
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   298
<a id="EventDelivery"></a>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   299
<h3>Event Delivery</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   300
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   301
If the focus is not in java application and the user clicks on a focusable
90ce3da70b43 Initial load
duke
parents:
diff changeset
   302
child Component<b>a</b> of an inactive Frame <b>b</b>, the following events
90ce3da70b43 Initial load
duke
parents:
diff changeset
   303
will be dispatched and handled in order:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   304
90ce3da70b43 Initial load
duke
parents:
diff changeset
   305
  <ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   306
    <li><b>b</b> will receive a <code>WINDOW_ACTIVATED</code> event.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   307
    <li>Next, <b>b</b> will receive a <code>WINDOW_GAINED_FOCUS</code> event.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   308
    <li>Finally, <b>a</b> will receive a <code>FOCUS_GAINED</code> event.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   309
  </ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   310
90ce3da70b43 Initial load
duke
parents:
diff changeset
   311
If the user later clicks on a focusable child Component <b>c</b> of another
90ce3da70b43 Initial load
duke
parents:
diff changeset
   312
Frame <b>d</b>, the following events will be dispatched and handled in
90ce3da70b43 Initial load
duke
parents:
diff changeset
   313
order:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   314
  <ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   315
   <li><b>a</b> will receive a <code>FOCUS_LOST</code> event.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   316
   <li><b>b</b> will receive a <code>WINDOW_LOST_FOCUS</code> event.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   317
   <li><b>b</b> will receive a <code>WINDOW_DEACTIVATED</code> event.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   318
   <li><b>d</b> will receive a <code>WINDOW_ACTIVATED</code> event.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   319
   <li><b>d</b> will receive a <code>WINDOW_GAINED_FOCUS</code> event.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   320
   <li><b>c</b> will receive a <code>FOCUS_GAINED</code> event.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   321
  </ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   322
90ce3da70b43 Initial load
duke
parents:
diff changeset
   323
Note that each event will be fully handled before the next event is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   324
dispatched. This restriction will be enforced even if the Components
90ce3da70b43 Initial load
duke
parents:
diff changeset
   325
are in different contexts and are handled on different event
90ce3da70b43 Initial load
duke
parents:
diff changeset
   326
dispatching threads.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   327
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   328
In addition, each event type will be dispatched in 1-to-1
90ce3da70b43 Initial load
duke
parents:
diff changeset
   329
correspondence with its opposite event type. For example, if a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   330
Component receives a <code>FOCUS_GAINED</code> event, under no
90ce3da70b43 Initial load
duke
parents:
diff changeset
   331
circumstances can it ever receive another <code>FOCUS_GAINED</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   332
event without an intervening <code>FOCUS_LOST</code> event.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   333
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   334
Finally, it is important to note that these events are delivered for
90ce3da70b43 Initial load
duke
parents:
diff changeset
   335
informational purposes only. It is impossible, for example, to prevent
90ce3da70b43 Initial load
duke
parents:
diff changeset
   336
the delivery of a pending <code>FOCUS_GAINED</code> event by requesting
90ce3da70b43 Initial load
duke
parents:
diff changeset
   337
focus back to the Component losing focus while handling the preceding
90ce3da70b43 Initial load
duke
parents:
diff changeset
   338
<code>FOCUS_LOST</code> event. While client code may make such a request,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   339
the pending <code>FOCUS_GAINED</code> will still be delivered,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   340
followed later by the events transferring focus back to the original
90ce3da70b43 Initial load
duke
parents:
diff changeset
   341
focus owner.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   342
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   343
If it is absolutely necessary to suppress the <code>FOCUS_GAINED</code> event,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   344
client code can install a <code>VetoableChangeListener</code> which
90ce3da70b43 Initial load
duke
parents:
diff changeset
   345
rejects the focus change. See <a href="#FocusAndVetoableChangeListener">Focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
   346
and VetoableChangeListener</a>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   347
90ce3da70b43 Initial load
duke
parents:
diff changeset
   348
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   349
<a id="OppositeComponents"></a>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   350
<h3>Opposite Components and Windows</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   351
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   352
Each event includes information about the "opposite" Component or
90ce3da70b43 Initial load
duke
parents:
diff changeset
   353
Window involved in the focus or activation change. For example, for a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   354
<code>FOCUS_GAINED</code> event, the opposite Component is the Component
90ce3da70b43 Initial load
duke
parents:
diff changeset
   355
that lost focus. If the focus or activation change occurs with a native
90ce3da70b43 Initial load
duke
parents:
diff changeset
   356
application, with a Java application in a different VM or context, or
90ce3da70b43 Initial load
duke
parents:
diff changeset
   357
with no other Component, then the opposite Component or Window is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   358
null. This information is accessible using
90ce3da70b43 Initial load
duke
parents:
diff changeset
   359
<code>FocusEvent.getOppositeComponent</code> or
90ce3da70b43 Initial load
duke
parents:
diff changeset
   360
<code>WindowEvent.getOppositeWindow</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   361
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   362
On some platforms, it is not possible to discern the opposite
90ce3da70b43 Initial load
duke
parents:
diff changeset
   363
Component or Window when the focus or activation change occurs between
90ce3da70b43 Initial load
duke
parents:
diff changeset
   364
two different heavyweight Components. In these cases, the opposite
90ce3da70b43 Initial load
duke
parents:
diff changeset
   365
Component or Window may be set to null on some platforms, and to a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   366
valid non-null value on other platforms. However, for a focus change
90ce3da70b43 Initial load
duke
parents:
diff changeset
   367
between two lightweight Components which share the same heavyweight
90ce3da70b43 Initial load
duke
parents:
diff changeset
   368
Container, the opposite Component will always be set correctly. Thus,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   369
a pure Swing application can ignore this platform restriction when
90ce3da70b43 Initial load
duke
parents:
diff changeset
   370
using the opposite Component of a focus change that occurred within a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   371
top-level Window.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   372
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   373
<a id="TemporaryFocusEvents"></a>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   374
<h3>Temporary FocusEvents</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   375
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   376
<code>FOCUS_GAINED</code> and <code>FOCUS_LOST</code> events are
90ce3da70b43 Initial load
duke
parents:
diff changeset
   377
marked as either temporary or permanent.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   378
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   379
Temporary <code>FOCUS_LOST</code> events are sent when a Component is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   380
losing the focus, but will regain the focus shortly. These events
90ce3da70b43 Initial load
duke
parents:
diff changeset
   381
can be useful when focus changes are used as triggers for validation
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   382
of data. For instance, a text Component may want to commit its
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   383
contents when the user begins interacting with another Component,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   384
and can accomplish this by responding to <code>FOCUS_LOST</code> events.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   385
However, if the <code>FocusEvent</code> received is temporary,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   386
the commit should not be done, since the text field will be receiving
90ce3da70b43 Initial load
duke
parents:
diff changeset
   387
the focus again shortly.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   388
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   389
A permanent focus transfer typically occurs as the result of a user
90ce3da70b43 Initial load
duke
parents:
diff changeset
   390
clicking on a selectable, heavyweight Component, focus traversal with
90ce3da70b43 Initial load
duke
parents:
diff changeset
   391
the keyboard or an equivalent input device, or from a call to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   392
<code>requestFocus()</code> or <code>requestFocusInWindow()</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   393
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   394
A temporary focus transfer typically occurs as the result of showing a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   395
Menu or PopupMenu, clicking or dragging a Scrollbar, moving a Window
90ce3da70b43 Initial load
duke
parents:
diff changeset
   396
by dragging the title bar, or making another Window the focused
90ce3da70b43 Initial load
duke
parents:
diff changeset
   397
Window. Note that on some platforms, these actions may not generate
90ce3da70b43 Initial load
duke
parents:
diff changeset
   398
any FocusEvents at all. On others, temporary focus transfers will
90ce3da70b43 Initial load
duke
parents:
diff changeset
   399
occur.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   400
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   401
When a Component receives a temporary <code>FOCUS_LOST</code> event,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   402
the event's opposite Component (if any) may receive a temporary
90ce3da70b43 Initial load
duke
parents:
diff changeset
   403
<code>FOCUS_GAINED</code> event, but could also receive a permanent
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   404
<code>FOCUS_GAINED</code> event. Showing a Menu or PopupMenu, or
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   405
clicking or dragging a Scrollbar, should generate a temporary
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   406
<code>FOCUS_GAINED</code> event. Changing the focused Window,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   407
however, will yield a permanent <code>FOCUS_GAINED</code> event
90ce3da70b43 Initial load
duke
parents:
diff changeset
   408
for the new focus owner.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   409
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   410
The Component class includes variants of <code>requestFocus</code> and
90ce3da70b43 Initial load
duke
parents:
diff changeset
   411
<code>requestFocusInWindow</code> which take a desired temporary state as a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   412
parameter. However, because specifying an arbitrary temporary state
90ce3da70b43 Initial load
duke
parents:
diff changeset
   413
may not be implementable on all native windowing systems, correct
90ce3da70b43 Initial load
duke
parents:
diff changeset
   414
behavior for this method can be guaranteed only for lightweight
90ce3da70b43 Initial load
duke
parents:
diff changeset
   415
Components. This method is not intended for general use, but exists
90ce3da70b43 Initial load
duke
parents:
diff changeset
   416
instead as a hook for lightweight Component libraries, such as Swing.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   417
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   418
<a id="FocusTraversal"></a>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   419
<h3>Focus Traversal</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   420
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   421
Each Component defines its own Set of focus traversal keys for a given
90ce3da70b43 Initial load
duke
parents:
diff changeset
   422
focus traversal operation. Components support separate Sets of keys
90ce3da70b43 Initial load
duke
parents:
diff changeset
   423
for forward and backward traversal, and also for traversal up one
90ce3da70b43 Initial load
duke
parents:
diff changeset
   424
focus traversal cycle. Containers which are focus cycle roots also
90ce3da70b43 Initial load
duke
parents:
diff changeset
   425
support a Set of keys for traversal down one focus traversal cycle. If
90ce3da70b43 Initial load
duke
parents:
diff changeset
   426
a Set is not explicitly defined for a Component, that Component
90ce3da70b43 Initial load
duke
parents:
diff changeset
   427
recursively inherits a Set from its parent, and ultimately from a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   428
context-wide default set on the current <code>KeyboardFocusManager</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   429
<p>
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   430
Using the <code>AWTKeyStroke</code> API, client code can specify
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   431
on which of two specific KeyEvents, <code>KEY_PRESSED</code> or
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   432
<code>KEY_RELEASED</code>, the focus traversal operation will occur.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   433
Regardless of which KeyEvent is specified, however, all KeyEvents
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   434
related to the focus traversal key, including the associated
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   435
<code>KEY_TYPED</code> event, will be consumed, and will not be
90ce3da70b43 Initial load
duke
parents:
diff changeset
   436
dispatched to any Component. It is a runtime error to specify a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   437
<code>KEY_TYPED</code> event as mapping to a focus traversal operation,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   438
or to map the same event to multiple focus traversal operations for any
90ce3da70b43 Initial load
duke
parents:
diff changeset
   439
particular Component or for a <code>KeyboardFocusManager</code>'s defaults.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   440
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   441
The default focus traversal keys are implementation-dependent. Sun
90ce3da70b43 Initial load
duke
parents:
diff changeset
   442
recommends that the all implementations for a particular native
90ce3da70b43 Initial load
duke
parents:
diff changeset
   443
platform use the same keys. For Windows and Unix, the recommendations
90ce3da70b43 Initial load
duke
parents:
diff changeset
   444
are:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   445
90ce3da70b43 Initial load
duke
parents:
diff changeset
   446
  <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   447
     <li>traverse forward to the next Component:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   448
      <br><i>TextAreas</i>: <code>CTRL-TAB</code> on <code>KEY_PRESSED</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   449
      <br><i>All others</i>: <code>TAB</code> on <code>KEY_PRESSED</code> and
90ce3da70b43 Initial load
duke
parents:
diff changeset
   450
                       <code>CTRL-TAB</code> on <code>KEY_PRESSED</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   451
     <li>traverse backward to the previous Component:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   452
      <br><i>TextAreas</i>: <code>CTRL-SHIFT-TAB</code> on
90ce3da70b43 Initial load
duke
parents:
diff changeset
   453
                       <code>KEY_PRESSED</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   454
      <br><i>All others</i>: <code>SHIFT-TAB</code> on <code>KEY_PRESSED</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   455
                       and <code>CTRL-SHIFT-TAB</code> on
90ce3da70b43 Initial load
duke
parents:
diff changeset
   456
                       <code>KEY_PRESSED</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   457
     <li>traverse up one focus traversal cycle : &lt;none&gt;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   458
     <li>traverse down one focus traversal cycle : &lt;none&gt;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   459
  </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   460
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   461
Components can enable and disable all of their focus traversal keys en
90ce3da70b43 Initial load
duke
parents:
diff changeset
   462
masse using <code>Component.setFocusTraversalKeysEnabled</code>. When focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
   463
traversal keys are disabled, the Component receives all KeyEvents for
90ce3da70b43 Initial load
duke
parents:
diff changeset
   464
those keys. When focus traversal keys are enabled, the Component never
90ce3da70b43 Initial load
duke
parents:
diff changeset
   465
receives KeyEvents for traversal keys; instead, the KeyEvents are
90ce3da70b43 Initial load
duke
parents:
diff changeset
   466
automatically mapped to focus traversal operations.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   467
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   468
For normal forward and backward traversal, the AWT focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
   469
implementation determines which Component to focus next based on the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   470
<a href=#FocusTraversalPolicy><code>FocusTraversalPolicy</code></a> of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   471
the focus owner's focus cycle root or focus traversal policy provider. If the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   472
focus owner is a focus cycle root, then it may be ambiguous as to which
90ce3da70b43 Initial load
duke
parents:
diff changeset
   473
Components represent the next and previous Components to focus during
90ce3da70b43 Initial load
duke
parents:
diff changeset
   474
normal focus traversal. Thus, the current
90ce3da70b43 Initial load
duke
parents:
diff changeset
   475
<code>KeyboardFocusManager</code> maintains a reference to the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   476
"current" focus cycle root, which is global across all contexts. The
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   477
current focus cycle root is used to resolve the ambiguity.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   478
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   479
For up-cycle traversal, the focus owner is set to the current focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
   480
owner's focus cycle root, and the current focus cycle root is set to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   481
the new focus owner's focus cycle root. If, however, the current focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
   482
owner's focus cycle root is a top-level window, then the focus owner
90ce3da70b43 Initial load
duke
parents:
diff changeset
   483
is set to the focus cycle root's default component to focus, and the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   484
current focus cycle root is unchanged.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   485
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   486
For down-cycle traversal, if the current focus owner is a focus cycle
90ce3da70b43 Initial load
duke
parents:
diff changeset
   487
root, then the focus owner is set to the current focus owner's default
90ce3da70b43 Initial load
duke
parents:
diff changeset
   488
component to focus, and the current focus cycle root is set to the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   489
current focus owner. If the current focus owner is not a focus cycle
90ce3da70b43 Initial load
duke
parents:
diff changeset
   490
root, then no focus traversal operation occurs.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   491
90ce3da70b43 Initial load
duke
parents:
diff changeset
   492
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   493
<a id="FocusTraversalPolicy"></a>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   494
<h3>FocusTraversalPolicy</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   495
<p>
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   496
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   497
A <code>FocusTraversalPolicy</code> defines the order in which Components within
90ce3da70b43 Initial load
duke
parents:
diff changeset
   498
a particular focus cycle root or focus traversal policy provider are
90ce3da70b43 Initial load
duke
parents:
diff changeset
   499
traversed. Instances of <code>FocusTraversalPolicy</code> can be shared across
90ce3da70b43 Initial load
duke
parents:
diff changeset
   500
Containers, allowing those Containers to implement the same traversal policy.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   501
FocusTraversalPolicies do not need to be reinitialized when the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   502
focus-traversal-cycle hierarchy changes.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   503
90ce3da70b43 Initial load
duke
parents:
diff changeset
   504
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   505
Each <code>FocusTraversalPolicy</code> must define the following
90ce3da70b43 Initial load
duke
parents:
diff changeset
   506
five algorithms:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   507
90ce3da70b43 Initial load
duke
parents:
diff changeset
   508
  <ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   509
    <li>Given a focus cycle root and a Component <b>a</b> in that cycle, the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   510
        next Component after <b>a</b>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   511
    <li>Given a focus cycle root and a Component <b>a</b> in that cycle, the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   512
        previous Component before <b>a</b>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   513
    <li>Given a focus cycle root, the "first" Component in that cycle.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   514
        The "first" Component is the Component to focus when traversal
90ce3da70b43 Initial load
duke
parents:
diff changeset
   515
        wraps in the forward direction.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   516
    <li>Given a focus cycle root, the "last" Component in that cycle.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   517
        The "last" Component is the Component to focus when traversal
90ce3da70b43 Initial load
duke
parents:
diff changeset
   518
        wraps in the reverse direction.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   519
    <li>Given a focus cycle root, the "default" Component in that cycle.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   520
        The "default" Component will be the first to receive focus when
90ce3da70b43 Initial load
duke
parents:
diff changeset
   521
        traversing down into a new focus traversal cycle. This may be the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   522
        same as the "first" Component, but need not be.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   523
  </ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   524
90ce3da70b43 Initial load
duke
parents:
diff changeset
   525
<p>
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   526
A <code>FocusTraversalPolicy</code> may optionally provide an
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   527
algorithm for the following:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   528
  <blockquote>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   529
  Given a Window, the "initial" Component in that Window. The initial
90ce3da70b43 Initial load
duke
parents:
diff changeset
   530
  Component will be the first to receive focus when the Window is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   531
  first made visible. By default, this is the same as the "default"
90ce3da70b43 Initial load
duke
parents:
diff changeset
   532
  Component.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   533
  </blockquote>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   534
90ce3da70b43 Initial load
duke
parents:
diff changeset
   535
In addition, Swing provides a subclass of <code>FocusTraversalPolicy</code>,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   536
<code>InternalFrameFocusTraversalPolicy</code>, which allows developers
90ce3da70b43 Initial load
duke
parents:
diff changeset
   537
to provide an algorithm for the following:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   538
90ce3da70b43 Initial load
duke
parents:
diff changeset
   539
  <blockquote>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   540
  Given a <code>JInternalFrame</code>, the "initial" Component in that
90ce3da70b43 Initial load
duke
parents:
diff changeset
   541
  <code>JInternalFrame</code>. The initial Component is the first to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   542
  receive focus when the <code>JInternalFrame</code> is first selected.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   543
  By default, this is the same as the <code>JInternalFrame</code>'s
90ce3da70b43 Initial load
duke
parents:
diff changeset
   544
  default Component to focus.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   545
  </blockquote>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   546
90ce3da70b43 Initial load
duke
parents:
diff changeset
   547
A <code>FocusTraversalPolicy</code> is installed on a Container using
90ce3da70b43 Initial load
duke
parents:
diff changeset
   548
Container.<code>setFocusTraversalPolicy</code>. If a policy is not explicitly
90ce3da70b43 Initial load
duke
parents:
diff changeset
   549
set, then a Container inherits its policy from its nearest focus-cycle-root
90ce3da70b43 Initial load
duke
parents:
diff changeset
   550
ancestor. Top-levels initialize their focus traversal policies using the context
90ce3da70b43 Initial load
duke
parents:
diff changeset
   551
default policy. The context default policy is established by using
90ce3da70b43 Initial load
duke
parents:
diff changeset
   552
KeyboardFocusManager.  <code>setDefaultFocusTraversalPolicy</code>.
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   553
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   554
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   555
AWT provides two standard <code>FocusTraversalPolicy</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   556
implementations for use by client code.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   557
90ce3da70b43 Initial load
duke
parents:
diff changeset
   558
  <ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   559
    <li><code>ContainerOrderFocusTraversalPolicy</code>: Iterates across the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   560
        Components in a focus traversal cycle in the order they were added
90ce3da70b43 Initial load
duke
parents:
diff changeset
   561
        to their Containers. Each Component is tested for fitness using the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   562
        accept(Component) method. By default, a Component is fit only if it
90ce3da70b43 Initial load
duke
parents:
diff changeset
   563
        is visible, displayable, enabled, and focusable.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   564
    <li>By default, ContainerOrderFocusTraversalPolicy implicitly transfers
90ce3da70b43 Initial load
duke
parents:
diff changeset
   565
        focus down-cycle. That is, during normal forward focus traversal,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   566
        the Component traversed after a focus cycle root will be the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   567
        focus-cycle-root's default Component to focus, regardless of whether
90ce3da70b43 Initial load
duke
parents:
diff changeset
   568
        the focus cycle root is a traversable or non-traversable Container
90ce3da70b43 Initial load
duke
parents:
diff changeset
   569
        (see the pic.1,2 below). Such behavior provides backward compatibility
90ce3da70b43 Initial load
duke
parents:
diff changeset
   570
        with applications designed without the concepts of up- and down-cycle
90ce3da70b43 Initial load
duke
parents:
diff changeset
   571
        traversal.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   572
    <li><code>DefaultFocusTraversalPolicy</code>: A subclass of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   573
        <code>ContainerOrderFocusTraversalPolicy</code> which redefines
90ce3da70b43 Initial load
duke
parents:
diff changeset
   574
        the fitness test.  If client code has explicitly set the
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   575
        focusability of a Component by either overriding
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   576
        <code>Component.isFocusTraversable()</code> or
90ce3da70b43 Initial load
duke
parents:
diff changeset
   577
        <code>Component.isFocusable()</code>, or by calling
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   578
        <code>Component.setFocusable(boolean)</code>, then a
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   579
        <code>DefaultFocusTraversalPolicy</code> behaves exactly
90ce3da70b43 Initial load
duke
parents:
diff changeset
   580
        like a <code>ContainerOrderFocusTraversalPolicy</code>. If,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   581
        however, the Component is relying on default focusability, then a
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   582
        <code>DefaultFocusTraversalPolicy</code> will reject all
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   583
        Components with non-focusable peers.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   584
        <br>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   585
        The focusability of a peer is implementation-dependent. Sun
90ce3da70b43 Initial load
duke
parents:
diff changeset
   586
        recommends that all implementations for a particular native platform
90ce3da70b43 Initial load
duke
parents:
diff changeset
   587
        construct peers with the same focusability. The recommendations for
90ce3da70b43 Initial load
duke
parents:
diff changeset
   588
        Windows and Unix are that Canvases, Labels, Panels, Scrollbars,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   589
        ScrollPanes, Windows, and lightweight Components have non-focusable
90ce3da70b43 Initial load
duke
parents:
diff changeset
   590
        peers, and all other Components have focusable peers. These
90ce3da70b43 Initial load
duke
parents:
diff changeset
   591
        recommendations are used in the Sun AWT implementations. Note that
90ce3da70b43 Initial load
duke
parents:
diff changeset
   592
        the focusability of a Component's peer is different from, and does
90ce3da70b43 Initial load
duke
parents:
diff changeset
   593
        not impact, the focusability of the Component itself.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   594
  </ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   595
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   596
Swing provides two additional, standard FocusTraversalPolicy
90ce3da70b43 Initial load
duke
parents:
diff changeset
   597
implementations for use by client code. Each implementation is an
90ce3da70b43 Initial load
duke
parents:
diff changeset
   598
InternalFrameFocusTraversalPolicy.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   599
90ce3da70b43 Initial load
duke
parents:
diff changeset
   600
  <ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   601
    <li>SortingFocusTraversalPolicy: Determines traversal order by
90ce3da70b43 Initial load
duke
parents:
diff changeset
   602
        sorting the Components of a focus traversal cycle based on a given
90ce3da70b43 Initial load
duke
parents:
diff changeset
   603
        Comparator. Each Component is tested for fitness using the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   604
        accept(Component) method. By default, a Component is fit only if it
90ce3da70b43 Initial load
duke
parents:
diff changeset
   605
        is visible, displayable, enabled, and focusable.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   606
    <li>By default, SortingFocusTraversalPolicy implicitly transfers focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
   607
        down-cycle. That is, during normal forward focus traversal, the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   608
        Component traversed after a focus cycle root will be the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   609
        focus-cycle-root's default Component to focus, regardless of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   610
        whether the focus cycle root is a traversable or non-traversable
90ce3da70b43 Initial load
duke
parents:
diff changeset
   611
        Container (see the pic.1,2 below). Such behavior provides backward
90ce3da70b43 Initial load
duke
parents:
diff changeset
   612
        compatibility with applications designed without the concepts of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   613
        up- and down-cycle traversal.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   614
    <li>LayoutFocusTraversalPolicy: A subclass of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   615
        SortingFocusTraversalPolicy which sorts Components based on their
90ce3da70b43 Initial load
duke
parents:
diff changeset
   616
        size, position, and orientation. Based on their size and position,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   617
        Components are roughly categorized into rows and columns. For a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   618
        Container with horizontal orientation, columns run left-to-right or
90ce3da70b43 Initial load
duke
parents:
diff changeset
   619
        right-to-left, and rows run top-to-bottom. For a Container with
90ce3da70b43 Initial load
duke
parents:
diff changeset
   620
        vertical orientation, columns run top-to-bottom and rows run
90ce3da70b43 Initial load
duke
parents:
diff changeset
   621
        left-to-right or right-to-left. All columns in a row are fully
90ce3da70b43 Initial load
duke
parents:
diff changeset
   622
        traversed before proceeding to the next row.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   623
        <br>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   624
        In addition, the fitness test is extended to exclude JComponents
90ce3da70b43 Initial load
duke
parents:
diff changeset
   625
        that have or inherit empty InputMaps.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   626
  </ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   627
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   628
The figure below shows an implicit focus transfer:
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   629
<br><img src="ImplicitFocusTransfer.gif" alt="Implicit focus transfer."><br>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   630
90ce3da70b43 Initial load
duke
parents:
diff changeset
   631
Assume the following:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   632
 <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   633
   <li><b>A</b>, <b>B</b> and <b>C</b> are components in some window (a container)
90ce3da70b43 Initial load
duke
parents:
diff changeset
   634
   <li><b>R</b> is a container in the window and it is a parent of <b>B</b> and <b>C</b>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   635
       Besides, <b>R</b> is a focus cycle root.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   636
   <li><b>B</b> is the default component in the focul traversal cycle of <b>R</b>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   637
   <li><b>R</b> is a traversable Container in the pic.1, and it is a non-traversable
90ce3da70b43 Initial load
duke
parents:
diff changeset
   638
       Container in the pic.2.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   639
   <li>In such a case a forward traversal will look as follows:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   640
   <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   641
     <li> pic.1 : <b>A</b> -> <b>R</b> -> <b>B</b> -> <b>C</b>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   642
     <li> pic.2 : <b>A</b> -> <b>B</b> -> <b>C</b>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   643
   </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   644
 </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   645
90ce3da70b43 Initial load
duke
parents:
diff changeset
   646
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   647
Swing applications, or mixed Swing/AWT applications, that use one of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   648
the standard look and feels, or any other look and feel derived from
90ce3da70b43 Initial load
duke
parents:
diff changeset
   649
BasicLookAndFeel, will use LayoutFocusTraversalPolicy for all
90ce3da70b43 Initial load
duke
parents:
diff changeset
   650
Containers by default.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   651
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   652
All other applications, including pure AWT applications, will use
90ce3da70b43 Initial load
duke
parents:
diff changeset
   653
<code>DefaultFocusTraversalPolicy</code> by default.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   654
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   655
<a id="FocusTraversalPolicyProviders"></a>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   656
<h3>Focus Traversal Policy Providers</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   657
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   658
  A Container that isn't a focus cycle root has an option to provide a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   659
  FocusTraversalPolicy of its own. To do so, one needs to set Container's focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
   660
  traversal policy provider property to <code>true</code> with the call to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   661
21254
f6d36ee3f269 8025824: [cleanup] Fix tidy errors and warnings in preformatted HTML files related to 2d/awt/swing
yan
parents: 9035
diff changeset
   662
  <blockquote>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   663
    <code>Container.setFocusTraversalPolicyProvider(boolean)</code>
21254
f6d36ee3f269 8025824: [cleanup] Fix tidy errors and warnings in preformatted HTML files related to 2d/awt/swing
yan
parents: 9035
diff changeset
   664
  </blockquote>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   665
90ce3da70b43 Initial load
duke
parents:
diff changeset
   666
  To determine whether a Container is a focus traversal policy provider, the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   667
  following method should be used:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   668
21254
f6d36ee3f269 8025824: [cleanup] Fix tidy errors and warnings in preformatted HTML files related to 2d/awt/swing
yan
parents: 9035
diff changeset
   669
  <blockquote>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   670
    <code>Container.isFocusTraversalPolicyProvider()</code>
21254
f6d36ee3f269 8025824: [cleanup] Fix tidy errors and warnings in preformatted HTML files related to 2d/awt/swing
yan
parents: 9035
diff changeset
   671
  </blockquote>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   672
90ce3da70b43 Initial load
duke
parents:
diff changeset
   673
  If focus traversal policy provider property is set on a focus cycle root, it
90ce3da70b43 Initial load
duke
parents:
diff changeset
   674
  isn't considered a focus traversal policy provider and behaves just like any
90ce3da70b43 Initial load
duke
parents:
diff changeset
   675
  other focus cycle root.
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   676
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   677
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   678
  The main difference between focus cycle roots and focus traversal policy
90ce3da70b43 Initial load
duke
parents:
diff changeset
   679
  providers is that the latter allow focus to enter and leave them just as all other
90ce3da70b43 Initial load
duke
parents:
diff changeset
   680
  Containers. However, children inside focus traversal policy provider are
90ce3da70b43 Initial load
duke
parents:
diff changeset
   681
  traversed in the order determined by provider's FocusTraversalPolicy. In order
90ce3da70b43 Initial load
duke
parents:
diff changeset
   682
  to enable focus traversal policy providers to behave this way,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   683
  FocusTraversalPolicies treat them in the following manner:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   684
90ce3da70b43 Initial load
duke
parents:
diff changeset
   685
  <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   686
    <li> Focus traversal policy providers can be passed to FocusTraversalPolicy
90ce3da70b43 Initial load
duke
parents:
diff changeset
   687
        methods instead of focus cycle roots.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   688
    <li> When calculating next or previous Component in
90ce3da70b43 Initial load
duke
parents:
diff changeset
   689
        <code>FocusTraversalPolicy.getComponentAfter</code> or
90ce3da70b43 Initial load
duke
parents:
diff changeset
   690
        <code>FocusTraversalPolicy.getComponentBefore</code>,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   691
        <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   692
          <li>if a Component is a child of a focus traversal policy provider,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   693
              the next and previous for this Component are determined using this
90ce3da70b43 Initial load
duke
parents:
diff changeset
   694
              focus traversal policy provider's FocusTraversalPolicy. However,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   695
              in order for focus to leave the provider, the following rules are
90ce3da70b43 Initial load
duke
parents:
diff changeset
   696
              applied:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   697
              <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   698
                <li> if at some point the <code>next</code> found Component is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   699
                    the <code>first</code> Component of focus traversal policy
90ce3da70b43 Initial load
duke
parents:
diff changeset
   700
                    provider, the Component after the focus traversal policy
90ce3da70b43 Initial load
duke
parents:
diff changeset
   701
                    provider is returned
90ce3da70b43 Initial load
duke
parents:
diff changeset
   702
                <li> if at some point the <code>previous</code> found Component is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   703
                    the <code>last</code> Component of focus traversal policy
90ce3da70b43 Initial load
duke
parents:
diff changeset
   704
                    provider, the Component before the focus traversal policy
90ce3da70b43 Initial load
duke
parents:
diff changeset
   705
                    provider is returned
90ce3da70b43 Initial load
duke
parents:
diff changeset
   706
              </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   707
          <li> When calculating the next Component in
90ce3da70b43 Initial load
duke
parents:
diff changeset
   708
              <code>FocusTraversalPolicy.getComponentAfter</code>,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   709
              <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   710
                <li> if an obtained Component is a non-traversable Container and
90ce3da70b43 Initial load
duke
parents:
diff changeset
   711
                     it is a focus traversal policy provider, then the default Component
90ce3da70b43 Initial load
duke
parents:
diff changeset
   712
                     of that provider is returned
90ce3da70b43 Initial load
duke
parents:
diff changeset
   713
                <li> if the Component passed to the <code>FocusTraversalPolicy.getComponentAfter</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   714
                     method is a traversable Container and it is a focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
   715
                     traversal policy provider, then the default Component of this provider
90ce3da70b43 Initial load
duke
parents:
diff changeset
   716
                     is returned
90ce3da70b43 Initial load
duke
parents:
diff changeset
   717
              </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   718
          <li> When calculating the previous Component in
90ce3da70b43 Initial load
duke
parents:
diff changeset
   719
              <code>FocusTraversalPolicy.getComponentBefore</code>,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   720
              <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   721
                <li> if an obtained Component is a Container (traversable or
90ce3da70b43 Initial load
duke
parents:
diff changeset
   722
                     non-traversable) and it is a focus traversal policy provider, then
90ce3da70b43 Initial load
duke
parents:
diff changeset
   723
                     the last Component of that provider is returned
90ce3da70b43 Initial load
duke
parents:
diff changeset
   724
              </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   725
        </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   726
    <li> When calculating the first Component in FocusTraversalPolicy.getFirstComponent,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   727
        <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   728
          <li> if an obtained Component is a non-traversable Container and it is a focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
   729
               traversal policy provider, then the default Component of that provider is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   730
               returned
90ce3da70b43 Initial load
duke
parents:
diff changeset
   731
          <li> if an obtained Component is a traversable Container and it is a focus traversal
90ce3da70b43 Initial load
duke
parents:
diff changeset
   732
               policy provider, then that Container itself is returned
90ce3da70b43 Initial load
duke
parents:
diff changeset
   733
        </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   734
    <li> When calculating the last Component in FocusTraversalPolicy.getLastComponent,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   735
        <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   736
          <li> if an obtained Component is a Container (traversable or non-traversable)
90ce3da70b43 Initial load
duke
parents:
diff changeset
   737
               and it is a focus traversal policy provider, then the last Component of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   738
               that provider is returned
90ce3da70b43 Initial load
duke
parents:
diff changeset
   739
        </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   740
  </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   741
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   742
<a id="ProgrammaticTraversal"></a>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   743
<h3>Programmatic Traversal</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   744
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   745
In addition to user-initiated focus traversal, client code can
90ce3da70b43 Initial load
duke
parents:
diff changeset
   746
initiate a focus traversal operation programmatically. To client code,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   747
programmatic traversals are indistinguishable from user-initiated
90ce3da70b43 Initial load
duke
parents:
diff changeset
   748
traversals. The preferred way to initiate a programmatic traversal is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   749
to use one of the following methods on <code>KeyboardFocusManager</code>:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   750
90ce3da70b43 Initial load
duke
parents:
diff changeset
   751
  <ul>
21254
f6d36ee3f269 8025824: [cleanup] Fix tidy errors and warnings in preformatted HTML files related to 2d/awt/swing
yan
parents: 9035
diff changeset
   752
    <li><code>KeyboardFocusManager.focusNextComponent()</code>
f6d36ee3f269 8025824: [cleanup] Fix tidy errors and warnings in preformatted HTML files related to 2d/awt/swing
yan
parents: 9035
diff changeset
   753
    <li><code>KeyboardFocusManager.focusPreviousComponent()</code>
f6d36ee3f269 8025824: [cleanup] Fix tidy errors and warnings in preformatted HTML files related to 2d/awt/swing
yan
parents: 9035
diff changeset
   754
    <li><code>KeyboardFocusManager.upFocusCycle()</code>
f6d36ee3f269 8025824: [cleanup] Fix tidy errors and warnings in preformatted HTML files related to 2d/awt/swing
yan
parents: 9035
diff changeset
   755
    <li><code>KeyboardFocusManager.downFocusCycle()</code>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   756
  </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   757
90ce3da70b43 Initial load
duke
parents:
diff changeset
   758
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   759
Each of these methods initiates the traversal operation with the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   760
current focus owner. If there is currently no focus owner, then no
90ce3da70b43 Initial load
duke
parents:
diff changeset
   761
traversal operation occurs. In addition, if the focus owner is not a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   762
focus cycle root, then downFocusCycle() performs no traversal
90ce3da70b43 Initial load
duke
parents:
diff changeset
   763
operation.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   764
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   765
<code>KeyboardFocusManager</code> also supports the following variants
90ce3da70b43 Initial load
duke
parents:
diff changeset
   766
of these methods:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   767
90ce3da70b43 Initial load
duke
parents:
diff changeset
   768
  <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   769
    <li><code>KeyboardFocusManager.focusNextComponent(Component)</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   770
    <li><code>KeyboardFocusManager.focusPreviousComponent(Component)</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   771
    <li><code>KeyboardFocusManager.upFocusCycle(Component)</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   772
    <li><code>KeyboardFocusManager.downFocusCycle(Container)</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   773
  </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   774
90ce3da70b43 Initial load
duke
parents:
diff changeset
   775
Each of these methods initiates the traversal operation with the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   776
specified Component rather than the focus owner. That is, the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   777
traversal occurs as though the specified Component is the focus owner,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   778
though it need not be.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   779
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   780
Alternate, but equivalent, APIs are defined on the Component and
90ce3da70b43 Initial load
duke
parents:
diff changeset
   781
Container classes themselves:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   782
90ce3da70b43 Initial load
duke
parents:
diff changeset
   783
  <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   784
    <li><code>Component.transferFocus()</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   785
    <li><code>Component.transferFocusBackward()</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   786
    <li><code>Component.transferFocusUpCycle()</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   787
    <li><code>Container.transferFocusDownCycle()</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   788
  </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   789
90ce3da70b43 Initial load
duke
parents:
diff changeset
   790
As with the <code>KeyboardFocusManager</code> variants, each of these methods
90ce3da70b43 Initial load
duke
parents:
diff changeset
   791
initiates the traversal operation as though the Component is the focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
   792
owner, though it need not be.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   793
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   794
Also note that hiding or disabling the focus owner, directly or
90ce3da70b43 Initial load
duke
parents:
diff changeset
   795
indirectly via an ancestor, or making the focus owner non-displayable
90ce3da70b43 Initial load
duke
parents:
diff changeset
   796
or non-focusable, initiates an automatic, forward focus traversal.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   797
While hiding any ancestor, lightweight or heavyweight, will always
90ce3da70b43 Initial load
duke
parents:
diff changeset
   798
indirectly hide its children, only disabling a heavyweight ancestor
90ce3da70b43 Initial load
duke
parents:
diff changeset
   799
will disable its children. Thus, disabling a lightweight ancestor of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   800
the focus owner does not automatically initiate a focus traversal.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   801
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   802
If client code initiates a focus traversal, and there is no other
90ce3da70b43 Initial load
duke
parents:
diff changeset
   803
Component to focus, then the focus owner remains unchanged. If client
90ce3da70b43 Initial load
duke
parents:
diff changeset
   804
code initiates an automatic focus traversal by hiding the focus owner,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   805
directly or indirectly, or by making the focus owner non-displayable or
90ce3da70b43 Initial load
duke
parents:
diff changeset
   806
non-focusable, and there is no other Component to focus, then the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   807
global focus owner is cleared. If client code initiates an automatic
90ce3da70b43 Initial load
duke
parents:
diff changeset
   808
focus traversal by disabling the focus owner, directly or indirectly,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   809
and there is no other Component to focus, then the focus owner remains
90ce3da70b43 Initial load
duke
parents:
diff changeset
   810
unchanged.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   811
90ce3da70b43 Initial load
duke
parents:
diff changeset
   812
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   813
<a id="Focusability"></a>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   814
<h3>Focusability</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   815
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   816
A focusable Component can become the focus owner ("focusability") and
90ce3da70b43 Initial load
duke
parents:
diff changeset
   817
participates in keyboard focus traversal ("focus traversability") with
90ce3da70b43 Initial load
duke
parents:
diff changeset
   818
a FocusTraversalPolicy. There is no separation of these two concepts;
90ce3da70b43 Initial load
duke
parents:
diff changeset
   819
a Component must either be both focusable and focus traversable, or
90ce3da70b43 Initial load
duke
parents:
diff changeset
   820
neither.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   821
90ce3da70b43 Initial load
duke
parents:
diff changeset
   822
A Component expresses this state via the isFocusable() method. By
90ce3da70b43 Initial load
duke
parents:
diff changeset
   823
default, all Components return true from this method. Client code can
90ce3da70b43 Initial load
duke
parents:
diff changeset
   824
change this default by calling Component.setFocusable(boolean).
90ce3da70b43 Initial load
duke
parents:
diff changeset
   825
90ce3da70b43 Initial load
duke
parents:
diff changeset
   826
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   827
<a id="FocusableWindows"></a>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   828
<h3>Focusable Windows</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   829
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   830
To support palette windows and input methods, client code can prevent
90ce3da70b43 Initial load
duke
parents:
diff changeset
   831
a Window from becoming the focused Window. By transitivity, this
90ce3da70b43 Initial load
duke
parents:
diff changeset
   832
prevents the Window or any of its descendants from becoming the focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
   833
owner. Non-focusable Windows may still own Windows that are
90ce3da70b43 Initial load
duke
parents:
diff changeset
   834
focusable. By default, every Frame and Dialog is focusable. Every
90ce3da70b43 Initial load
duke
parents:
diff changeset
   835
Window which is not a Frame or Dialog, but whose nearest owning Frame
90ce3da70b43 Initial load
duke
parents:
diff changeset
   836
or Dialog is showing on the screen, and which has at least one
90ce3da70b43 Initial load
duke
parents:
diff changeset
   837
Component in its focus traversal cycle, is also focusable by
90ce3da70b43 Initial load
duke
parents:
diff changeset
   838
default. To make a Window non-focusable, use
90ce3da70b43 Initial load
duke
parents:
diff changeset
   839
Window.setFocusableWindowState(false).
90ce3da70b43 Initial load
duke
parents:
diff changeset
   840
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   841
If a Window is non-focusable, this restriction is enforced when the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   842
<code>KeyboardFocusManager</code> sees a <code>WINDOW_GAINED_FOCUS</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   843
event for the Window.  At this point, the focus change is rejected and
90ce3da70b43 Initial load
duke
parents:
diff changeset
   844
focus is reset to a different Window. The rejection recovery scheme
90ce3da70b43 Initial load
duke
parents:
diff changeset
   845
is the same as if a <code>VetoableChangeListener</code> rejected the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   846
focus change.  See <a href="#FocusAndVetoableChangeListener">Focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
   847
and VetoableChangeListener</a>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   848
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   849
Because the new focus implementation requires that KeyEvents intended
90ce3da70b43 Initial load
duke
parents:
diff changeset
   850
for a Window or its descendants be proxied through a child of the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   851
Window's owner, and because this proxy must be mapped on X11 in order
90ce3da70b43 Initial load
duke
parents:
diff changeset
   852
to receive events, a Window whose nearest owning Frame or Dialog is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   853
not showing could never receive KeyEvents on X11. To support this
90ce3da70b43 Initial load
duke
parents:
diff changeset
   854
restriction, we have made a distinction between a Window's "window
90ce3da70b43 Initial load
duke
parents:
diff changeset
   855
focusability" and its "window focusability state". A Window's
90ce3da70b43 Initial load
duke
parents:
diff changeset
   856
focusability state is combined with the showing state of the Window's
90ce3da70b43 Initial load
duke
parents:
diff changeset
   857
nearest owning Frame or Dialog to determine the Window's focusability.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   858
By default, all Windows have a focusability state of true. Setting a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   859
Window's focusability state to false ensures that it will not become
90ce3da70b43 Initial load
duke
parents:
diff changeset
   860
the focused Window regardless of the showing state of its nearest
90ce3da70b43 Initial load
duke
parents:
diff changeset
   861
owning Frame or Dialog.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   862
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   863
Swing allows applications to create JWindows with null owners. Swing
90ce3da70b43 Initial load
duke
parents:
diff changeset
   864
constructs all such JWindows so that they are owned by a private,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   865
hidden Frame. Because the showing state of this Frame will always be
90ce3da70b43 Initial load
duke
parents:
diff changeset
   866
false, a JWindow constructed will a null owner can never be the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   867
focused Window, even if it has a Window focusability state of true.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   868
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   869
If the focused Window is made non-focusable, then the AWT will attempt
90ce3da70b43 Initial load
duke
parents:
diff changeset
   870
to focus the most recently focused Component of the Window's
90ce3da70b43 Initial load
duke
parents:
diff changeset
   871
owner. The Window's owner will thus become the new focused Window. If
90ce3da70b43 Initial load
duke
parents:
diff changeset
   872
the Window's owner is also a non-focusable Window, then the focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
   873
change request will proceed up the ownership hierarchy recursively.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   874
Since not all platforms support cross-Window focus changes (see
90ce3da70b43 Initial load
duke
parents:
diff changeset
   875
<a href=#RequestingFocus>Requesting Focus</a>), it is possible that
90ce3da70b43 Initial load
duke
parents:
diff changeset
   876
all such focus change requests will fail. In this case, the global
90ce3da70b43 Initial load
duke
parents:
diff changeset
   877
focus owner will be cleared and the focused Window will remain unchanged.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   878
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   879
<a id="RequestingFocus"></a>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   880
<h3>Requesting Focus</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   881
90ce3da70b43 Initial load
duke
parents:
diff changeset
   882
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   883
A Component can request that it become the focus owner by calling
90ce3da70b43 Initial load
duke
parents:
diff changeset
   884
<code>Component.requestFocus()</code>. This initiates a permanent
90ce3da70b43 Initial load
duke
parents:
diff changeset
   885
focus transfer to the Component only if the Component is displayable,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   886
focusable, visible and all of its ancestors (with the exception of the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   887
top-level Window) are visible. The request will be immediately denied if
90ce3da70b43 Initial load
duke
parents:
diff changeset
   888
any of these conditions is not met. A disabled Component may be
90ce3da70b43 Initial load
duke
parents:
diff changeset
   889
the focus owner; however, in this case, all KeyEvents will be discarded.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   890
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   891
The request will also be denied if the Component's top-level Window is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   892
not the focused Window and the platform does not support requesting
90ce3da70b43 Initial load
duke
parents:
diff changeset
   893
focus across Windows. If the request is denied for this reason, the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   894
request is remembered and will be granted when the Window is later
90ce3da70b43 Initial load
duke
parents:
diff changeset
   895
focused by the user. Otherwise, the focus change request changes the
8132
8686fda1829a 6693961: cross-window focus transfer ability in the Focus Spec should be revised
dav
parents: 5506
diff changeset
   896
focused Window as well.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   897
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   898
There is no way to determine synchronously whether a focus change
90ce3da70b43 Initial load
duke
parents:
diff changeset
   899
request has been granted. Instead, client code must install a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   900
FocusListener on the Component and watch for the delivery of a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   901
<code>FOCUS_GAINED</code> event. Client code must not assume that
90ce3da70b43 Initial load
duke
parents:
diff changeset
   902
the Component is the focus owner until it receives this event.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   903
The event may or may not be delivered before <code>requestFocus()</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   904
returns. Developers must not assume one behavior or the other.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   905
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   906
The AWT supports type-ahead if all focus change requests are made on
90ce3da70b43 Initial load
duke
parents:
diff changeset
   907
the EventDispatchThread. If client code requests a focus change, and
90ce3da70b43 Initial load
duke
parents:
diff changeset
   908
the AWT determines that this request might be granted by the native
90ce3da70b43 Initial load
duke
parents:
diff changeset
   909
windowing system, then the AWT will notify the current
90ce3da70b43 Initial load
duke
parents:
diff changeset
   910
KeyboardFocusManager that is should enqueue all KeyEvents with a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   911
timestamp later than the that of the event currently being handled.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   912
These KeyEvents will not be dispatched until the new Component becomes
90ce3da70b43 Initial load
duke
parents:
diff changeset
   913
the focus owner. The AWT will cancel the delayed dispatching request
90ce3da70b43 Initial load
duke
parents:
diff changeset
   914
if the focus change does not succeed at the native level, if the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   915
Component's peer is disposed, or if the focus change is vetoed by a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   916
VetoableChangeListener. KeyboardFocusManagers are not required to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   917
support type-ahead if a focus change request is made from a thread
90ce3da70b43 Initial load
duke
parents:
diff changeset
   918
other than the EventDispatchThread.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   919
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   920
Because <code>Component.requestFocus()</code> cannot be implemented
90ce3da70b43 Initial load
duke
parents:
diff changeset
   921
consistently across platforms, developers are encouraged to use
90ce3da70b43 Initial load
duke
parents:
diff changeset
   922
<code>Component.requestFocusInWindow()</code> instead. This method
90ce3da70b43 Initial load
duke
parents:
diff changeset
   923
denies cross-Window focus transfers on all platforms automatically.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   924
By eliminating the only platform-specific element of the focus transfer,
90ce3da70b43 Initial load
duke
parents:
diff changeset
   925
this method achieves consistent cross-platform behavior.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   926
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   927
In addition, <code>requestFocusInWindow()</code> returns a boolean value.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   928
If 'false' is returned, the request is guaranteed to fail. If 'true' is
90ce3da70b43 Initial load
duke
parents:
diff changeset
   929
returned, the request will succeed unless it is vetoed, or an
90ce3da70b43 Initial load
duke
parents:
diff changeset
   930
extraordinary event, such as disposal of the Component's peer, occurs
90ce3da70b43 Initial load
duke
parents:
diff changeset
   931
before the request can be granted by the native windowing
90ce3da70b43 Initial load
duke
parents:
diff changeset
   932
system. Again, while a return value of 'true' indicates that the
90ce3da70b43 Initial load
duke
parents:
diff changeset
   933
request is likely to succeed, developers must never assume that this
90ce3da70b43 Initial load
duke
parents:
diff changeset
   934
Component is the focus owner until this Component receives a
90ce3da70b43 Initial load
duke
parents:
diff changeset
   935
<code>FOCUS_GAINED</code> event.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   936
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   937
If client code wants no Component in the application to be the focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
   938
owner, it can call the method <code>KeyboardFocusManager</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   939
<code>clearGlobalFocusOwner()</code> on the current
90ce3da70b43 Initial load
duke
parents:
diff changeset
   940
<code>KeyboardFocusManager</code>. If there exists a focus owner
90ce3da70b43 Initial load
duke
parents:
diff changeset
   941
when this method is called, the focus owner will receive a permanent
90ce3da70b43 Initial load
duke
parents:
diff changeset
   942
<code>FOCUS_LOST</code> event. After this point, the AWT
90ce3da70b43 Initial load
duke
parents:
diff changeset
   943
focus implementation will discard all KeyEvents until the user or
90ce3da70b43 Initial load
duke
parents:
diff changeset
   944
client code explicitly sets focus to a Component.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   945
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   946
The Component class also supports variants of <code>requestFocus</code> and
90ce3da70b43 Initial load
duke
parents:
diff changeset
   947
<code>requestFocusInWindow</code> that allow client code to specify
90ce3da70b43 Initial load
duke
parents:
diff changeset
   948
a temporary state.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   949
See <a href="#TemporaryFocusEvents">Temporary FocusEvents</a>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   950
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   951
<a id="FocusAndPropertyChangeListener"></a>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   952
<h3>Focus and PropertyChangeListener</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   953
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   954
Client code can listen to changes in context-wide focus state, or to
90ce3da70b43 Initial load
duke
parents:
diff changeset
   955
changes in focus-related state in Components, via
90ce3da70b43 Initial load
duke
parents:
diff changeset
   956
PropertyChangeListeners.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   957
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   958
The <code>KeyboardFocusManager</code> supports the following properties:
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   959
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   960
  <ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   961
    <li><code>focusOwner</code>: the focus owner
90ce3da70b43 Initial load
duke
parents:
diff changeset
   962
    <li><code>focusedWindow</code>: the focused Window
90ce3da70b43 Initial load
duke
parents:
diff changeset
   963
    <li><code>activeWindow</code>: the active Window
90ce3da70b43 Initial load
duke
parents:
diff changeset
   964
    <li><code>defaultFocusTraversalPolicy</code>: the default focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
   965
        traversal policy
90ce3da70b43 Initial load
duke
parents:
diff changeset
   966
    <li><code>forwardDefaultFocusTraversalKeys</code>: the Set of default
90ce3da70b43 Initial load
duke
parents:
diff changeset
   967
        <code>FORWARD_TRAVERSAL_KEYS</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   968
    <li><code>backwardDefaultFocusTraversalKeys</code>: the Set of default
90ce3da70b43 Initial load
duke
parents:
diff changeset
   969
        <code>BACKWARD_TRAVERSAL_KEYS</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   970
    <li><code>upCycleDefaultFocusTraversalKeys</code>: the Set of default
90ce3da70b43 Initial load
duke
parents:
diff changeset
   971
        <code>UP_CYCLE_TRAVERSAL_KEYS</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   972
    <li><code>downCycleDefaultFocusTraversalKeys</code>: the Set of default
90ce3da70b43 Initial load
duke
parents:
diff changeset
   973
        <code>DOWN_CYCLE_TRAVERSAL_KEYS</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   974
    <li><code>currentFocusCycleRoot</code>: the current focus cycle root
90ce3da70b43 Initial load
duke
parents:
diff changeset
   975
  </ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   976
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   977
A <code>PropertyChangeListener</code> installed on the current
90ce3da70b43 Initial load
duke
parents:
diff changeset
   978
<code>KeyboardFocusManager</code> will only see these changes within
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
   979
the <code>KeyboardFocusManager</code>'s context, even though the
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
   980
focus owner, focused Window, active Window, and current focus cycle
90ce3da70b43 Initial load
duke
parents:
diff changeset
   981
root comprise the global focus state shared by all contexts.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   982
We believe this is less intrusive than requiring client code to pass
90ce3da70b43 Initial load
duke
parents:
diff changeset
   983
a security check before installing a <code>PropertyChangeListener</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
   984
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   985
Component supports the following focus-related properties:
90ce3da70b43 Initial load
duke
parents:
diff changeset
   986
90ce3da70b43 Initial load
duke
parents:
diff changeset
   987
  <ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   988
   <li><code>focusable</code>: the Component's focusability
90ce3da70b43 Initial load
duke
parents:
diff changeset
   989
   <li><code>focusTraversalKeysEnabled</code>: the Component's
90ce3da70b43 Initial load
duke
parents:
diff changeset
   990
       focus traversal keys enabled state
90ce3da70b43 Initial load
duke
parents:
diff changeset
   991
   <li><code>forwardFocusTraversalKeys</code>: the Component's Set of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   992
       <code>FORWARD_TRAVERSAL_KEYS</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   993
   <li><code>backwardFocusTraversalKeys</code>: the Component's Set of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   994
       <code>BACKWARD_TRAVERSAL_KEYS</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   995
   <li><code>upCycleFocusTraversalKeys</code>: the Component's Set of
90ce3da70b43 Initial load
duke
parents:
diff changeset
   996
       <code>UP_CYCLE_TRAVERSAL_KEYS</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   997
  </ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   998
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
   999
In addition to the Component properties, Container supports the
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1000
following focus-related properties:
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1001
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1002
  <ol>
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1003
    <li><code>downCycleFocusTraversalKeys</code>: the Container's Set of
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1004
        <code>DOWN_CYCLE_TRAVERSAL_KEYS</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1005
    <li><code>focusTraversalPolicy</code>: the Container's focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1006
        traversal policy
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1007
    <li><code>focusCycleRoot</code>: the Container's focus-cycle-root state
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1008
  </ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1009
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1010
In addition to the Container properties, Window supports the following
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1011
focus-related property:
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1012
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1013
  <ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1014
    <li><code>focusableWindow</code>: the Window's focusable Window state
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1015
  </ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1016
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1017
Also note that a <code>PropertyChangeListener</code> installed on a
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1018
Window will never see a <code>PropertyChangeEvent</code> for the
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1019
<code>focusCycleRoot</code> property.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1020
A Window is always a focus cycle root; this property cannot change.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1021
<p>
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1022
<a id="FocusAndVetoableChangeListener"></a>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1023
<h3>Focus and VetoableChangeListener</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1024
<p>
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1025
The <code>KeyboardFocusManager</code> also supports
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1026
<code>VetoableChangeListener</code>s for the following properties:
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1027
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1028
  <ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1029
    <li>"focusOwner": the focus owner
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1030
    <li>"focusedWindow": the focused Window
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1031
    <li>"activeWindow": the active Window
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1032
  </ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1033
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1034
If a VetoableChangeListener vetoes a focus or activation change by
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1035
throwing a PropertyVetoException, the change is aborted. Any
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1036
VetoableChangeListeners which had already approved the change will
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1037
asynchronously receive PropertyChangeEvents indicating a reversion of
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1038
state to the previous value.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1039
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1040
VetoableChangeListeners are notified of the state change before the
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1041
change is reflected in the KeyboardFocusManager. Conversely,
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1042
PropertyChangeListeners are notified after the change is reflected.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1043
It follows that all VetoableChangeListeners will be notified before
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1044
any PropertyChangeListener.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1045
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1046
VetoableChangeListeners must be idempotent, and must veto both loss
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1047
and gain events for a particular focus change (e.g., both
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1048
<code>FOCUS_LOST</code> and <code>FOCUS_GAINED</code>). For example,
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1049
if a <code>VetoableChangeListener</code> vetoes a <code>FOCUS_LOST</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1050
event, a <code>KeyboardFocusManager</code> is not required to search the
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1051
<code>EventQueue</code> and remove the associated pending
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1052
<code>FOCUS_GAINED</code> event. Instead, the
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1053
<code>KeyboardFocusManager</code> is free to attempt to
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1054
dispatch this event and it is the responsibility of the
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1055
<code>VetoableChangeListener</code> to veto it as well. In addition,
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1056
during processing of the <code>FOCUS_GAINED</code> event, the
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1057
<code>KeyboardFocusManager</code> may attempt to resync the global
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1058
focus state by synthesizing another <code>FOCUS_LOST</code> event.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1059
This event must be vetoed just as the first <code>FOCUS_LOST</code> event was.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1060
<p>
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1061
A <code>KeyboardFocusManager</code> may not hold any locks while
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1062
notifying <code>PropertyChangeListener</code>s of a state change.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1063
This requirement is relaxed for <code>VetoableChangeListeners</code>,
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1064
however. Therefore, client-definied <code>VetoableChangeListener</code>s
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1065
should avoid acquiring additional locks inside
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1066
<code>vetoableChange(PropertyChangeEvent)</code> as this may lead to deadlock.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1067
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1068
If a focus or activation change is rejected, the KeyboardFocusManager
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1069
will initiate rejection recovery as follows:
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1070
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1071
  <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1072
    <li>If a focused or active Window change was rejected, then the
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1073
        focused or active Window will be reset to the Window which was
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1074
        previously the focused or active Window. If there is no such
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1075
        Window, then the <code>KeyboardFocusManager</code> will clear
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1076
        the global focus owner.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1077
    <li>If a focus owner change was rejected, then the focus owner will be
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1078
        reset to the Component which was previously the focus owner. If
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1079
        that is not possible, then it will be reset to the next Component
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1080
        in the focus traversal cycle after the previous focus owner. If
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1081
        that is also not possible, then the <code>KeyboardFocusManager</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1082
        will clear the global focus owner.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1083
  </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1084
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1085
<code>VetoableChangeListener</code>s must be careful to avoid vetoing focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1086
changes initiated as a result of veto rejection recovery. Failure
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1087
to anticipate this situation could lead to an infinite cycle of
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1088
vetoed focus changes and recovery attempts.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1089
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1090
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1091
<a id="ZOrder"></a>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1092
<h3>Z-Order</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1093
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1094
On some native windowing systems, the Z-order of a Window can affect
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1095
its focused or active (if applicable) state. On Microsoft Windows, the
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1096
top-most Window is naturally the focused Window as well. However, on
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1097
Solaris, many window managers use a point-to-focus model that ignores
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1098
Z-order in determining the focused Window.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1099
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1100
When focusing or activating Windows, the AWT adheres to the UI
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1101
requirements of the native platform. Therefore, the focus behavior of
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1102
Z-order-related methods such as:
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1103
  <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1104
    <li><code>Window.toFront()</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1105
    <li><code>Window.toBack()</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1106
    <li><code>Window.show()</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1107
    <li><code>Window.hide()</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1108
    <li><code>Window.setVisible(boolean)</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1109
    <li><code>Window.dispose()</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1110
    <li><code>Frame.setState(int)</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1111
  </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1112
is platform-dependent. In JDK 1.4, the behavior of these methods on
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1113
Microsoft Windows and Solaris is as follows:
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1114
  <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1115
     <li><code>Window.toFront()</code>:<br>
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1116
        <b>Microsoft Windows</b>: The Window is moved to front, if possible.
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1117
        While we will always be able to move this Window in front of other
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1118
        Windows in the same VM, Windows 98 and Windows 2000 do not allow an
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1119
        application to bring any of its windows to the front unless one
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1120
        of that application's windows is already in the foreground. In
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1121
        this case, Windows will instead flash the Window's icon in the
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1122
        taskbar. If the Window is moved to the front, it will be made
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1123
        the focused and (if applicable) active Window.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1124
      <br>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1125
        <b>Solaris</b>: The Window is moved to front. In a point-to-focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1126
        window manager, the Window will become the focused Window if it
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1127
        is the top-most Window underneath the cursor. In a click-to-focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1128
        window manager, the focused Window will remain unchanged.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1129
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1130
     <li><code>Window.toBack()</code>:<br>
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1131
        <b>Microsoft Windows</b>: The Window is moved to back. Note however
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1132
        that Microsoft Windows insists that an owned Window always be in
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1133
        front of all of its recursive owners. Thus, after the completion of
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1134
        this operation, the Window may not be the lowest Java Window in the
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1135
        Z-order. If the Window, or any of its owners, was the focused Window,
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1136
        then the focused Window is reset to the top-most Window in the VM.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1137
      <br>
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1138
        <b>Solaris</b>: The Window is moved to back. Like Microsoft Windows,
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1139
        some window managers insist than an owned Window always be in front
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1140
        of all of its recursive owners. Thus, after the completion of this
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1141
        operation, the Window may not be the lowest Java Window in the
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1142
        Z-order. If the Window was the focused Window, it will lose
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1143
        focus in a point-to-focus window manager if it is no longer the
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1144
        top-most Window under the cursor. In a click-to-focus window
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1145
        manager, the focused Window will remain unchanged.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1146
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1147
     <li><code>Window.show()/Window.setVisible(true)/Frame.setState(NORMAL)</code>:<br>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1148
        <b>Microsoft Windows</b>: The Window is moved to front and becomes the focused
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1149
        Window.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1150
      <br>
21254
f6d36ee3f269 8025824: [cleanup] Fix tidy errors and warnings in preformatted HTML files related to 2d/awt/swing
yan
parents: 9035
diff changeset
  1151
        <b>Solaris</b>: The Window is moved to front. In a point-to-focus focus
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1152
        window manager, the Window will be focused if it is now the
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1153
        top-most Window under the cursor. In a click-to-focus window
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1154
        manager, the Window will become the focused Window.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1155
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1156
     <li><code>Window.hide()/Window.setVisible(false)/Window.dispose()/
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1157
    Frame.setState(ICONIFIED)</code>:<br>
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1158
        <b>Microsoft Windows</b>: If the Window was the focused Window, the focused
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1159
        Window is reset to a window chosen by the OS, or to no window. The
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1160
        window may be in a native application, or a Java application in
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1161
        another VM.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1162
       <br>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1163
        <b>Solaris</b>: If the Window was the focused Window, in a point-to-
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1164
        focus window manager, the top-most Window under the cursor will
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1165
        become the focused Window. In a click-to-focus window manager,
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1166
        the focused Window is reset to a window chosen by the window
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1167
        manager. The window may be in a native application, or a Java
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1168
        application in another VM.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1169
  </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1170
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1171
<a id="ReplacingDefaultKeyboardFocusManager"></a>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1172
<h3>Replacing DefaultKeyboardFocusManager</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1173
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1174
<code>KeyboardFocusManager</code>s are pluggable at the browser context
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1175
level. Client code can subclass <code>KeyboardFocusManager</code> or
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1176
<code>DefaultKeyboardFocusManager</code> to modify the way that WindowEvents
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1177
related to focus, FocusEvents, and KeyEvents are handled and
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1178
dispatched, and to examine and modify the global focus state. A custom
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1179
<code>KeyboardFocusManager</code> can also reject focus changes at a more
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1180
fundamental level then a FocusListener or WindowListener ever could.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1181
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1182
While giving a developer ultimate control over the focus model,
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1183
replacing the entire <code>KeyboardFocusManager</code> is a difficult process
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1184
requiring a thorough understanding of the peer focus layer.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1185
Fortunately, most applications do not need this much control.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1186
Developers are encouraged to use KeyEventDispatchers,
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1187
KeyEventPostProcessors, FocusTraversalPolicies,
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1188
VetoableChangeListeners, and other concepts discussed in this document
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1189
before resorting to a full replacement of the <code>KeyboardFocusManager</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1190
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1191
First note that, because unhindered access to Components in other
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1192
contexts represents a security hole, the SecurityManager must grant a
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1193
new permission, "replaceKeyboardFocusManager", before client code is
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1194
permitted to replace the <code>KeyboardFocusManager</code> with an arbitrary
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1195
subclass instance. Because of the security check, replacing the
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1196
<code>KeyboardFocusManager</code> is not an option for applications that will be
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1197
deployed in environments with a SecurityManager, such as applets in a
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1198
browser.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1199
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1200
Once installed, a <code>KeyboardFocusManager</code> instance has
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1201
access to the global focus state via a set of protected functions.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1202
The <code>KeyboardFocusManager</code> can only call these functions
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1203
if it is installed in the calling thread's context. This ensures
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1204
that malicious code cannot circumvent the security check in
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1205
<code>KeyboardFocusManager.setCurrentFocusManager</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1206
A <code>KeyboardFocusManager</code> should always work with
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1207
the global focus state instead of the context focus state.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1208
Failure to do this will lead to incorrect behavior of the
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1209
<code>KeyboardFocusManager</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1210
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1211
The primary responsibility of a <code>KeyboardFocusManager</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1212
is the dispatch of the following events:
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1213
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1214
    <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1215
      <li>all <code>KeyEvent</code>s
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1216
      <li>all <code>FocusEvent</code>s
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1217
      <li><code>WindowEvent.WINDOW_GAINED_FOCUS</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1218
      <li><code>WindowEvent.WINDOW_LOST_FOCUS</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1219
      <li><code>WindowEvent.WINDOW_ACTIVATED</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1220
      <li><code>WindowEvent.WINDOW_DEACTIVATED</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1221
    </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1222
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1223
The peer layer will provide the <code>KeyboardFocusManager</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1224
with all of the above events except <code>WINDOW_ACTIVATED</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1225
and <code>WINDOW_DEACTIVATED</code>. The <code>KeyboardFocusManager</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1226
must synthesize <code>WINDOW_ACTIVATED</code> and
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1227
<code>WINDOW_DEACTIVATED</code> events when appropriate and target them
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1228
accordingly.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1229
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1230
The <code>KeyboardFocusManager</code> may need to retarget the events
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1231
provided by the peer layer to its own notion of the focus owner or
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1232
focused Window:
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1233
    <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1234
      <li>A KeyEvent must be retargeted to the focus owner. Because the peer
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1235
          layer is unaware of any lightweight Components, KeyEvents will
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1236
          arrive from the peer layer targeted to the focus owner's
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1237
          heavyweight Container, not the focus owner.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1238
      <li>A <code>FOCUS_LOST</code> event must be retargeted to the focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1239
          owner. Again, this is necessary because the peer layer is
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1240
          unaware of lightweight Components.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1241
      <li>A <code>WINDOW_LOST_FOCUS</code> event must be retargeted to
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1242
          the focused Window. The implementation of the Window class
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1243
          may cause the native focused Window to differ from the Java
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1244
          focused Window.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1245
    </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1246
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1247
A <code>KeyboardFocusManager</code> must ensure proper event ordering,
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1248
and a 1-to-1 correspondence between an event and its opposite event type.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1249
The peer layer does not make any of these guarantees. For example, it is
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1250
possible for the peer layer to send a <code>FOCUS_GAINED</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1251
event before a <code>WINDOW_GAINED_FOCUS</code> event.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1252
The <code>KeyboardFocusManager</code> is responsible for
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1253
ensuring that the <code>WINDOW_GAINED_FOCUS</code> event is dispatched
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1254
before the <code>FOCUS_GAINED</code> event.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1255
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1256
Before redispatching an event via <code>KeyboardFocusManager</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1257
<code>redispatchEvent</code>, a <code>KeyboardFocusManager</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1258
must attempt to update the global focus state. Typically, this
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1259
is done using one of the <code>KeyboardFocusManager.setGlobal*</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1260
methods; however, an implementation is free to implement its own methods.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1261
After attempting an update, the <code>KeyboardFocusManager</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1262
must verify that the global focus state change
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1263
was not rejected. A rejection is detected when a call to the
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1264
corresponding <code>getGlobal*</code> method returns a value different than the
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1265
value just set. Rejections occur in three standard cases:
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1266
    <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1267
      <li>If the <code>KeyboardFocusManager</code> attempts
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1268
          to set the global focus owner to a non-focusable Component.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1269
      <li>If the <code>KeyboardFocusManager</code> attempts
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1270
          to set the global focused Window to a non-focusable Window.
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1271
      <li>If the change is rejected by an installed
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1272
          <code>VetoableChangeListener</code>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1273
    </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1274
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1275
Client-defined implementations of <code>KeyboardFocusManager</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1276
can adjust the set of focus transfers which are rejected by overriding the
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1277
accessor and mutator methods for the global focus state.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1278
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1279
If a request to change the global focus state is rejected, the
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1280
<code>KeyboardFocusManager</code> must discard the event which prompted
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1281
the focus change request. The Component to which the event was targeted
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1282
must not receive the event.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1283
<p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1284
The <code>KeyboardFocusManager</code> is also expected to initiate rejection
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1285
recovery as outlined in <a href="#FocusAndVetoableChangeListener">Focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1286
and VetoableChangeListener</a>.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1287
  <p>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1288
     Finally, a KeyboardFocusManager must handle the following set of
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1289
     special cases:
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1290
    <ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1291
      <li>When handling a <code>WINDOW_GAINED_FOCUS</code> event, the
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1292
          <code>KeyboardFocusManager</code> must set focus to the
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1293
          appropriate child Component of the Window. If a child
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1294
          Component of the Window previously requested focus,
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1295
          but the focus change was rejected because the platform
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1296
          does not support cross-Window focus change requests,
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1297
          then focus should be set to that child Component.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1298
          Otherwise, if the Window has never been focused, focus should be
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1299
          set to the Window's initial Component to focus. If the Window was
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1300
          previously focused, focus should be set to the Window's most
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1301
          recent focus owner.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1302
      <li>The <code>KeyboardFocusManager</code> must ensure that the
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1303
          opposite Component or Window are as accurate as the native
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1304
          windowing platform permits. For example, the
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1305
          <code>KeyboardFocusManager</code> may need to
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1306
          retarget the opposite Component to a lightweight child of the
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1307
          heavyweight initially specified by the peer layer.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1308
          <br>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1309
          If the peer layer states that the opposite Component or Window is
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1310
          <code>null</code>, it is acceptable for the
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1311
          <code>KeyboardFocusManager</code> to propagate
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1312
          this value. <code>null</code> indicates that it is highly
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1313
          probably that no other Component or Window was involved
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1314
          in the focus or activation change. Because of platform
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1315
          limitations, this computation may be
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1316
          subject to a heuristic and could be incorrect. Nevertheless, this
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1317
          heuristic will be the best possible guess which the peer layer
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1318
          could make.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1319
       <li>Focus and activation changes in which a Component or Window loses
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1320
          focus or activation to itself must be discarded.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1321
       <li>Events posted by the peer layer claiming that the active Window
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1322
          has lost focus to the focused Window must be discarded. The peer
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1323
          implementation of the Window class may generate these spurious
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1324
          events.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1325
    </ul>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1326
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1327
<a id="Incompatibilities"></a>
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1328
<h3>Incompatibilities with Previous Releases</h3>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1329
  <p><b>Cross-platform changes:</b>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1330
    <ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1331
      <li>The default focus traversability for all Components is now
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1332
          'true'. Previously, some Components (in particular, all
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1333
          lightweights), had a default focus traversability of 'false'. Note
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1334
          that despite this change, however, the
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1335
          <code>DefaultFocusTraversalPolicy</code> for all AWT Containers
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1336
          will preserve the traversal order of previous releases.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1337
      <li>A request to focus a non-focus traversable (i.e., non-focusable)
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1338
          Component will be denied. Previously, such requests were granted.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1339
      <li><code>Window.toFront()</code> and <code>Window.toBack()</code>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1340
          now perform no operation if the Window is not visible.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1341
          Previously, the behavior was platform-dependent.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1342
      <li>KeyListeners installed on <code>Component</code>s
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1343
          will no longer see <code>KeyEvent</code>s that map to focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1344
          traversal operations, and
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1345
          <code>Component.handleEvent()</code> will no longer be invoked
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1346
          for such events. Previously, AWT Components saw these events
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1347
          and had an opportunity to consume them before AWT
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1348
          initiated focus traversal. Code that requires this
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1349
          functionality should instead disable focus traversal keys on
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1350
          its <code>Component</code>s and handle focus traversal
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1351
          itself. Alternately, the code can use an
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1352
          <code>AWTEventListener</code> or
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1353
          <code>KeyEventDispatcher</code> to pre-listen to all
48264
efda6932a433 8182410: missing 'title' in api/javax/swing/plaf/synth/doc-files/componentProperties.html
serb
parents: 47216
diff changeset
  1354
          <code>KeyEvent</code>s.
2
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1355
    </ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1356
  <p><b>Changes specific to Microsoft Windows:</b>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1357
    <ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1358
      <li><code>Window.toBack()</code> changes the focused Window to
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1359
          the top-most Window after the Z-order change.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1360
      <li><code>requestFocus()</code> now allows cross-Window focus
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1361
          change requests in all cases. Previously, requests were granted
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1362
          for heavyweights, but denied for lightweights.
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1363
    </ol>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1364
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1365
</body>
90ce3da70b43 Initial load
duke
parents:
diff changeset
  1366
</html>