--- old/src/java.desktop/share/classes/java/awt/doc-files/FocusSpec.html 2017-10-23 13:51:02.000000000 -0700 +++ new/src/java.desktop/share/classes/java/awt/doc-files/FocusSpec.html 2017-10-23 13:51:02.000000000 -0700 @@ -1,5 +1,11 @@ + + + + + The AWT Focus Subsystem + - - - - - The AWT Focus Subsystem - - - -

The AWT Focus Subsystem

+ +

The AWT Focus Subsystem

Prior to Java 2 Standard Edition, JDK 1.4, the AWT focus subsystem @@ -57,8 +56,8 @@ determining the "opposite" Component involved in the focus or activation change. For example, when a Component received a FOCUS_LOST event, it had no way of knowing which Component was gaining - focus. Since Microsoft Windows provides this functionality for free, - developers migrating from Microsoft Windows C/C++ or Visual Basic to + focus. Since Microsoft Windows provides this functionality for free, + developers migrating from Microsoft Windows C/C++ or Visual Basic to Java had been frustrated by the omission.

To address these and other deficiencies, we have designed a new focus @@ -101,7 +100,7 @@

  • Incompatibilities with Previous Releases - +

    Overview of KeyboardFocusManager

    The focus model is centralized around a single class, @@ -160,7 +159,7 @@ define new focus cycle but only modifies the order by which its children are traversed "forward" and "backward". Focus traversal policy provider can be set using - setFocusTraversalPolicyProvider on the Container. + setFocusTraversalPolicyProvider on the Container.

    @@ -180,7 +179,7 @@ descendants.

    - Here is an example:
    Three groups as described below: ABCF BDE and DGH.

    Assume the following: @@ -193,7 +192,7 @@

  • G, H, E, and F are all Components. - + There are a total of three focus cycle roots in this example:
      @@ -213,7 +212,7 @@ implementation in the DefaultKeyboardFocusManager class. - +

      KeyboardFocusManager and Browser Contexts

      Some browsers partition applets in different code bases into separate @@ -229,7 +228,7 @@ owner, focused Window, or active Window, per ClassLoader. - +

      KeyEventDispatcher and KeyEventPostProcessor

      While the user's KeyEvents should generally be delivered to the focus @@ -272,7 +271,7 @@ KeyEventPostProcessor, and similar restrictions apply to its use in that capacity. - +

      FocusEvent and WindowEvent

      The AWT defines the following six event types central to the focus @@ -296,7 +295,7 @@ not a Frame or Dialog) when it is no longer the active Window.

    - +

    Event Delivery

    If the focus is not in java application and the user clicks on a focusable @@ -347,7 +346,7 @@ and VetoableChangeListener. - +

    Opposite Components and Windows

    Each event includes information about the "opposite" Component or @@ -371,7 +370,7 @@ using the opposite Component of a focus change that occurred within a top-level Window. - +

    Temporary FocusEvents

    FOCUS_GAINED and FOCUS_LOST events are @@ -380,7 +379,7 @@ Temporary FOCUS_LOST events are sent when a Component is losing the focus, but will regain the focus shortly. These events can be useful when focus changes are used as triggers for validation -of data. For instance, a text Component may want to commit its +of data. For instance, a text Component may want to commit its contents when the user begins interacting with another Component, and can accomplish this by responding to FOCUS_LOST events. However, if the FocusEvent received is temporary, @@ -402,8 +401,8 @@ When a Component receives a temporary FOCUS_LOST event, the event's opposite Component (if any) may receive a temporary FOCUS_GAINED event, but could also receive a permanent -FOCUS_GAINED event. Showing a Menu or PopupMenu, or -clicking or dragging a Scrollbar, should generate a temporary +FOCUS_GAINED event. Showing a Menu or PopupMenu, or +clicking or dragging a Scrollbar, should generate a temporary FOCUS_GAINED event. Changing the focused Window, however, will yield a permanent FOCUS_GAINED event for the new focus owner. @@ -416,7 +415,7 @@ Components. This method is not intended for general use, but exists instead as a hook for lightweight Component libraries, such as Swing. - +

    Focus Traversal

    Each Component defines its own Set of focus traversal keys for a given @@ -428,11 +427,11 @@ recursively inherits a Set from its parent, and ultimately from a context-wide default set on the current KeyboardFocusManager.

    -Using the AWTKeyStroke API, client code can specify -on which of two specific KeyEvents, KEY_PRESSED or +Using the AWTKeyStroke API, client code can specify +on which of two specific KeyEvents, KEY_PRESSED or KEY_RELEASED, the focus traversal operation will occur. Regardless of which KeyEvent is specified, however, all KeyEvents -related to the focus traversal key, including the associated +related to the focus traversal key, including the associated KEY_TYPED event, will be consumed, and will not be dispatched to any Component. It is a runtime error to specify a KEY_TYPED event as mapping to a focus traversal operation, @@ -475,7 +474,7 @@ normal focus traversal. Thus, the current KeyboardFocusManager maintains a reference to the "current" focus cycle root, which is global across all contexts. The -current focus cycle root is used to resolve the ambiguity. +current focus cycle root is used to resolve the ambiguity.

    For up-cycle traversal, the focus owner is set to the current focus owner's focus cycle root, and the current focus cycle root is set to @@ -491,10 +490,10 @@ root, then no focus traversal operation occurs. - +

    FocusTraversalPolicy

    - + A FocusTraversalPolicy defines the order in which Components within a particular focus cycle root or focus traversal policy provider are traversed. Instances of FocusTraversalPolicy can be shared across @@ -524,7 +523,7 @@

    -A FocusTraversalPolicy may optionally provide an +A FocusTraversalPolicy may optionally provide an algorithm for the following:

    Given a Window, the "initial" Component in that Window. The initial @@ -551,7 +550,7 @@ ancestor. Top-levels initialize their focus traversal policies using the context default policy. The context default policy is established by using KeyboardFocusManager. setDefaultFocusTraversalPolicy. - +

    AWT provides two standard FocusTraversalPolicy implementations for use by client code. @@ -573,14 +572,14 @@

  • DefaultFocusTraversalPolicy: A subclass of ContainerOrderFocusTraversalPolicy which redefines the fitness test. If client code has explicitly set the - focusability of a Component by either overriding + focusability of a Component by either overriding Component.isFocusTraversable() or Component.isFocusable(), or by calling - Component.setFocusable(boolean), then a + Component.setFocusable(boolean), then a DefaultFocusTraversalPolicy behaves exactly like a ContainerOrderFocusTraversalPolicy. If, however, the Component is relying on default focusability, then a - DefaultFocusTraversalPolicy will reject all + DefaultFocusTraversalPolicy will reject all Components with non-focusable peers.
    The focusability of a peer is implementation-dependent. Sun @@ -627,7 +626,7 @@

    The figure below shows an implicit focus transfer: -
    Implicit focus transfer.
    +
    Implicit focus transfer.
    Assume the following:

      @@ -653,7 +652,7 @@ All other applications, including pure AWT applications, will use DefaultFocusTraversalPolicy by default. - +

      Focus Traversal Policy Providers

      A Container that isn't a focus cycle root has an option to provide a @@ -674,7 +673,7 @@ If focus traversal policy provider property is set on a focus cycle root, it isn't considered a focus traversal policy provider and behaves just like any other focus cycle root. - +

      The main difference between focus cycle roots and focus traversal policy providers is that the latter allow focus to enter and leave them just as all other @@ -740,7 +739,7 @@

    - +

    Programmatic Traversal

    In addition to user-initiated focus traversal, client code can @@ -811,7 +810,7 @@ unchanged. - +

    Focusability

    A focusable Component can become the focus owner ("focusability") and @@ -825,7 +824,7 @@ change this default by calling Component.setFocusable(boolean). - +

    Focusable Windows

    To support palette windows and input methods, client code can prevent @@ -877,7 +876,7 @@ all such focus change requests will fail. In this case, the global focus owner will be cleared and the focused Window will remain unchanged. - +

    Requesting Focus

    @@ -949,7 +948,7 @@ a temporary state. See Temporary FocusEvents - +

    Focus and PropertyChangeListener

    Client code can listen to changes in context-wide focus state, or to @@ -957,7 +956,7 @@ PropertyChangeListeners.

    The KeyboardFocusManager supports the following properties: - +

    1. focusOwner: the focus owner
    2. focusedWindow: the focused Window @@ -977,7 +976,7 @@

      A PropertyChangeListener installed on the current KeyboardFocusManager will only see these changes within -the KeyboardFocusManager's context, even though the +the KeyboardFocusManager's context, even though the focus owner, focused Window, active Window, and current focus cycle root comprise the global focus state shared by all contexts. We believe this is less intrusive than requiring client code to pass @@ -1001,7 +1000,7 @@ following focus-related properties:

        -
      1. downCycleFocusTraversalKeys: the Container's Set of +
      2. downCycleFocusTraversalKeys: the Container's Set of DOWN_CYCLE_TRAVERSAL_KEYS
      3. focusTraversalPolicy: the Container's focus traversal policy @@ -1020,10 +1019,10 @@ focusCycleRoot property. A Window is always a focus cycle root; this property cannot change.

        - +

        Focus and VetoableChangeListener

        -The KeyboardFocusManager also supports +The KeyboardFocusManager also supports VetoableChangeListeners for the following properties:

          @@ -1054,13 +1053,13 @@ KeyboardFocusManager is free to attempt to dispatch this event and it is the responsibility of the VetoableChangeListener to veto it as well. In addition, -during processing of the FOCUS_GAINED event, the +during processing of the FOCUS_GAINED event, the KeyboardFocusManager may attempt to resync the global focus state by synthesizing another FOCUS_LOST event. This event must be vetoed just as the first FOCUS_LOST event was.

          -A KeyboardFocusManager may not hold any locks while -notifying PropertyChangeListeners of a state change. +A KeyboardFocusManager may not hold any locks while +notifying PropertyChangeListeners of a state change. This requirement is relaxed for VetoableChangeListeners, however. Therefore, client-definied VetoableChangeListeners should avoid acquiring additional locks inside @@ -1089,13 +1088,13 @@ vetoed focus changes and recovery attempts. - +

          Z-Order

          On some native windowing systems, the Z-order of a Window can affect -its focused or active (if applicable) state. On Microsoft Windows, the -top-most Window is naturally the focused Window as well. However, on -Solaris, many window managers use a point-to-focus model that ignores +its focused or active (if applicable) state. On Microsoft Windows, the +top-most Window is naturally the focused Window as well. However, on +Solaris, many window managers use a point-to-focus model that ignores Z-order in determining the focused Window. When focusing or activating Windows, the AWT adheres to the UI @@ -1114,8 +1113,8 @@ Microsoft Windows and Solaris is as follows:

          • Window.toFront():
            - Microsoft Windows: The Window is moved to front, if possible. - While we will always be able to move this Window in front of other + Microsoft Windows: The Window is moved to front, if possible. + While we will always be able to move this Window in front of other Windows in the same VM, Windows 98 and Windows 2000 do not allow an application to bring any of its windows to the front unless one of that application's windows is already in the foreground. In @@ -1129,15 +1128,15 @@ window manager, the focused Window will remain unchanged.
          • Window.toBack():
            - Microsoft Windows: The Window is moved to back. Note however - that Microsoft Windows insists that an owned Window always be in - front of all of its recursive owners. Thus, after the completion of - this operation, the Window may not be the lowest Java Window in the - Z-order. If the Window, or any of its owners, was the focused Window, + Microsoft Windows: The Window is moved to back. Note however + that Microsoft Windows insists that an owned Window always be in + front of all of its recursive owners. Thus, after the completion of + this operation, the Window may not be the lowest Java Window in the + Z-order. If the Window, or any of its owners, was the focused Window, then the focused Window is reset to the top-most Window in the VM.
            - Solaris: The Window is moved to back. Like Microsoft Windows, - some window managers insist than an owned Window always be in front + Solaris: The Window is moved to back. Like Microsoft Windows, + some window managers insist than an owned Window always be in front of all of its recursive owners. Thus, after the completion of this operation, the Window may not be the lowest Java Window in the Z-order. If the Window was the focused Window, it will lose @@ -1156,7 +1155,7 @@
          • Window.hide()/Window.setVisible(false)/Window.dispose()/ Frame.setState(ICONIFIED):
            - Microsoft Windows: If the Window was the focused Window, the focused + Microsoft Windows: If the Window was the focused Window, the focused Window is reset to a window chosen by the OS, or to no window. The window may be in a native application, or a Java application in another VM. @@ -1169,7 +1168,7 @@ application in another VM.
          - +

          Replacing DefaultKeyboardFocusManager

          KeyboardFocusManagers are pluggable at the browser context @@ -1238,7 +1237,7 @@ heavyweight Container, not the focus owner.

        1. A FOCUS_LOST event must be retargeted to the focus owner. Again, this is necessary because the peer layer is - unaware of lightweight Components. + unaware of lightweight Components.
        2. A WINDOW_LOST_FOCUS event must be retargeted to the focused Window. The implementation of the Window class may cause the native focused Window to differ from the Java @@ -1269,7 +1268,7 @@ to set the global focus owner to a non-focusable Component.
        3. If the KeyboardFocusManager attempts to set the global focused Window to a non-focusable Window. -
        4. If the change is rejected by an installed +
        5. If the change is rejected by an installed VetoableChangeListener.

          @@ -1302,13 +1301,13 @@ recent focus owner.

        6. The KeyboardFocusManager must ensure that the opposite Component or Window are as accurate as the native - windowing platform permits. For example, the + windowing platform permits. For example, the KeyboardFocusManager may need to retarget the opposite Component to a lightweight child of the heavyweight initially specified by the peer layer.
          If the peer layer states that the opposite Component or Window is - null, it is acceptable for the + null, it is acceptable for the KeyboardFocusManager to propagate this value. null indicates that it is highly probably that no other Component or Window was involved @@ -1325,7 +1324,7 @@ events. - +

          Incompatibilities with Previous Releases

          Cross-platform changes:

            @@ -1343,7 +1342,7 @@
          1. KeyListeners installed on Components will no longer see KeyEvents that map to focus traversal operations, and - Component.handleEvent() will no longer be invoked + Component.handleEvent() will no longer be invoked for such events. Previously, AWT Components saw these events and had an opportunity to consume them before AWT initiated focus traversal. Code that requires this @@ -1352,7 +1351,7 @@ itself. Alternately, the code can use an AWTEventListener or KeyEventDispatcher to pre-listen to all - KeyEvents. + KeyEvents.

          Changes specific to Microsoft Windows: