java.awt
Class KeyboardFocusManager

java.lang.Object
  extended byjava.awt.KeyboardFocusManager
All Implemented Interfaces:
KeyEventDispatcher, KeyEventPostProcessor
Direct Known Subclasses:
DefaultKeyboardFocusManager

public abstract class KeyboardFocusManager
extends Object
implements KeyEventDispatcher, KeyEventPostProcessor

The KeyboardFocusManager is responsible for managing the active and focused Windows, and the current focus owner. The focus owner is defined as the Component in an application that will typically receive all KeyEvents generated by the user. The focused Window is the Window that is, or contains, the focus owner. Only a Frame or a Dialog can be the active Window. The native windowing system may denote the active Window or its children with special decorations, such as a highlighted title bar. The active Window is always either the focused Window, or the first Frame or Dialog that is an owner of the focused Window.

The KeyboardFocusManager is both a centralized location for client code to query for the focus owner and initiate focus changes, and an event dispatcher for all FocusEvents, WindowEvents related to focus, and KeyEvents.

Some browsers partition applets in different code bases into separate contexts, and establish walls between these contexts. In such a scenario, there will be one KeyboardFocusManager per context. Other browsers place all applets into the same context, implying that there will be only a single, global KeyboardFocusManager for all applets. This behavior is implementation-dependent. Consult your browser's documentation for more information. No matter how many contexts there may be, however, there can never be more than one focus owner, focused Window, or active Window, per ClassLoader.

Since:
1.4
Author:
David Mendenhall
See Also:
Window, Frame, Dialog, FocusEvent, WindowEvent, KeyEvent

Nested Class Summary
private static class KeyboardFocusManager.HeavyweightFocusRequest
           
private static class KeyboardFocusManager.LightweightFocusRequest
           
 
Field Summary
private static Window activeWindow
          Only a Frame or a Dialog can be the active Window.
static int BACKWARD_TRAVERSAL_KEYS
          The identifier for the Backward focus traversal keys.
private  java.beans.PropertyChangeSupport changeSupport
          A description of any PropertyChangeListeners which have been registered.
private static boolean clearingCurrentLightweightRequests
           
private static Container currentFocusCycleRoot
          The current focus cycle root.
private static LinkedList currentLightweightRequests
           
(package private)  SequencedEvent currentSequencedEvent
           
private static sun.awt.DebugHelper dbg
           
private static String[] defaultFocusTraversalKeyPropertyNames
          The bound property names of each focus traversal key.
private  Set[] defaultFocusTraversalKeys
          The default focus traversal keys.
private static String[] defaultFocusTraversalKeyStrings
          The default Strings for initializing the default focus traversal keys.
private  FocusTraversalPolicy defaultPolicy
          The default FocusTraversalPolicy for all Windows that have no policy of their own set.
static int DOWN_CYCLE_TRAVERSAL_KEYS
          The identifier for the Down Cycle focus traversal keys.
private static Window focusedWindow
          The Window which is, or contains, the focus owner.
private static Component focusOwner
          The Component in an application that will typically receive all KeyEvents generated by the user.
static int FORWARD_TRAVERSAL_KEYS
          The identifier for the Forward focus traversal keys.
private static LinkedList heavyweightRequests
           
private  LinkedList keyEventDispatchers
          This KeyboardFocusManager's KeyEventDispatcher chain.
private  LinkedList keyEventPostProcessors
          This KeyboardFocusManager's KeyEventPostProcessor chain.
private static Map mostRecentFocusOwners
          Maps Windows to those Windows' most recent focus owners.
private static Component newFocusOwner
           
private static String notPrivileged
          Error String for initializing SecurityExceptions.
private static Component permanentFocusOwner
          The Component in an application that will regain focus when an outstanding temporary focus transfer has completed, or the focus owner, if no outstanding temporary transfer exists.
private static AWTPermission replaceKeyboardFocusManagerPermission
          We cache the permission used to verify that the calling thread is permitted to access the global focus state.
(package private) static int SNFH_FAILURE
           
(package private) static int SNFH_SUCCESS_HANDLED
           
(package private) static int SNFH_SUCCESS_PROCEED
           
(package private) static int TRAVERSAL_KEY_LENGTH
           
static int UP_CYCLE_TRAVERSAL_KEYS
          The identifier for the Up Cycle focus traversal keys.
private  java.beans.VetoableChangeSupport vetoableSupport
          A description of any VetoableChangeListeners which have been registered.
 
Constructor Summary
KeyboardFocusManager()
          Initializes a KeyboardFocusManager.
 
Method Summary
private  void _clearGlobalFocusOwner()
           
 void addKeyEventDispatcher(KeyEventDispatcher dispatcher)
          Adds a KeyEventDispatcher to this KeyboardFocusManager's dispatcher chain.
 void addKeyEventPostProcessor(KeyEventPostProcessor processor)
          Adds a KeyEventPostProcessor to this KeyboardFocusManager's post- processor chain.
 void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
          Adds a PropertyChangeListener to the listener list.
 void addPropertyChangeListener(String propertyName, java.beans.PropertyChangeListener listener)
          Adds a PropertyChangeListener to the listener list for a specific property.
 void addVetoableChangeListener(String propertyName, java.beans.VetoableChangeListener listener)
          Adds a VetoableChangeListener to the listener list for a specific property.
 void addVetoableChangeListener(java.beans.VetoableChangeListener listener)
          Adds a VetoableChangeListener to the listener list.
private static void clearFocusRequestList()
           
 void clearGlobalFocusOwner()
          Clears the global focus owner at both the Java and native levels.
(package private) static void clearMostRecentFocusOwner(Component comp)
           
protected abstract  void dequeueKeyEvents(long after, Component untilFocused)
          Called by the AWT to notify the KeyboardFocusManager that it should cancel delayed dispatching of KeyEvents.
protected abstract  void discardKeyEvents(Component comp)
          Called by the AWT to notify the KeyboardFocusManager that it should cancel delayed dispatching of KeyEvents.
abstract  boolean dispatchEvent(AWTEvent e)
          This method is called by the AWT event dispatcher requesting that the current KeyboardFocusManager dispatch the specified event on its behalf.
abstract  boolean dispatchKeyEvent(KeyEvent e)
          Typically this method will be called by dispatchEvent if no other KeyEventDispatcher in the dispatcher chain dispatched the KeyEvent, or if no other KeyEventDispatchers are registered.
 void downFocusCycle()
          Moves the focus down one focus traversal cycle from the current focus owner, if and only if the current focus owner is a Container that is a focus cycle root.
abstract  void downFocusCycle(Container aContainer)
          Moves the focus down one focus traversal cycle.
protected abstract  void enqueueKeyEvents(long after, Component untilFocused)
          Called by the AWT to notify the KeyboardFocusManager that it should delay dispatching of KeyEvents until the specified Component becomes the focus owner.
protected  void firePropertyChange(String propertyName, Object oldValue, Object newValue)
          Fires a PropertyChangeEvent in response to a change in a bound property.
protected  void fireVetoableChange(String propertyName, Object oldValue, Object newValue)
          Fires a PropertyChangeEvent in response to a change in a vetoable property.
private static boolean focusedWindowChanged(Component a, Component b)
           
 void focusNextComponent()
          Focuses the Component after the current focus owner.
abstract  void focusNextComponent(Component aComponent)
          Focuses the Component after aComponent, typically based on a FocusTraversalPolicy.
 void focusPreviousComponent()
          Focuses the Component before the current focus owner.
abstract  void focusPreviousComponent(Component aComponent)
          Focuses the Component before aComponent, typically based on a FocusTraversalPolicy.
 Window getActiveWindow()
          Returns the active Window, if the active Window is in the same context as the calling thread.
(package private) static Window getContainingWindow(Component comp)
           
 Container getCurrentFocusCycleRoot()
          Returns the current focus cycle root, if the current focus cycle root is in the same context as the calling thread.
static KeyboardFocusManager getCurrentKeyboardFocusManager()
          Returns the current KeyboardFocusManager instance for the calling thread's context.
(package private) static KeyboardFocusManager getCurrentKeyboardFocusManager(sun.awt.AppContext appcontext)
           
(package private)  SequencedEvent getCurrentSequencedEvent()
           
(package private)  Component getCurrentWaitingRequest(Component parent)
           
 Set getDefaultFocusTraversalKeys(int id)
          Returns a Set of default focus traversal keys for a given traversal operation.
 FocusTraversalPolicy getDefaultFocusTraversalPolicy()
          Returns the default FocusTraversalPolicy.
 Window getFocusedWindow()
          Returns the focused Window, if the focused Window is in the same context as the calling thread.
 Component getFocusOwner()
          Returns the focus owner, if the focus owner is in the same context as the calling thread.
protected  Window getGlobalActiveWindow()
          Returns the active Window, even if the calling thread is in a different context than the active Window.
protected  Container getGlobalCurrentFocusCycleRoot()
          Returns the current focus cycle root, even if the calling thread is in a different context than the current focus cycle root.
protected  Window getGlobalFocusedWindow()
          Returns the focused Window, even if the calling thread is in a different context than the focused Window.
protected  Component getGlobalFocusOwner()
          Returns the focus owner, even if the calling thread is in a different context than the focus owner.
protected  Component getGlobalPermanentFocusOwner()
          Returns the permanent focus owner, even if the calling thread is in a different context than the permanent focus owner.
private static Component getHeavyweight(Component comp)
           
protected  List getKeyEventDispatchers()
          Returns this KeyboardFocusManager's KeyEventDispatcher chain as a List.
protected  List getKeyEventPostProcessors()
          Returns this KeyboardFocusManager's KeyEventPostProcessor chain as a List.
(package private) static Component getMostRecentFocusOwner(Window window)
           
(package private) static Window getNativeFocusedWindow()
           
(package private) static Component getNativeFocusOwner()
           
 Component getPermanentFocusOwner()
          Returns the permanent focus owner, if the permanent focus owner is in the same context as the calling thread.
 java.beans.PropertyChangeListener[] getPropertyChangeListeners()
          Returns an array of all the property change listeners registered on this keyboard focus manager.
 java.beans.PropertyChangeListener[] getPropertyChangeListeners(String propertyName)
          Returns an array of all the PropertyChangeListeners associated with the named property.
 java.beans.VetoableChangeListener[] getVetoableChangeListeners()
          Returns an array of all the vetoable change listeners registered on this keyboard focus manager.
 java.beans.VetoableChangeListener[] getVetoableChangeListeners(String propertyName)
          Returns an array of all the VetoableChangeListeners associated with the named property.
(package private) static void heavyweightButtonDown(Component heavyweight, long time)
           
(package private) static void heavyweightButtonDown(Component heavyweight, long time, boolean acceptDuplicates)
           
(package private) static Set initFocusTraversalKeysSet(String value, Set targetSet)
           
private static void initIDs()
          Initialize JNI field and method IDs
(package private) static boolean isProxyActive(KeyEvent e)
           
private static boolean isProxyActiveImpl(KeyEvent e)
           
(package private) static Window markClearGlobalFocusOwner()
          Returns the Window which will be active after processing this request, or null if this is a duplicate request.
abstract  boolean postProcessKeyEvent(KeyEvent e)
          This method will be called by dispatchKeyEvent.
(package private) static void processCurrentLightweightRequests()
           
abstract  void processKeyEvent(Component focusedComponent, KeyEvent e)
          This method initiates a focus traversal operation if and only if the KeyEvent represents a focus traversal key for the specified focusedComponent.
(package private) static boolean processSynchronousLightweightTransfer(Component heavyweight, Component descendant, boolean temporary, boolean focusedWindowChangeAllowed, long time)
           
 void redispatchEvent(Component target, AWTEvent e)
          Redispatches an AWTEvent in such a way that the AWT event dispatcher will not recursively request that the KeyboardFocusManager, or any installed KeyEventDispatchers, dispatch the event again.
(package private) static boolean removeFirstRequest()
           
(package private) static void removeFocusRequest(Component component)
           
 void removeKeyEventDispatcher(KeyEventDispatcher dispatcher)
          Removes a KeyEventDispatcher which was previously added to this KeyboardFocusManager's dispatcher chain.
 void removeKeyEventPostProcessor(KeyEventPostProcessor processor)
          Removes a previously added KeyEventPostProcessor from this KeyboardFocusManager's post-processor chain.
(package private) static void removeLastFocusRequest(Component heavyweight)
           
 void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
          Removes a PropertyChangeListener from the listener list.
 void removePropertyChangeListener(String propertyName, java.beans.PropertyChangeListener listener)
          Removes a PropertyChangeListener from the listener list for a specific property.
 void removeVetoableChangeListener(String propertyName, java.beans.VetoableChangeListener listener)
          Removes a VetoableChangeListener from the listener list for a specific property.
 void removeVetoableChangeListener(java.beans.VetoableChangeListener listener)
          Removes a VetoableChangeListener from the listener list.
(package private)  int requestCount()
           
(package private) static AWTEvent retargetFocusEvent(AWTEvent event)
           
(package private) static FocusEvent retargetFocusGained(FocusEvent fe)
           
(package private) static FocusEvent retargetFocusLost(FocusEvent fe)
           
(package private) static FocusEvent retargetUnexpectedFocusEvent(FocusEvent fe)
           
static void setCurrentKeyboardFocusManager(KeyboardFocusManager newManager)
          Sets the current KeyboardFocusManager instance for the calling thread's context.
(package private)  void setCurrentSequencedEvent(SequencedEvent current)
           
 void setDefaultFocusTraversalKeys(int id, Set keystrokes)
          Sets the default focus traversal keys for a given traversal operation.
 void setDefaultFocusTraversalPolicy(FocusTraversalPolicy defaultPolicy)
          Sets the default FocusTraversalPolicy.
protected  void setGlobalActiveWindow(Window activeWindow)
          Sets the active Window.
 void setGlobalCurrentFocusCycleRoot(Container newFocusCycleRoot)
          Sets the current focus cycle root.
protected  void setGlobalFocusedWindow(Window focusedWindow)
          Sets the focused Window.
protected  void setGlobalFocusOwner(Component focusOwner)
          Sets the focus owner.
protected  void setGlobalPermanentFocusOwner(Component permanentFocusOwner)
          Sets the permanent focus owner.
(package private) static void setMostRecentFocusOwner(Component component)
           
(package private) static void setMostRecentFocusOwner(Window window, Component component)
           
(package private) static int shouldNativelyFocusHeavyweight(Component heavyweight, Component descendant, boolean temporary, boolean focusedWindowChangeAllowed, long time)
          Indicates whether the native implementation should proceed with a pending, native focus request.
 void upFocusCycle()
          Moves the focus up one focus traversal cycle from the current focus owner.
abstract  void upFocusCycle(Component aComponent)
          Moves the focus up one focus traversal cycle.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

dbg

private static final sun.awt.DebugHelper dbg

FORWARD_TRAVERSAL_KEYS

public static final int FORWARD_TRAVERSAL_KEYS
The identifier for the Forward focus traversal keys.

See Also:
setDefaultFocusTraversalKeys(int, java.util.Set), getDefaultFocusTraversalKeys(int), Component.setFocusTraversalKeys(int, java.util.Set), Component.getFocusTraversalKeys(int), Constant Field Values

BACKWARD_TRAVERSAL_KEYS

public static final int BACKWARD_TRAVERSAL_KEYS
The identifier for the Backward focus traversal keys.

See Also:
setDefaultFocusTraversalKeys(int, java.util.Set), getDefaultFocusTraversalKeys(int), Component.setFocusTraversalKeys(int, java.util.Set), Component.getFocusTraversalKeys(int), Constant Field Values

UP_CYCLE_TRAVERSAL_KEYS

public static final int UP_CYCLE_TRAVERSAL_KEYS
The identifier for the Up Cycle focus traversal keys.

See Also:
setDefaultFocusTraversalKeys(int, java.util.Set), getDefaultFocusTraversalKeys(int), Component.setFocusTraversalKeys(int, java.util.Set), Component.getFocusTraversalKeys(int), Constant Field Values

DOWN_CYCLE_TRAVERSAL_KEYS

public static final int DOWN_CYCLE_TRAVERSAL_KEYS
The identifier for the Down Cycle focus traversal keys.

See Also:
setDefaultFocusTraversalKeys(int, java.util.Set), getDefaultFocusTraversalKeys(int), Component.setFocusTraversalKeys(int, java.util.Set), Component.getFocusTraversalKeys(int), Constant Field Values

TRAVERSAL_KEY_LENGTH

static final int TRAVERSAL_KEY_LENGTH
See Also:
Constant Field Values

focusOwner

private static Component focusOwner
The Component in an application that will typically receive all KeyEvents generated by the user.


permanentFocusOwner

private static Component permanentFocusOwner
The Component in an application that will regain focus when an outstanding temporary focus transfer has completed, or the focus owner, if no outstanding temporary transfer exists.


focusedWindow

private static Window focusedWindow
The Window which is, or contains, the focus owner.


activeWindow

private static Window activeWindow
Only a Frame or a Dialog can be the active Window. The native windowing system may denote the active Window with a special decoration, such as a highlighted title bar. The active Window is always either the focused Window, or the first Frame or Dialog which is an owner of the focused Window.


defaultPolicy

private FocusTraversalPolicy defaultPolicy
The default FocusTraversalPolicy for all Windows that have no policy of their own set. If those Windows have focus-cycle-root children that have no keyboard-traversal policy of their own, then those children will also inherit this policy (as will, recursively, their focus-cycle-root children).


defaultFocusTraversalKeyPropertyNames

private static final String[] defaultFocusTraversalKeyPropertyNames
The bound property names of each focus traversal key.


defaultFocusTraversalKeyStrings

private static final String[] defaultFocusTraversalKeyStrings
The default Strings for initializing the default focus traversal keys. Only used if default traversal keys are not set using Preferences API.


defaultFocusTraversalKeys

private Set[] defaultFocusTraversalKeys
The default focus traversal keys. Each array of traversal keys will be in effect on all Windows that have no such array of their own explicitly set. Each array will also be inherited, recursively, by any child Component of those Windows that has no such array of its own explicitly set.


currentFocusCycleRoot

private static Container currentFocusCycleRoot
The current focus cycle root. If the focus owner is itself a focus cycle root, then it may be ambiguous as to which Components represent the next and previous Components to focus during normal focus traversal. In that case, the current focus cycle root is used to differentiate among the possibilities.


vetoableSupport

private java.beans.VetoableChangeSupport vetoableSupport
A description of any VetoableChangeListeners which have been registered.


changeSupport

private java.beans.PropertyChangeSupport changeSupport
A description of any PropertyChangeListeners which have been registered.


keyEventDispatchers

private LinkedList keyEventDispatchers
This KeyboardFocusManager's KeyEventDispatcher chain. The List does not include this KeyboardFocusManager unless it was explicitly re-registered via a call to addKeyEventDispatcher. If no other KeyEventDispatchers are registered, this field may be null or refer to a List of length 0.


keyEventPostProcessors

private LinkedList keyEventPostProcessors
This KeyboardFocusManager's KeyEventPostProcessor chain. The List does not include this KeyboardFocusManager unless it was explicitly re-registered via a call to addKeyEventPostProcessor. If no other KeyEventPostProcessors are registered, this field may be null or refer to a List of length 0.


mostRecentFocusOwners

private static Map mostRecentFocusOwners
Maps Windows to those Windows' most recent focus owners.


notPrivileged

private static final String notPrivileged
Error String for initializing SecurityExceptions.

See Also:
Constant Field Values

replaceKeyboardFocusManagerPermission

private static AWTPermission replaceKeyboardFocusManagerPermission
We cache the permission used to verify that the calling thread is permitted to access the global focus state.


currentSequencedEvent

transient SequencedEvent currentSequencedEvent

heavyweightRequests

private static LinkedList heavyweightRequests

currentLightweightRequests

private static LinkedList currentLightweightRequests

clearingCurrentLightweightRequests

private static boolean clearingCurrentLightweightRequests

newFocusOwner

private static Component newFocusOwner

SNFH_FAILURE

static final int SNFH_FAILURE
See Also:
Constant Field Values

SNFH_SUCCESS_HANDLED

static final int SNFH_SUCCESS_HANDLED
See Also:
Constant Field Values

SNFH_SUCCESS_PROCEED

static final int SNFH_SUCCESS_PROCEED
See Also:
Constant Field Values
Constructor Detail

KeyboardFocusManager

public KeyboardFocusManager()
Initializes a KeyboardFocusManager.

Method Detail

initIDs

private static void initIDs()
Initialize JNI field and method IDs


getCurrentKeyboardFocusManager

public static KeyboardFocusManager getCurrentKeyboardFocusManager()
Returns the current KeyboardFocusManager instance for the calling thread's context.

Returns:
this thread's context's KeyboardFocusManager
See Also:
setCurrentKeyboardFocusManager(java.awt.KeyboardFocusManager)

getCurrentKeyboardFocusManager

static KeyboardFocusManager getCurrentKeyboardFocusManager(sun.awt.AppContext appcontext)

setCurrentKeyboardFocusManager

public static void setCurrentKeyboardFocusManager(KeyboardFocusManager newManager)
                                           throws SecurityException
Sets the current KeyboardFocusManager instance for the calling thread's context. If null is specified, then the current KeyboardFocusManager is replaced with a new instance of DefaultKeyboardFocusManager.

If a SecurityManager is installed, the calling thread must be granted the AWTPermission "replaceKeyboardFocusManager" in order to replace the the current KeyboardFocusManager. If this permission is not granted, this method will throw a SecurityException, and the current KeyboardFocusManager will be unchanged.

Parameters:
newManager - the new KeyboardFocusManager for this thread's context
Throws:
SecurityException - if the calling thread does not have permission to replace the current KeyboardFocusManager
See Also:
getCurrentKeyboardFocusManager(), DefaultKeyboardFocusManager

setCurrentSequencedEvent

final void setCurrentSequencedEvent(SequencedEvent current)

getCurrentSequencedEvent

final SequencedEvent getCurrentSequencedEvent()

initFocusTraversalKeysSet

static Set initFocusTraversalKeysSet(String value,
                                     Set targetSet)

getFocusOwner

public Component getFocusOwner()
Returns the focus owner, if the focus owner is in the same context as the calling thread. The focus owner is defined as the Component in an application that will typically receive all KeyEvents generated by the user. KeyEvents which map to the focus owner's focus traversal keys will not be delivered if focus traversal keys are enabled for the focus owner. In addition, KeyEventDispatchers may retarget or consume KeyEvents before they reach the focus owner.

Returns:
the focus owner, or null if the focus owner is not a member of the calling thread's context
See Also:
getGlobalFocusOwner(), setGlobalFocusOwner(java.awt.Component)

getGlobalFocusOwner

protected Component getGlobalFocusOwner()
                                 throws SecurityException
Returns the focus owner, even if the calling thread is in a different context than the focus owner. The focus owner is defined as the Component in an application that will typically receive all KeyEvents generated by the user. KeyEvents which map to the focus owner's focus traversal keys will not be delivered if focus traversal keys are enabled for the focus owner. In addition, KeyEventDispatchers may retarget or consume KeyEvents before they reach the focus owner.

This method will throw a SecurityException if this KeyboardFocusManager is not the current KeyboardFocusManager for the calling thread's context.

Returns:
the focus owner
Throws:
SecurityException - if this KeyboardFocusManager is not the current KeyboardFocusManager for the calling thread's context
See Also:
getFocusOwner(), setGlobalFocusOwner(java.awt.Component)

setGlobalFocusOwner

protected void setGlobalFocusOwner(Component focusOwner)
Sets the focus owner. The operation will be cancelled if the Component is not focusable. The focus owner is defined as the Component in an application that will typically receive all KeyEvents generated by the user. KeyEvents which map to the focus owner's focus traversal keys will not be delivered if focus traversal keys are enabled for the focus owner. In addition, KeyEventDispatchers may retarget or consume KeyEvents before they reach the focus owner.

This method does not actually set the focus to the specified Component. It merely stores the value to be subsequently returned by getFocusOwner(). Use Component.requestFocus() or Component.requestFocusInWindow() to change the focus owner, subject to platform limitations.

Parameters:
focusOwner - the focus owner
See Also:
getFocusOwner(), getGlobalFocusOwner(), Component.requestFocus(), Component.requestFocusInWindow(), Component.isFocusable()

clearGlobalFocusOwner

public void clearGlobalFocusOwner()
Clears the global focus owner at both the Java and native levels. If there exists a focus owner, that Component will receive a permanent FOCUS_LOST event. After this operation completes, the native windowing system will discard all user-generated KeyEvents until the user selects a new Component to receive focus, or a Component is given focus explicitly via a call to requestFocus(). This operation does not change the focused or active Windows.

See Also:
Component.requestFocus(), FocusEvent.FOCUS_LOST

_clearGlobalFocusOwner

private void _clearGlobalFocusOwner()

getNativeFocusOwner

static Component getNativeFocusOwner()

getNativeFocusedWindow

static Window getNativeFocusedWindow()

getPermanentFocusOwner

public Component getPermanentFocusOwner()
Returns the permanent focus owner, if the permanent focus owner is in the same context as the calling thread. The permanent focus owner is defined as the last Component in an application to receive a permanent FOCUS_GAINED event. The focus owner and permanent focus owner are equivalent unless a temporary focus change is currently in effect. In such a situation, the permanent focus owner will again be the focus owner when the temporary focus change ends.

Returns:
the permanent focus owner, or null if the permanent focus owner is not a member of the calling thread's context
See Also:
getGlobalPermanentFocusOwner(), setGlobalPermanentFocusOwner(java.awt.Component)

getGlobalPermanentFocusOwner

protected Component getGlobalPermanentFocusOwner()
                                          throws SecurityException
Returns the permanent focus owner, even if the calling thread is in a different context than the permanent focus owner. The permanent focus owner is defined as the last Component in an application to receive a permanent FOCUS_GAINED event. The focus owner and permanent focus owner are equivalent unless a temporary focus change is currently in effect. In such a situation, the permanent focus owner will again be the focus owner when the temporary focus change ends.

This method will throw a SecurityException if this KeyboardFocusManager is not the current KeyboardFocusManager for the calling thread's context.

Returns:
the permanent focus owner
Throws:
SecurityException - if this KeyboardFocusManager is not the current KeyboardFocusManager for the calling thread's context
See Also:
getPermanentFocusOwner(), setGlobalPermanentFocusOwner(java.awt.Component)

setGlobalPermanentFocusOwner

protected void setGlobalPermanentFocusOwner(Component permanentFocusOwner)
Sets the permanent focus owner. The operation will be cancelled if the Component is not focusable. The permanent focus owner is defined as the last Component in an application to receive a permanent FOCUS_GAINED event. The focus owner and permanent focus owner are equivalent unless a temporary focus change is currently in effect. In such a situation, the permanent focus owner will again be the focus owner when the temporary focus change ends.

This method does not actually set the focus to the specified Component. It merely stores the value to be subsequently returned by getPermanentFocusOwner(). Use Component.requestFocus() or Component.requestFocusInWindow() to change the focus owner, subject to platform limitations.

Parameters:
permanentFocusOwner - the permanent focus owner
See Also:
getPermanentFocusOwner(), getGlobalPermanentFocusOwner(), Component.requestFocus(), Component.requestFocusInWindow(), Component.isFocusable()

getFocusedWindow

public Window getFocusedWindow()
Returns the focused Window, if the focused Window is in the same context as the calling thread. The focused Window is the Window that is or contains the focus owner.

Returns:
the focused Window, or null if the focused Window is not a member of the calling thread's context
See Also:
getGlobalFocusedWindow(), setGlobalFocusedWindow(java.awt.Window)

getGlobalFocusedWindow

protected Window getGlobalFocusedWindow()
                                 throws SecurityException
Returns the focused Window, even if the calling thread is in a different context than the focused Window. The focused Window is the Window that is or contains the focus owner.

This method will throw a SecurityException if this KeyboardFocusManager is not the current KeyboardFocusManager for the calling thread's context.

Returns:
the focused Window
Throws:
SecurityException - if this KeyboardFocusManager is not the current KeyboardFocusManager for the calling thread's context
See Also:
getFocusedWindow(), setGlobalFocusedWindow(java.awt.Window)

setGlobalFocusedWindow

protected void setGlobalFocusedWindow(Window focusedWindow)
Sets the focused Window. The focused Window is the Window that is or contains the focus owner. The operation will be cancelled if the specified Window to focus is not a focusable Window.

This method does not actually change the focused Window as far as the native windowing system is concerned. It merely stores the value to be subsequently returned by getFocusedWindow(). Use Component.requestFocus() or Component.requestFocusInWindow() to change the focused Window, subject to platform limitations.

Parameters:
focusedWindow - the focused Window
See Also:
getFocusedWindow(), getGlobalFocusedWindow(), Component.requestFocus(), Component.requestFocusInWindow(), Window.isFocusableWindow()

getActiveWindow

public Window getActiveWindow()
Returns the active Window, if the active Window is in the same context as the calling thread. Only a Frame or a Dialog can be the active Window. The native windowing system may denote the active Window or its children with special decorations, such as a highlighted title bar. The active Window is always either the focused Window, or the first Frame or Dialog that is an owner of the focused Window.

Returns:
the active Window, or null if the active Window is not a member of the calling thread's context
See Also:
getGlobalActiveWindow(), setGlobalActiveWindow(java.awt.Window)

getGlobalActiveWindow

protected Window getGlobalActiveWindow()
                                throws SecurityException
Returns the active Window, even if the calling thread is in a different context than the active Window. Only a Frame or a Dialog can be the active Window. The native windowing system may denote the active Window or its children with special decorations, such as a highlighted title bar. The active Window is always either the focused Window, or the first Frame or Dialog that is an owner of the focused Window.

This method will throw a SecurityException if this KeyboardFocusManager is not the current KeyboardFocusManager for the calling thread's context.

Returns:
the active Window
Throws:
SecurityException - if this KeyboardFocusManager is not the current KeyboardFocusManager for the calling thread's context
See Also:
getActiveWindow(), setGlobalActiveWindow(java.awt.Window)

setGlobalActiveWindow

protected void setGlobalActiveWindow(Window activeWindow)
Sets the active Window. Only a Frame or a Dialog can be the active Window. The native windowing system may denote the active Window or its children with special decorations, such as a highlighted title bar. The active Window is always either the focused Window, or the first Frame or Dialog that is an owner of the focused Window.

This method does not actually change the active Window as far as the native windowing system is concerned. It merely stores the value to be subsequently returned by getActiveWindow(). Use Component.requestFocus() or Component.requestFocusInWindow()to change the active Window, subject to platform limitations.

Parameters:
activeWindow - the active Window
See Also:
getActiveWindow(), getGlobalActiveWindow(), Component.requestFocus(), Component.requestFocusInWindow()

getDefaultFocusTraversalPolicy

public FocusTraversalPolicy getDefaultFocusTraversalPolicy()
Returns the default FocusTraversalPolicy. Top-level components use this value on their creation to initialize their own focus traversal policy by explicit call to Container.setFocusTraversalPolicy.

Returns:
the default FocusTraversalPolicy. null will never be returned.
See Also:
setDefaultFocusTraversalPolicy(java.awt.FocusTraversalPolicy), Container.setFocusTraversalPolicy(java.awt.FocusTraversalPolicy), Container.getFocusTraversalPolicy()

setDefaultFocusTraversalPolicy

public void setDefaultFocusTraversalPolicy(FocusTraversalPolicy defaultPolicy)
Sets the default FocusTraversalPolicy. Top-level components use this value on their creation to initialize their own focus traversal policy by explicit call to Container.setFocusTraversalPolicy. Note: this call doesn't affect already created components as they have their policy initialized. Only new components will use this policy as their default policy.

Parameters:
defaultPolicy - the new, default FocusTraversalPolicy
Throws:
IllegalArgumentException - if defaultPolicy is null
See Also:
getDefaultFocusTraversalPolicy(), Container.setFocusTraversalPolicy(java.awt.FocusTraversalPolicy), Container.getFocusTraversalPolicy()

setDefaultFocusTraversalKeys

public void setDefaultFocusTraversalKeys(int id,
                                         Set keystrokes)
Sets the default focus traversal keys for a given traversal operation. This traversal key Set will be in effect on all Windows that have no such Set of their own explicitly defined. This Set will also be inherited, recursively, by any child Component of those Windows that has no such Set of its own explicitly defined.

The default values for the default focus traversal keys are implementation-dependent. Sun recommends that all implementations for a particular native platform use the same default values. The recommendations for Windows and Unix are listed below. These recommendations are used in the Sun AWT implementations.

Identifier Meaning Default
KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS Normal forward keyboard traversal TAB on KEY_PRESSED, CTRL-TAB on KEY_PRESSED
KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS Normal reverse keyboard traversal SHIFT-TAB on KEY_PRESSED, CTRL-SHIFT-TAB on KEY_PRESSED
KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS Go up one focus traversal cycle none
KeyboardFocusManager.DOWN_CYCLE_TRAVERSAL_KEYS Go down one focus traversal cycle none
To disable a traversal key, use an empty Set; Collections.EMPTY_SET is recommended.

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 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, or to map the same event to multiple default focus traversal operations.

Parameters:
id - one of KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS, KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS, KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS, or KeyboardFocusManager.DOWN_CYCLE_TRAVERSAL_KEYS
keystrokes - the Set of AWTKeyStrokes for the specified operation
Throws:
IllegalArgumentException - if id is not one of KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS, KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS, KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS, or KeyboardFocusManager.DOWN_CYCLE_TRAVERSAL_KEYS, or if keystrokes is null, or if keystrokes contains null, or if any Object in keystrokes is not an AWTKeyStroke, or if any keystroke represents a KEY_TYPED event, or if any keystroke already maps to another default focus traversal operation
See Also:
getDefaultFocusTraversalKeys(int), Component.setFocusTraversalKeys(int, java.util.Set), Component.getFocusTraversalKeys(int)

getDefaultFocusTraversalKeys

public Set getDefaultFocusTraversalKeys(int id)
Returns a Set of default focus traversal keys for a given traversal operation. This traversal key Set will be in effect on all Windows that have no such Set of their own explicitly defined. This Set will also be inherited, recursively, by any child Component of those Windows that has no such Set of its own explicitly defined. (See setDefaultFocusTraversalKeys for a full description of each operation.)

Parameters:
id - one of KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS, KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS, KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS, or KeyboardFocusManager.DOWN_CYCLE_TRAVERSAL_KEYS
Returns:
the Set of AWTKeyStrokes for the specified operation; the Set will be unmodifiable, and may be empty; null will never be returned
Throws:
IllegalArgumentException - if id is not one of KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS, KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS, KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS, or KeyboardFocusManager.DOWN_CYCLE_TRAVERSAL_KEYS
See Also:
setDefaultFocusTraversalKeys(int, java.util.Set), Component.setFocusTraversalKeys(int, java.util.Set), Component.getFocusTraversalKeys(int)

getCurrentFocusCycleRoot

public Container getCurrentFocusCycleRoot()
Returns the current focus cycle root, if the current focus cycle root is in the same context as the calling thread. If the focus owner is itself a focus cycle root, then it may be ambiguous as to which Components represent the next and previous Components to focus during normal focus traversal. In that case, the current focus cycle root is used to differentiate among the possibilities.

This method is intended to be used only by KeyboardFocusManagers and focus implementations. It is not for general client use.

Returns:
the current focus cycle root, or null if the current focus cycle root is not a member of the calling thread's context
See Also:
getGlobalCurrentFocusCycleRoot(), setGlobalCurrentFocusCycleRoot(java.awt.Container)

getGlobalCurrentFocusCycleRoot

protected Container getGlobalCurrentFocusCycleRoot()
                                            throws SecurityException
Returns the current focus cycle root, even if the calling thread is in a different context than the current focus cycle root. If the focus owner is itself a focus cycle root, then it may be ambiguous as to which Components represent the next and previous Components to focus during normal focus traversal. In that case, the current focus cycle root is used to differentiate among the possibilities.

This method will throw a SecurityException if this KeyboardFocusManager is not the current KeyboardFocusManager for the calling thread's context.

Returns:
the current focus cycle root, or null if the current focus cycle root is not a member of the calling thread's context
Throws:
SecurityException - if this KeyboardFocusManager is not the current KeyboardFocusManager for the calling thread's context
See Also:
getCurrentFocusCycleRoot(), setGlobalCurrentFocusCycleRoot(java.awt.Container)

setGlobalCurrentFocusCycleRoot

public void setGlobalCurrentFocusCycleRoot(Container newFocusCycleRoot)
Sets the current focus cycle root. If the focus owner is itself a focus cycle root, then it may be ambiguous as to which Components represent the next and previous Components to focus during normal focus traversal. In that case, the current focus cycle root is used to differentiate among the possibilities.

This method is intended to be used only by KeyboardFocusManagers and focus implementations. It is not for general client use.

Parameters:
newFocusCycleRoot - the new focus cycle root
See Also:
getCurrentFocusCycleRoot(), getGlobalCurrentFocusCycleRoot()

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
Adds a PropertyChangeListener to the listener list. The listener is registered for all bound properties of this class, including the following: If listener is null, no exception is thrown and no action is performed.

Parameters:
listener - the PropertyChangeListener to be added
See Also:
removePropertyChangeListener(java.beans.PropertyChangeListener), getPropertyChangeListeners(), addPropertyChangeListener(java.lang.String,java.beans.PropertyChangeListener)

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
Removes a PropertyChangeListener from the listener list. This method should be used to remove the PropertyChangeListeners that were registered for all bound properties of this class.

If listener is null, no exception is thrown and no action is performed.

Parameters:
listener - the PropertyChangeListener to be removed
See Also:
addPropertyChangeListener(java.beans.PropertyChangeListener), getPropertyChangeListeners(), removePropertyChangeListener(java.lang.String,java.beans.PropertyChangeListener)

getPropertyChangeListeners

public java.beans.PropertyChangeListener[] getPropertyChangeListeners()
Returns an array of all the property change listeners registered on this keyboard focus manager.

Returns:
all of this keyboard focus manager's PropertyChangeListeners or an empty array if no property change listeners are currently registered
Since:
1.4
See Also:
addPropertyChangeListener(java.beans.PropertyChangeListener), removePropertyChangeListener(java.beans.PropertyChangeListener), getPropertyChangeListeners(java.lang.String)

addPropertyChangeListener

public void addPropertyChangeListener(String propertyName,
                                      java.beans.PropertyChangeListener listener)
Adds a PropertyChangeListener to the listener list for a specific property. The specified property may be user-defined, or one of the following: If listener is null, no exception is thrown and no action is performed.

Parameters:
propertyName - one of the property names listed above
listener - the PropertyChangeListener to be added
See Also:
addPropertyChangeListener(java.beans.PropertyChangeListener), removePropertyChangeListener(java.lang.String,java.beans.PropertyChangeListener), getPropertyChangeListeners(java.lang.String)

removePropertyChangeListener

public void removePropertyChangeListener(String propertyName,
                                         java.beans.PropertyChangeListener listener)
Removes a PropertyChangeListener from the listener list for a specific property. This method should be used to remove PropertyChangeListeners that were registered for a specific bound property.

If listener is null, no exception is thrown and no action is performed.

Parameters:
propertyName - a valid property name
listener - the PropertyChangeListener to be removed
See Also:
addPropertyChangeListener(java.lang.String,java.beans.PropertyChangeListener), getPropertyChangeListeners(java.lang.String), removePropertyChangeListener(java.beans.PropertyChangeListener)

getPropertyChangeListeners

public java.beans.PropertyChangeListener[] getPropertyChangeListeners(String propertyName)
Returns an array of all the PropertyChangeListeners associated with the named property.

Returns:
all of the PropertyChangeListeners associated with the named property or an empty array if no such listeners have been added.
Since:
1.4
See Also:
addPropertyChangeListener(java.lang.String,java.beans.PropertyChangeListener), removePropertyChangeListener(java.lang.String,java.beans.PropertyChangeListener)

firePropertyChange

protected void firePropertyChange(String propertyName,
                                  Object oldValue,
                                  Object newValue)
Fires a PropertyChangeEvent in response to a change in a bound property. The event will be delivered to all registered PropertyChangeListeners. No event will be delivered if oldValue and newValue are the same.

Parameters:
propertyName - the name of the property that has changed
oldValue - the property's previous value
newValue - the property's new value

addVetoableChangeListener

public void addVetoableChangeListener(java.beans.VetoableChangeListener listener)
Adds a VetoableChangeListener to the listener list. The listener is registered for all vetoable properties of this class, including the following: If listener is null, no exception is thrown and no action is performed.

Parameters:
listener - the VetoableChangeListener to be added
See Also:
removeVetoableChangeListener(java.beans.VetoableChangeListener), getVetoableChangeListeners(), addVetoableChangeListener(java.lang.String,java.beans.VetoableChangeListener)

removeVetoableChangeListener

public void removeVetoableChangeListener(java.beans.VetoableChangeListener listener)
Removes a VetoableChangeListener from the listener list. This method should be used to remove the VetoableChangeListeners that were registered for all vetoable properties of this class.

If listener is null, no exception is thrown and no action is performed.

Parameters:
listener - the VetoableChangeListener to be removed
See Also:
addVetoableChangeListener(java.beans.VetoableChangeListener), getVetoableChangeListeners(), removeVetoableChangeListener(java.lang.String,java.beans.VetoableChangeListener)

getVetoableChangeListeners

public java.beans.VetoableChangeListener[] getVetoableChangeListeners()
Returns an array of all the vetoable change listeners registered on this keyboard focus manager.

Returns:
all of this keyboard focus manager's VetoableChangeListeners or an empty array if no vetoable change listeners are currently registered
Since:
1.4
See Also:
addVetoableChangeListener(java.beans.VetoableChangeListener), removeVetoableChangeListener(java.beans.VetoableChangeListener), getVetoableChangeListeners(java.lang.String)

addVetoableChangeListener

public void addVetoableChangeListener(String propertyName,
                                      java.beans.VetoableChangeListener listener)
Adds a VetoableChangeListener to the listener list for a specific property. The specified property may be user-defined, or one of the following: If listener is null, no exception is thrown and no action is performed.

Parameters:
propertyName - one of the property names listed above
listener - the VetoableChangeListener to be added
See Also:
addVetoableChangeListener(java.beans.VetoableChangeListener), removeVetoableChangeListener(java.beans.VetoableChangeListener), getVetoableChangeListeners()

removeVetoableChangeListener

public void removeVetoableChangeListener(String propertyName,
                                         java.beans.VetoableChangeListener listener)
Removes a VetoableChangeListener from the listener list for a specific property. This method should be used to remove VetoableChangeListeners that were registered for a specific bound property.

If listener is null, no exception is thrown and no action is performed.

Parameters:
propertyName - a valid property name
listener - the VetoableChangeListener to be removed
See Also:
addVetoableChangeListener(java.beans.VetoableChangeListener), getVetoableChangeListeners(), removeVetoableChangeListener(java.beans.VetoableChangeListener)

getVetoableChangeListeners

public java.beans.VetoableChangeListener[] getVetoableChangeListeners(String propertyName)
Returns an array of all the VetoableChangeListeners associated with the named property.

Returns:
all of the VetoableChangeListeners associated with the named property or an empty array if no such listeners have been added.
Since:
1.4
See Also:
addVetoableChangeListener(java.lang.String,java.beans.VetoableChangeListener), removeVetoableChangeListener(java.lang.String,java.beans.VetoableChangeListener), getVetoableChangeListeners()

fireVetoableChange

protected void fireVetoableChange(String propertyName,
                                  Object oldValue,
                                  Object newValue)
                           throws java.beans.PropertyVetoException
Fires a PropertyChangeEvent in response to a change in a vetoable property. The event will be delivered to all registered VetoableChangeListeners. If a VetoableChangeListener throws a PropertyVetoException, a new event is fired reverting all VetoableChangeListeners to the old value and the exception is then rethrown. No event will be delivered if oldValue and newValue are the same.

Parameters:
propertyName - the name of the property that has changed
oldValue - the property's previous value
newValue - the property's new value
Throws:
java.beans.PropertyVetoException - if a VetoableChangeListener threw PropertyVetoException

addKeyEventDispatcher

public void addKeyEventDispatcher(KeyEventDispatcher dispatcher)
Adds a KeyEventDispatcher to this KeyboardFocusManager's dispatcher chain. This KeyboardFocusManager will request that each KeyEventDispatcher dispatch KeyEvents generated by the user before finally dispatching the KeyEvent itself. KeyEventDispatchers will be notified in the order in which they were added. Notifications will halt as soon as one KeyEventDispatcher returns true from its dispatchKeyEvent method. There is no limit to the total number of KeyEventDispatchers which can be added, nor to the number of times which a particular KeyEventDispatcher instance can be added.

If a null dispatcher is specified, no action is taken and no exception is thrown.

Parameters:
dispatcher - the KeyEventDispatcher to add to the dispatcher chain
See Also:
removeKeyEventDispatcher(java.awt.KeyEventDispatcher)

removeKeyEventDispatcher

public void removeKeyEventDispatcher(KeyEventDispatcher dispatcher)
Removes a KeyEventDispatcher which was previously added to this KeyboardFocusManager's dispatcher chain. This KeyboardFocusManager cannot itself be removed, unless it was explicitly re-registered via a call to addKeyEventDispatcher.

If a null dispatcher is specified, if the specified dispatcher is not in the dispatcher chain, or if this KeyboardFocusManager is specified without having been explicitly re-registered, no action is taken and no exception is thrown.

Parameters:
dispatcher - the KeyEventDispatcher to remove from the dispatcher chain
See Also:
addKeyEventDispatcher(java.awt.KeyEventDispatcher)

getKeyEventDispatchers

protected List getKeyEventDispatchers()
Returns this KeyboardFocusManager's KeyEventDispatcher chain as a List. The List will not include this KeyboardFocusManager unless it was explicitly re-registered via a call to addKeyEventDispatcher. If no other KeyEventDispatchers are registered, implementations are free to return null or a List of length 0. Client code should not assume one behavior over another, nor should it assume that the behavior, once established, will not change.

Returns:
a possibly null or empty List of KeyEventDispatchers
See Also:
addKeyEventDispatcher(java.awt.KeyEventDispatcher), removeKeyEventDispatcher(java.awt.KeyEventDispatcher)

addKeyEventPostProcessor

public void addKeyEventPostProcessor(KeyEventPostProcessor processor)
Adds a KeyEventPostProcessor to this KeyboardFocusManager's post- processor chain. After a KeyEvent has been dispatched to and handled by its target, KeyboardFocusManager will request that each KeyEventPostProcessor perform any necessary post-processing as part of the KeyEvent's final resolution. KeyEventPostProcessors will be notified in the order in which they were added; the current KeyboardFocusManager will be notified last. Notifications will halt as soon as one KeyEventPostProcessor returns true from its postProcessKeyEvent method. There is no limit to the the total number of KeyEventPostProcessors that can be added, nor to the number of times that a particular KeyEventPostProcessor instance can be added.

If a null post-processor is specified, no action is taken and no exception is thrown.

Parameters:
processor - the KeyEventPostProcessor to add to the post-processor chain
See Also:
removeKeyEventPostProcessor(java.awt.KeyEventPostProcessor)

removeKeyEventPostProcessor

public void removeKeyEventPostProcessor(KeyEventPostProcessor processor)
Removes a previously added KeyEventPostProcessor from this KeyboardFocusManager's post-processor chain. This KeyboardFocusManager cannot itself be entirely removed from the chain. Only additional references added via addKeyEventPostProcessor can be removed.

If a null post-processor is specified, if the specified post-processor is not in the post-processor chain, or if this KeyboardFocusManager is specified without having been explicitly added, no action is taken and no exception is thrown.

Parameters:
processor - the KeyEventPostProcessor to remove from the post- processor chain
See Also:
addKeyEventPostProcessor(java.awt.KeyEventPostProcessor)

getKeyEventPostProcessors

protected List getKeyEventPostProcessors()
Returns this KeyboardFocusManager's KeyEventPostProcessor chain as a List. The List will not include this KeyboardFocusManager unless it was explicitly added via a call to addKeyEventPostProcessor. If no KeyEventPostProcessors are registered, implementations are free to return null or a List of length 0. Client code should not assume one behavior over another, nor should it assume that the behavior, once established, will not change.

Returns:
a possibly null or empty List of KeyEventPostProcessors
See Also:
addKeyEventPostProcessor(java.awt.KeyEventPostProcessor), removeKeyEventPostProcessor(java.awt.KeyEventPostProcessor)

setMostRecentFocusOwner

static void setMostRecentFocusOwner(Component component)

setMostRecentFocusOwner

static void setMostRecentFocusOwner(Window window,
                                    Component component)

clearMostRecentFocusOwner

static void clearMostRecentFocusOwner(Component comp)

getMostRecentFocusOwner

static Component getMostRecentFocusOwner(Window window)

dispatchEvent

public abstract boolean dispatchEvent(AWTEvent e)
This method is called by the AWT event dispatcher requesting that the current KeyboardFocusManager dispatch the specified event on its behalf. It is expected that all KeyboardFocusManagers will dispatch all FocusEvents, all WindowEvents related to focus, and all KeyEvents. These events should be dispatched based on the KeyboardFocusManager's notion of the focus owner and the focused and active Windows, sometimes overriding the source of the specified AWTEvent. Dispatching must be done using redispatchEvent to prevent the AWT event dispatcher from recursively requesting that the KeyboardFocusManager dispatch the event again. If this method returns false, then the AWT event dispatcher will attempt to dispatch the event itself.

Parameters:
e - the AWTEvent to be dispatched
Returns:
true if this method dispatched the event; false otherwise
See Also:
redispatchEvent(java.awt.Component, java.awt.AWTEvent), dispatchKeyEvent(java.awt.event.KeyEvent)

redispatchEvent

public final void redispatchEvent(Component target,
                                  AWTEvent e)
Redispatches an AWTEvent in such a way that the AWT event dispatcher will not recursively request that the KeyboardFocusManager, or any installed KeyEventDispatchers, dispatch the event again. Client implementations of dispatchEvent and client-defined KeyEventDispatchers must call redispatchEvent(target, e) instead of target.dispatchEvent(e) to dispatch an event.

This method is intended to be used only by KeyboardFocusManagers and KeyEventDispatchers. It is not for general client use.

Parameters:
target - the Component to which the event should be dispatched
e - the event to dispatch
See Also:
dispatchEvent(java.awt.AWTEvent), KeyEventDispatcher

dispatchKeyEvent

public abstract boolean dispatchKeyEvent(KeyEvent e)
Typically this method will be called by dispatchEvent if no other KeyEventDispatcher in the dispatcher chain dispatched the KeyEvent, or if no other KeyEventDispatchers are registered. If an implementation of this method returns false, dispatchEvent may try to dispatch the KeyEvent itself, or may simply return false. If true is returned, dispatchEvent should return true as well.

Specified by:
dispatchKeyEvent in interface KeyEventDispatcher
Parameters:
e - the KeyEvent which the current KeyboardFocusManager has requested that this KeyEventDispatcher dispatch
Returns:
true if the KeyEvent was dispatched; false otherwise
See Also:
dispatchEvent(java.awt.AWTEvent)

postProcessKeyEvent

public abstract boolean postProcessKeyEvent(KeyEvent e)
This method will be called by dispatchKeyEvent. By default, this method will handle any unconsumed KeyEvents that map to an AWT MenuShortcut by consuming the event and activating the shortcut.

Specified by:
postProcessKeyEvent in interface KeyEventPostProcessor
Parameters:
e - the KeyEvent to post-process
Returns:
true to indicate that no other KeyEventPostProcessor will be notified of the KeyEvent.
See Also:
dispatchKeyEvent(java.awt.event.KeyEvent), MenuShortcut

processKeyEvent

public abstract void processKeyEvent(Component focusedComponent,
                                     KeyEvent e)
This method initiates a focus traversal operation if and only if the KeyEvent represents a focus traversal key for the specified focusedComponent. It is expected that focusedComponent is the current focus owner, although this need not be the case. If it is not, focus traversal will nevertheless proceed as if focusedComponent were the current focus owner.

Parameters:
focusedComponent - the Component that will be the basis for a focus traversal operation if the specified event represents a focus traversal key for the Component
e - the event that may represent a focus traversal key

enqueueKeyEvents

protected abstract void enqueueKeyEvents(long after,
                                         Component untilFocused)
Called by the AWT to notify the KeyboardFocusManager that it should delay dispatching of KeyEvents until the specified Component becomes the focus owner. If client code requests a focus change, and the AWT determines that this request might be granted by the native windowing system, then the AWT will call this method. It is the responsibility of the KeyboardFocusManager to delay dispatching of KeyEvents with timestamps later than the specified time stamp until the specified Component receives a FOCUS_GAINED event, or the AWT cancels the delay request by invoking dequeueKeyEvents or discardKeyEvents.

Parameters:
after - timestamp of current event, or the current, system time if the current event has no timestamp, or the AWT cannot determine which event is currently being handled
untilFocused - Component which should receive a FOCUS_GAINED event before any pending KeyEvents
See Also:
dequeueKeyEvents(long, java.awt.Component), discardKeyEvents(java.awt.Component)

dequeueKeyEvents

protected abstract void dequeueKeyEvents(long after,
                                         Component untilFocused)
Called by the AWT to notify the KeyboardFocusManager that it should cancel delayed dispatching of KeyEvents. All KeyEvents which were enqueued because of a call to enqueueKeyEvents with the same timestamp and Component should be released for normal dispatching to the current focus owner. If the given timestamp is less than zero, the outstanding enqueue request for the given Component with the oldest timestamp (if any) should be cancelled.

Parameters:
after - the timestamp specified in the call to enqueueKeyEvents, or any value < 0
untilFocused - the Component specified in the call to enqueueKeyEvents
See Also:
enqueueKeyEvents(long, java.awt.Component), discardKeyEvents(java.awt.Component)

discardKeyEvents

protected abstract void discardKeyEvents(Component comp)
Called by the AWT to notify the KeyboardFocusManager that it should cancel delayed dispatching of KeyEvents. All KeyEvents which were enqueued because of one or more calls to enqueueKeyEvents with the same Component should be discarded.

Parameters:
comp - the Component specified in one or more calls to enqueueKeyEvents
See Also:
enqueueKeyEvents(long, java.awt.Component), dequeueKeyEvents(long, java.awt.Component)

focusNextComponent

public abstract void focusNextComponent(Component aComponent)
Focuses the Component after aComponent, typically based on a FocusTraversalPolicy.

Parameters:
aComponent - the Component that is the basis for the focus traversal operation
See Also:
FocusTraversalPolicy

focusPreviousComponent

public abstract void focusPreviousComponent(Component aComponent)
Focuses the Component before aComponent, typically based on a FocusTraversalPolicy.

Parameters:
aComponent - the Component that is the basis for the focus traversal operation
See Also:
FocusTraversalPolicy

upFocusCycle

public abstract void upFocusCycle(Component aComponent)
Moves the focus up one focus traversal cycle. Typically, the focus owner is set to aComponent's focus cycle root, and the current focus cycle root is set to the new focus owner's focus cycle root. If, however, aComponent's focus cycle root is a Window, then typically the focus owner is set to the Window's default Component to focus, and the current focus cycle root is unchanged.

Parameters:
aComponent - the Component that is the basis for the focus traversal operation

downFocusCycle

public abstract void downFocusCycle(Container aContainer)
Moves the focus down one focus traversal cycle. Typically, if aContainer is a focus cycle root, then the focus owner is set to aContainer's default Component to focus, and the current focus cycle root is set to aContainer. If aContainer is not a focus cycle root, then no focus traversal operation occurs.

Parameters:
aContainer - the Container that is the basis for the focus traversal operation

focusNextComponent

public final void focusNextComponent()
Focuses the Component after the current focus owner.


focusPreviousComponent

public final void focusPreviousComponent()
Focuses the Component before the current focus owner.


upFocusCycle

public final void upFocusCycle()
Moves the focus up one focus traversal cycle from the current focus owner. Typically, the new focus owner is set to the current focus owner's focus cycle root, and the current focus cycle root is set to the new focus owner's focus cycle root. If, however, the current focus owner's focus cycle root is a Window, then typically the focus owner is set to the focus cycle root's default Component to focus, and the current focus cycle root is unchanged.


downFocusCycle

public final void downFocusCycle()
Moves the focus down one focus traversal cycle from the current focus owner, if and only if the current focus owner is a Container that is a focus cycle root. Typically, the focus owner is set to the current focus owner's default Component to focus, and the current focus cycle root is set to the current focus owner. If the current focus owner is not a Container that is a focus cycle root, then no focus traversal operation occurs.


requestCount

int requestCount()

processSynchronousLightweightTransfer

static boolean processSynchronousLightweightTransfer(Component heavyweight,
                                                     Component descendant,
                                                     boolean temporary,
                                                     boolean focusedWindowChangeAllowed,
                                                     long time)

shouldNativelyFocusHeavyweight

static int shouldNativelyFocusHeavyweight(Component heavyweight,
                                          Component descendant,
                                          boolean temporary,
                                          boolean focusedWindowChangeAllowed,
                                          long time)
Indicates whether the native implementation should proceed with a pending, native focus request. Before changing the focus at the native level, the AWT implementation should always call this function for permission. This function will reject the request if a duplicate request preceded it, or if the specified heavyweight Component already owns the focus and no native focus changes are pending. Otherwise, the request will be approved and the focus request list will be updated so that, if necessary, the proper descendant will be focused when the corresponding FOCUS_GAINED event on the heavyweight is received. An implementation must ensure that calls to this method and native focus changes are atomic. If this is not guaranteed, then the ordering of the focus request list may be incorrect, leading to errors in the type-ahead mechanism. Typically this is accomplished by only calling this function from the native event pumping thread, or by holding a global, native lock during invocation.


heavyweightButtonDown

static void heavyweightButtonDown(Component heavyweight,
                                  long time)

heavyweightButtonDown

static void heavyweightButtonDown(Component heavyweight,
                                  long time,
                                  boolean acceptDuplicates)

markClearGlobalFocusOwner

static Window markClearGlobalFocusOwner()
Returns the Window which will be active after processing this request, or null if this is a duplicate request. The active Window is useful because some native platforms do not support setting the native focus owner to null. On these platforms, the obvious choice is to set the focus owner to the focus proxy of the active Window.


getCurrentWaitingRequest

Component getCurrentWaitingRequest(Component parent)

processCurrentLightweightRequests

static void processCurrentLightweightRequests()

retargetUnexpectedFocusEvent

static FocusEvent retargetUnexpectedFocusEvent(FocusEvent fe)

retargetFocusGained

static FocusEvent retargetFocusGained(FocusEvent fe)

retargetFocusLost

static FocusEvent retargetFocusLost(FocusEvent fe)

retargetFocusEvent

static AWTEvent retargetFocusEvent(AWTEvent event)

removeFirstRequest

static boolean removeFirstRequest()

removeLastFocusRequest

static void removeLastFocusRequest(Component heavyweight)

removeFocusRequest

static void removeFocusRequest(Component component)

clearFocusRequestList

private static void clearFocusRequestList()

focusedWindowChanged

private static boolean focusedWindowChanged(Component a,
                                            Component b)

getContainingWindow

static Window getContainingWindow(Component comp)

getHeavyweight

private static Component getHeavyweight(Component comp)

isProxyActiveImpl

private static boolean isProxyActiveImpl(KeyEvent e)

isProxyActive

static boolean isProxyActive(KeyEvent e)