java.awt
Class KeyboardFocusManager

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

public abstract class KeyboardFocusManager
extends Object
implements KeyEventDispatcher, KeyEventPostProcessor

The KeyboardFocusManager handles the focusing of windows for receiving keyboard events. The manager handles the dispatch of all FocusEvents and KeyEvents, along with WindowEvents relating to the focused window. Users can use the manager to ascertain the current focus owner and fire events.

The focus owner is the Component that receives key events. The focus owner is either the currently focused window or a component within this window.

The underlying native windowing system may denote the active window or its children with special decorations (e.g. a highlighted title bar). The active window is always either a Frame or Dialog, and is either the currently focused window or its owner.

Applets may be partitioned into different applet contexts, according to their code base. In this case, each context has its own KeyboardFocusManager, as opposed to the global manager maintained by applets which share the same context. Each context is insulated from the others, and they don't interact. The resulting behaviour, as with context division, depends on the browser supporting the applets. Regardless, there can only ever be one focused window, one active window and one focus owner per ClassLoader.

To support this separation of focus managers, the manager instances and the internal state information is grouped by the ThreadGroup to which it pertains. With respect to applets, each code base has its own ThreadGroup, so the isolation of each context is enforced within the manager.

By default, the manager defines TAB and Ctrl+TAB as the forward focus traversal keys and Shift+TAB and Ctrl+Shift+TAB as the backward focus traversal keys. No up or down cycle traversal keys are defined by default. Traversal takes effect on the firing of a relevant KEY_PRESSED event. However, all other key events related to the use of the defined focus traversal key sequence are consumed and not dispatched.

These default traversal keys come into effect on all windows for which no alternative set of keys is defined. This also applies recursively to any child components of such a window, which define no traversal keys of their own.

Since:
1.4

Field Summary
static int BACKWARD_TRAVERSAL_KEYS
          Identifies AWTKeyStrokes that move the focus backward in the focus cycle.
static int DOWN_CYCLE_TRAVERSAL_KEYS
          Identifies AWTKeyStrokes that move the focus down to the child focus cycle root.
static int FORWARD_TRAVERSAL_KEYS
          Identifies AWTKeyStrokes that move the focus forward in the focus cycle.
static int UP_CYCLE_TRAVERSAL_KEYS
          Identifies AWTKeyStrokes that move the focus up to the parent focus cycle root.
 
Constructor Summary
KeyboardFocusManager()
          Construct a KeyboardFocusManager.
 
Method Summary
 void addKeyEventDispatcher(KeyEventDispatcher dispatcher)
          Adds a key event dispatcher to the list of registered dispatchers.
 void addKeyEventPostProcessor(KeyEventPostProcessor postProcessor)
          Adds a key event post processor to the list of registered post processors.
 void addPropertyChangeListener(PropertyChangeListener l)
          Registers the supplied property change listener for receiving events caused by the following property changes: the current focus owner ("focusOwner") the permanent focus owner ("permanentFocusOwner") the focused window ("focusedWindow") the active window ("activeWindow") the default focus traversal policy ("defaultFocusTraversalPolicy") the default set of forward traversal keys ("forwardDefaultFocusTraversalKeys") the default set of backward traversal keys ("backwardDefaultFocusTraversalKeys") the default set of up cycle traversal keys ("upCycleDefaultFocusTraversalKeys") the default set of down cycle traversal keys ("downCycleDefaultFocusTraversalKeys") the current focus cycle root ("currentFocusCycleRoot") If the supplied listener is null, nothing occurs.
 void addPropertyChangeListener(String name, PropertyChangeListener l)
          Registers a property change listener for receiving events relating to a change to a specified property.
 void addVetoableChangeListener(String name, VetoableChangeListener l)
          Registers a vetoable property change listener for receiving events relating to a vetoable change to a specified property.
 void addVetoableChangeListener(VetoableChangeListener l)
          Registers a vetoable property change listener for receiving events relating to the following properties: the current focus owner ("focusOwner") the permanent focus owner ("permanentFocusOwner") the focused window ("focusedWindow") the active window ("activeWindow") Nothing occurs if a null listener is supplied.
 void clearGlobalFocusOwner()
          Clear the global focus owner and deliver a FOCUS_LOST event to the previously-focused Component.
protected abstract  void dequeueKeyEvents(long after, Component untilFocused)
          Removes the key event block specified by the supplied timestamp and component.
protected abstract  void discardKeyEvents(Component comp)
          Discards all key event blocks relating to focus requirements for the supplied component, regardless of timestamp.
abstract  boolean dispatchEvent(AWTEvent e)
          The AWT event dispatcher uses this method to request that the manager handle a particular event.
abstract  boolean dispatchKeyEvent(KeyEvent e)
          Attempts to dispatch key events for which no key event dispatcher has so far succeeded.
 void downFocusCycle()
          Moves the current focus downwards by one focus cycle, iff the current focus cycle root is a Container.
abstract  void downFocusCycle(Container cont)
          Moves the current focus downwards by one focus cycle.
protected abstract  void enqueueKeyEvents(long after, Component untilFocused)
          Delays all key events following the specified timestamp until the supplied component has focus.
protected  void firePropertyChange(String name, Object o, Object n)
          Fires a property change event as a response to a change to to the specified property.
protected  void fireVetoableChange(String name, Object o, Object n)
          Fires a property change event as a response to a vetoable change to to the specified property.
 void focusNextComponent()
          Moves the current focus to the next component, based on the current focus traversal policy.
abstract  void focusNextComponent(Component comp)
          Moves the current focus to the next component following comp, based on the current focus traversal policy.
 void focusPreviousComponent()
          Moves the current focus to the previous component, based on the current focus traversal policy.
abstract  void focusPreviousComponent(Component comp)
          Moves the current focus to the previous component, prior to comp, based on the current focus traversal policy.
 Window getActiveWindow()
          Retrieve the active Window, or null if the active window was not set by a thread in the current ThreadGroup.
 Container getCurrentFocusCycleRoot()
          Retrieve the current focus cycle root, or null if the focus owner was not set by a thread in the current ThreadGroup.
static KeyboardFocusManager getCurrentKeyboardFocusManager()
          Retrieve the keyboard focus manager associated with the ThreadGroup to which the calling thread belongs.
 Set<AWTKeyStroke> getDefaultFocusTraversalKeys(int id)
          Retrieve the default Set of focus traversal keys for one of the focus traversal directions.
 FocusTraversalPolicy getDefaultFocusTraversalPolicy()
          Retrieve the default FocusTraversalPolicy.
 Window getFocusedWindow()
          Retrieve the Window that is or contains the keyboard focus owner, or null if the focused window was not set by a thread in the current ThreadGroup.
 Component getFocusOwner()
          Retrieve the Component that has the keyboard focus, or null if the focus owner was not set by a thread in the current ThreadGroup.
protected  Window getGlobalActiveWindow()
          Retrieve the active Window, regardless of whether or not the Window was made active by a thread in the current ThreadGroup.
protected  Container getGlobalCurrentFocusCycleRoot()
          Retrieve the current focus cycle root, regardless of whether or not it was made set by a thread in the current ThreadGroup.
protected  Window getGlobalFocusedWindow()
          Retrieve the Window that is or contains the focus owner, regardless of whether or not the Window was set focused by a thread in the current ThreadGroup.
protected  Component getGlobalFocusOwner()
          Retrieve the Component that has the keyboard focus, regardless of whether or not it was set by a thread in the current ThreadGroup.
protected  Component getGlobalPermanentFocusOwner()
          Retrieve the Component that has the permanent keyboard focus, regardless of whether or not it was set by a thread in the current ThreadGroup.
protected  List<KeyEventDispatcher> getKeyEventDispatchers()
          Returns the currently registered key event dispatchers in List form.
protected  List<KeyEventPostProcessor> getKeyEventPostProcessors()
          Returns the currently registered key event post processors in List form.
 Component getPermanentFocusOwner()
          Retrieve the Component that has the permanent keyboard focus, or null if the focus owner was not set by a thread in the current ThreadGroup.
 PropertyChangeListener[] getPropertyChangeListeners()
          Returns the currently registered property change listeners in array form.
 PropertyChangeListener[] getPropertyChangeListeners(String name)
          Returns the currently registered property change listeners in array form, which listen for changes to the supplied property.
 VetoableChangeListener[] getVetoableChangeListeners()
          Returns the currently registered vetoable property change listeners in array form.
 VetoableChangeListener[] getVetoableChangeListeners(String name)
          Returns the currently registered vetoable property change listeners in array form, which listen for changes to the supplied property.
abstract  boolean postProcessKeyEvent(KeyEvent e)
          Handles the post processing of key events.
abstract  void processKeyEvent(Component focused, KeyEvent e)
          Handles focus traversal operations for key events which represent focus traversal keys in relation to the supplied component.
 void redispatchEvent(Component target, AWTEvent e)
          Handles redispatching of an event so that recursion of dispatch requests does not occur.
 void removeKeyEventDispatcher(KeyEventDispatcher dispatcher)
          Removes the specified key event dispatcher from the list of registered dispatchers.
 void removeKeyEventPostProcessor(KeyEventPostProcessor postProcessor)
          Removes the specified key event post processor from the list of registered post processors.
 void removePropertyChangeListener(PropertyChangeListener l)
          Removes the supplied property change listener from the list of registered listeners.
 void removePropertyChangeListener(String name, PropertyChangeListener l)
          Removes the supplied property change listener registered for the specified property from the list of registered listeners.
 void removeVetoableChangeListener(String name, VetoableChangeListener l)
          Removes the supplied vetoable property change listener registered for the specified property from the list of registered listeners.
 void removeVetoableChangeListener(VetoableChangeListener l)
          Removes the supplied vetoable property change listener from the list of registered listeners.
static void setCurrentKeyboardFocusManager(KeyboardFocusManager m)
          Set the keyboard focus manager associated with the ThreadGroup to which the calling thread belongs.
 void setDefaultFocusTraversalKeys(int id, Set<? extends AWTKeyStroke> keystrokes)
          Set the default Set of focus traversal keys for one of the focus traversal directions.
 void setDefaultFocusTraversalPolicy(FocusTraversalPolicy policy)
          Set the FocusTraversalPolicy returned by getDefaultFocusTraversalPolicy().
protected  void setGlobalActiveWindow(Window window)
          Set the Window that will be returned by getActiveWindow() (when it is called from the current ThreadGroup) and getGlobalActiveWindow().
 void setGlobalCurrentFocusCycleRoot(Container cycleRoot)
          Set the Container that will be returned by getCurrentFocusCycleRoot() (when it is called from the current ThreadGroup) and getGlobalCurrentFocusCycleRoot().
protected  void setGlobalFocusedWindow(Window window)
          Set the Window that will be returned by getFocusedWindow() (when it is called from the current ThreadGroup) and getGlobalFocusedWindow().
protected  void setGlobalFocusOwner(Component owner)
          Set the Component that will be returned by getFocusOwner() (when it is called from the current ThreadGroup) and getGlobalFocusOwner().
protected  void setGlobalPermanentFocusOwner(Component focusOwner)
          Set the Component that will be returned by getPermanentFocusOwner() (when it is called from the current ThreadGroup) and getGlobalPermanentFocusOwner().
 void upFocusCycle()
          Moves the current focus upwards by one focus cycle, so that the new focus owner is the focus cycle root of the current owner.
abstract  void upFocusCycle(Component comp)
          Moves the current focus upwards by one focus cycle.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

FORWARD_TRAVERSAL_KEYS

public static final int FORWARD_TRAVERSAL_KEYS
Identifies AWTKeyStrokes that move the focus forward in the focus cycle.

See Also:
Constant Field Values

BACKWARD_TRAVERSAL_KEYS

public static final int BACKWARD_TRAVERSAL_KEYS
Identifies AWTKeyStrokes that move the focus backward in the focus cycle.

See Also:
Constant Field Values

UP_CYCLE_TRAVERSAL_KEYS

public static final int UP_CYCLE_TRAVERSAL_KEYS
Identifies AWTKeyStrokes that move the focus up to the parent focus cycle root.

See Also:
Constant Field Values

DOWN_CYCLE_TRAVERSAL_KEYS

public static final int DOWN_CYCLE_TRAVERSAL_KEYS
Identifies AWTKeyStrokes that move the focus down to the child focus cycle root.

See Also:
Constant Field Values
Constructor Detail

KeyboardFocusManager

public KeyboardFocusManager()
Construct a KeyboardFocusManager.

Method Detail

getCurrentKeyboardFocusManager

public static KeyboardFocusManager getCurrentKeyboardFocusManager()
Retrieve the keyboard focus manager associated with the ThreadGroup to which the calling thread belongs.

Returns:
the keyboard focus manager associated with the current thread group

setCurrentKeyboardFocusManager

public static void setCurrentKeyboardFocusManager(KeyboardFocusManager m)
Set the keyboard focus manager associated with the ThreadGroup to which the calling thread belongs.

Parameters:
m - the keyboard focus manager for the current thread group

getFocusOwner

public Component getFocusOwner()
Retrieve the Component that has the keyboard focus, or null if the focus owner was not set by a thread in the current ThreadGroup.

Returns:
the keyboard focus owner or null

getGlobalFocusOwner

protected Component getGlobalFocusOwner()
Retrieve the Component that has the keyboard focus, regardless of whether or not it was set by a thread in the current ThreadGroup. If there is no temporary focus owner in effect then this method will return the same value as getGlobalPermanentFocusOwner().

Returns:
the keyboard focus owner
Throws:
SecurityException - if this is not the keyboard focus manager associated with the current ThreadGroup

setGlobalFocusOwner

protected void setGlobalFocusOwner(Component owner)
Set the Component that will be returned by getFocusOwner() (when it is called from the current ThreadGroup) and getGlobalFocusOwner(). This method does not actually transfer the keyboard focus.

Parameters:
owner - the Component to return from getFocusOwner and getGlobalFocusOwner
See Also:
Component.requestFocus(), Component.requestFocusInWindow()

clearGlobalFocusOwner

public void clearGlobalFocusOwner()
Clear the global focus owner and deliver a FOCUS_LOST event to the previously-focused Component. Until another Component becomes the keyboard focus owner, key events will be discarded by top-level windows.


getPermanentFocusOwner

public Component getPermanentFocusOwner()
Retrieve the Component that has the permanent keyboard focus, or null if the focus owner was not set by a thread in the current ThreadGroup.

Returns:
the keyboard focus owner or null

getGlobalPermanentFocusOwner

protected Component getGlobalPermanentFocusOwner()
Retrieve the Component that has the permanent keyboard focus, regardless of whether or not it was set by a thread in the current ThreadGroup.

Returns:
the keyboard focus owner
Throws:
SecurityException - if this is not the keyboard focus manager associated with the current ThreadGroup

setGlobalPermanentFocusOwner

protected void setGlobalPermanentFocusOwner(Component focusOwner)
Set the Component that will be returned by getPermanentFocusOwner() (when it is called from the current ThreadGroup) and getGlobalPermanentFocusOwner(). This method does not actually transfer the keyboard focus.

Parameters:
focusOwner - the Component to return from getPermanentFocusOwner and getGlobalPermanentFocusOwner
See Also:
Component.requestFocus(), Component.requestFocusInWindow()

getFocusedWindow

public Window getFocusedWindow()
Retrieve the Window that is or contains the keyboard focus owner, or null if the focused window was not set by a thread in the current ThreadGroup.

Returns:
the focused window or null

getGlobalFocusedWindow

protected Window getGlobalFocusedWindow()
Retrieve the Window that is or contains the focus owner, regardless of whether or not the Window was set focused by a thread in the current ThreadGroup.

Returns:
the focused window
Throws:
SecurityException - if this is not the keyboard focus manager associated with the current ThreadGroup

setGlobalFocusedWindow

protected void setGlobalFocusedWindow(Window window)
Set the Window that will be returned by getFocusedWindow() (when it is called from the current ThreadGroup) and getGlobalFocusedWindow(). This method does not actually cause window to become the focused Window.

Parameters:
window - the Window to return from getFocusedWindow and getGlobalFocusedWindow

getActiveWindow

public Window getActiveWindow()
Retrieve the active Window, or null if the active window was not set by a thread in the current ThreadGroup.

Returns:
the active window or null

getGlobalActiveWindow

protected Window getGlobalActiveWindow()
Retrieve the active Window, regardless of whether or not the Window was made active by a thread in the current ThreadGroup.

Returns:
the active window
Throws:
SecurityException - if this is not the keyboard focus manager associated with the current ThreadGroup

setGlobalActiveWindow

protected void setGlobalActiveWindow(Window window)
Set the Window that will be returned by getActiveWindow() (when it is called from the current ThreadGroup) and getGlobalActiveWindow(). This method does not actually cause window to be made active.

Parameters:
window - the Window to return from getActiveWindow and getGlobalActiveWindow

getDefaultFocusTraversalPolicy

public FocusTraversalPolicy getDefaultFocusTraversalPolicy()
Retrieve the default FocusTraversalPolicy. Focus-managing Containers use the returned object to define their initial focus traversal policy.

Returns:
a non-null default FocusTraversalPolicy object

setDefaultFocusTraversalPolicy

public void setDefaultFocusTraversalPolicy(FocusTraversalPolicy policy)
Set the FocusTraversalPolicy returned by getDefaultFocusTraversalPolicy(). Focus-managing Containers created after this call will use policy as their initial focus traversal policy. Existing Containers' focus traversal policies will not be affected by calls to this method.

Parameters:
policy - the FocusTraversalPolicy that will be returned by subsequent calls to getDefaultFocusTraversalPolicy
Throws:
IllegalArgumentException - if policy is null

setDefaultFocusTraversalKeys

public void setDefaultFocusTraversalKeys(int id,
                                         Set<? extends AWTKeyStroke> keystrokes)
Set the default Set of focus traversal keys for one of the focus traversal directions.

Parameters:
id - focus traversal direction identifier
keystrokes - set of AWTKeyStrokes
See Also:
FORWARD_TRAVERSAL_KEYS, BACKWARD_TRAVERSAL_KEYS, UP_CYCLE_TRAVERSAL_KEYS, DOWN_CYCLE_TRAVERSAL_KEYS

getDefaultFocusTraversalKeys

public Set<AWTKeyStroke> getDefaultFocusTraversalKeys(int id)
Retrieve the default Set of focus traversal keys for one of the focus traversal directions.

Parameters:
id - focus traversal direction identifier
Returns:
the default set of AWTKeyStrokes
See Also:
FORWARD_TRAVERSAL_KEYS, BACKWARD_TRAVERSAL_KEYS, UP_CYCLE_TRAVERSAL_KEYS, DOWN_CYCLE_TRAVERSAL_KEYS

getCurrentFocusCycleRoot

public Container getCurrentFocusCycleRoot()
Retrieve the current focus cycle root, or null if the focus owner was not set by a thread in the current ThreadGroup.

Returns:
the current focus cycle root or null

getGlobalCurrentFocusCycleRoot

protected Container getGlobalCurrentFocusCycleRoot()
Retrieve the current focus cycle root, regardless of whether or not it was made set by a thread in the current ThreadGroup.

Returns:
the current focus cycle root
Throws:
SecurityException - if this is not the keyboard focus manager associated with the current ThreadGroup

setGlobalCurrentFocusCycleRoot

public void setGlobalCurrentFocusCycleRoot(Container cycleRoot)
Set the Container that will be returned by getCurrentFocusCycleRoot() (when it is called from the current ThreadGroup) and getGlobalCurrentFocusCycleRoot(). This method does not actually make cycleRoot the current focus cycle root.

Parameters:
cycleRoot - the focus cycle root to return from getCurrentFocusCycleRoot and getGlobalCurrentFocusCycleRoot

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener l)
Registers the supplied property change listener for receiving events caused by the following property changes: If the supplied listener is null, nothing occurs.

Parameters:
l - the new listener to register.
See Also:
addPropertyChangeListener(String, java.beans.PropertyChangeListener)

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener l)
Removes the supplied property change listener from the list of registered listeners. If the supplied listener is null, nothing occurs.

Parameters:
l - the listener to remove.

getPropertyChangeListeners

public PropertyChangeListener[] getPropertyChangeListeners()
Returns the currently registered property change listeners in array form. The returned array is empty if no listeners are currently registered.

Returns:
an array of registered property change listeners.

addPropertyChangeListener

public void addPropertyChangeListener(String name,
                                      PropertyChangeListener l)
Registers a property change listener for receiving events relating to a change to a specified property. The supplied property name can be either user-defined or one from the following list of properties relevant to this class: Nothing occurs if a null listener is supplied. null is regarded as a valid property name.

Parameters:
name - the name of the property to handle change events for.
l - the listener to register for changes to the specified property.
See Also:
addPropertyChangeListener(java.beans.PropertyChangeListener)

removePropertyChangeListener

public void removePropertyChangeListener(String name,
                                         PropertyChangeListener l)
Removes the supplied property change listener registered for the specified property from the list of registered listeners. If the supplied listener is null, nothing occurs.

Parameters:
name - the name of the property the listener is monitoring changes to.
l - the listener to remove.

getPropertyChangeListeners

public PropertyChangeListener[] getPropertyChangeListeners(String name)
Returns the currently registered property change listeners in array form, which listen for changes to the supplied property. The returned array is empty, if no listeners are currently registered for events pertaining to the supplied property.

Parameters:
name - The property the returned listeners monitor for changes.
Returns:
an array of registered property change listeners which listen for changes to the supplied property.

firePropertyChange

protected void firePropertyChange(String name,
                                  Object o,
                                  Object n)
Fires a property change event as a response to a change to to the specified property. The event is only fired if a change has actually occurred (i.e. o and n are different).

Parameters:
name - The name of the property to which a change occurred.
o - The old value of the property.
n - The new value of the property.

addVetoableChangeListener

public void addVetoableChangeListener(VetoableChangeListener l)
Registers a vetoable property change listener for receiving events relating to the following properties: Nothing occurs if a null listener is supplied.

Parameters:
l - the listener to register.
See Also:
addVetoableChangeListener(String, java.beans.VetoableChangeListener)

removeVetoableChangeListener

public void removeVetoableChangeListener(VetoableChangeListener l)
Removes the supplied vetoable property change listener from the list of registered listeners. If the supplied listener is null, nothing occurs.

Parameters:
l - the listener to remove.

getVetoableChangeListeners

public VetoableChangeListener[] getVetoableChangeListeners()
Returns the currently registered vetoable property change listeners in array form. The returned array is empty if no listeners are currently registered.

Returns:
an array of registered vetoable property change listeners.
Since:
1.4

addVetoableChangeListener

public void addVetoableChangeListener(String name,
                                      VetoableChangeListener l)
Registers a vetoable property change listener for receiving events relating to a vetoable change to a specified property. The supplied property name can be either user-defined or one from the following list of properties relevant to this class: Nothing occurs if a null listener is supplied. null is regarded as a valid property name.

Parameters:
name - the name of the property to handle change events for.
l - the listener to register for changes to the specified property.
See Also:
addVetoableChangeListener(java.beans.VetoableChangeListener)

removeVetoableChangeListener

public void removeVetoableChangeListener(String name,
                                         VetoableChangeListener l)
Removes the supplied vetoable property change listener registered for the specified property from the list of registered listeners. If the supplied listener is null, nothing occurs.

Parameters:
name - the name of the vetoable property the listener is monitoring changes to.
l - the listener to remove.

getVetoableChangeListeners

public VetoableChangeListener[] getVetoableChangeListeners(String name)
Returns the currently registered vetoable property change listeners in array form, which listen for changes to the supplied property. The returned array is empty, if no listeners are currently registered for events pertaining to the supplied property.

Parameters:
name - The property the returned listeners monitor for changes.
Returns:
an array of registered property change listeners which listen for changes to the supplied property.
Since:
1.4

fireVetoableChange

protected void fireVetoableChange(String name,
                                  Object o,
                                  Object n)
                           throws PropertyVetoException
Fires a property change event as a response to a vetoable change to to the specified property. The event is only fired if a change has actually occurred (i.e. o and n are different). In the event that the property change is vetoed, the following occurs:
  1. This method throws a PropertyVetoException to the proposed change.
  2. A new event is fired to reverse the previous change.
  3. This method again throws a PropertyVetoException in response to the reversion.

Parameters:
name - The name of the property to which a change occurred.
o - The old value of the property.
n - The new value of the property.
Throws:
PropertyVetoException - if one of the listeners vetos the change by throwing this exception.

addKeyEventDispatcher

public void addKeyEventDispatcher(KeyEventDispatcher dispatcher)
Adds a key event dispatcher to the list of registered dispatchers. When a key event is fired, each dispatcher's dispatchKeyEvent method is called in the order that they were added, prior to the manager dispatching the event itself. Notifications halt when one of the dispatchers returns true.

The same dispatcher can exist multiple times within the list of registered dispatchers, and there is no limit on the length of this list. A null dispatcher is simply ignored.

Parameters:
dispatcher - The dispatcher to register.

removeKeyEventDispatcher

public void removeKeyEventDispatcher(KeyEventDispatcher dispatcher)
Removes the specified key event dispatcher from the list of registered dispatchers. The manager always dispatches events, regardless of its existence within the list. The manager can be added and removed from the list, as with any other dispatcher, but this does not affect its ability to dispatch key events. Non-existent and null dispatchers are simply ignored by this method.

Parameters:
dispatcher - The dispatcher to remove.

getKeyEventDispatchers

protected List<KeyEventDispatcher> getKeyEventDispatchers()
Returns the currently registered key event dispatchers in List form. At present, this only includes dispatchers explicitly registered via the addKeyEventDispatcher() method, but this behaviour is subject to change and should not be depended on. The manager itself may be a member of the list, but only if explicitly registered. If no dispatchers have been registered, the list will be empty.

Returns:
A list of explicitly registered key event dispatchers.
See Also:
addKeyEventDispatcher(java.awt.KeyEventDispatcher)

addKeyEventPostProcessor

public void addKeyEventPostProcessor(KeyEventPostProcessor postProcessor)
Adds a key event post processor to the list of registered post processors. Post processors work in the same way as key event dispatchers, except that they are invoked after the manager has dispatched the key event, and not prior to this. Each post processor's postProcessKeyEvent method is called to see if any post processing needs to be performed. THe processors are called in the order in which they were added to the list, and notifications continue until one returns true. As with key event dispatchers, the manager is implicitly called following this process, regardless of whether or not it is present within the list.

The same post processor can exist multiple times within the list of registered post processors, and there is no limit on the length of this list. A null post processor is simply ignored.

Parameters:
postProcessor - the post processor to register.
See Also:
addKeyEventDispatcher(java.awt.KeyEventDispatcher)

removeKeyEventPostProcessor

public void removeKeyEventPostProcessor(KeyEventPostProcessor postProcessor)
Removes the specified key event post processor from the list of registered post processors. The manager always post processes events, regardless of its existence within the list. The manager can be added and removed from the list, as with any other post processor, but this does not affect its ability to post process key events. Non-existent and null post processors are simply ignored by this method.

Parameters:
postProcessor - the post processor to remove.

getKeyEventPostProcessors

protected List<KeyEventPostProcessor> getKeyEventPostProcessors()
Returns the currently registered key event post processors in List form. At present, this only includes post processors explicitly registered via the addKeyEventPostProcessor() method, but this behaviour is subject to change and should not be depended on. The manager itself may be a member of the list, but only if explicitly registered. If no post processors have been registered, the list will be empty.

Returns:
A list of explicitly registered key event post processors.
See Also:
addKeyEventPostProcessor(java.awt.KeyEventPostProcessor)

dispatchEvent

public abstract boolean dispatchEvent(AWTEvent e)
The AWT event dispatcher uses this method to request that the manager handle a particular event. If the manager fails or refuses to dispatch the supplied event (this method returns false), the AWT event dispatcher will try to dispatch the event itself.

The manager is expected to handle all FocusEvents and KeyEvents, and WindowEvents relating to the focus. Dispatch is done with regard to the the focus owner and the currently focused and active windows. In handling the event, the source of the event may be overridden.

The actual dispatching is performed by calling redispatchEvent(). This avoids the infinite recursion of dispatch requests which may occur if this method is called on the target component.

Parameters:
e - the event to dispatch.
Returns:
true if the event was dispatched.
See Also:
redispatchEvent(java.awt.Component, java.awt.AWTEvent), KeyEvent, FocusEvent, WindowEvent

redispatchEvent

public final void redispatchEvent(Component target,
                                  AWTEvent e)
Handles redispatching of an event so that recursion of dispatch requests does not occur. Event dispatch methods within this manager (dispatchEvent()) and the key event dispatchers should use this method to handle dispatching rather than the dispatch method of the target component.

This method is not intended for general consumption, and is only for the use of the aforementioned classes.

Parameters:
target - the target component to which the event is dispatched.
e - the event to dispatch.

dispatchKeyEvent

public abstract boolean dispatchKeyEvent(KeyEvent e)
Attempts to dispatch key events for which no key event dispatcher has so far succeeded. This method is usually called by dispatchEvent() following the sending of the key event to any registered key event dispatchers. If the key event reaches this stage, none of the dispatchers returned true. This is, of course, always the case if there are no registered dispatchers.

If this method also fails to handle the key event, then false is returned to the caller. In the case of dispatchEvent(), the calling method may try to handle the event itself or simply forward on the false result to its caller. When the event is dispatched by this method, a true result is propogated through the calling methods.

Specified by:
dispatchKeyEvent in interface KeyEventDispatcher
Parameters:
e - the key event to dispatch.
Returns:
true if the event was dispatched successfully.
See Also:
redispatchEvent(Component, AWTEvent)

postProcessKeyEvent

public abstract boolean postProcessKeyEvent(KeyEvent e)
Handles the post processing of key events. By default, this method will map unhandled key events to appropriate MenuShortcuts. The event is consumed in the process and the shortcut is activated. This method is usually called by dispatchKeyEvent.

Specified by:
postProcessKeyEvent in interface KeyEventPostProcessor
Parameters:
e - the key event to post process.
Returns:
true by default, as the event was handled.
See Also:
redispatchEvent(Component, AWTEvent)

processKeyEvent

public abstract void processKeyEvent(Component focused,
                                     KeyEvent e)
Handles focus traversal operations for key events which represent focus traversal keys in relation to the supplied component. The supplied component is assumed to have the focus, whether it does so or not, and the operation is carried out as appropriate, with this in mind.

Parameters:
focused - the component on which to perform focus traversal, on the assumption that this component has the focus.
e - the possible focus traversal key event.

enqueueKeyEvents

protected abstract void enqueueKeyEvents(long after,
                                         Component untilFocused)
Delays all key events following the specified timestamp until the supplied component has focus. The AWT calls this method when it is determined that a focus change may occur within the native windowing system. Any key events which occur following the time specified by after are delayed until a FOCUS_GAINED event is received for the untilFocused component. The manager is responsible for ensuring this takes place.

Parameters:
after - the timestamp beyond which all key events are delayed until the supplied component gains focus.
untilFocused - the component to wait on gaining focus.

dequeueKeyEvents

protected abstract void dequeueKeyEvents(long after,
                                         Component untilFocused)
Removes the key event block specified by the supplied timestamp and component. All delayed key events are released for normal dispatching following its removal and subsequent key events that would have been blocked are now immediately dispatched. If the specified timestamp is below 0, then the request with the oldest timestamp is removed.

Parameters:
after - the timestamp of the key event block to be removed, or a value smaller than 0 if the oldest is to be removed.
untilFocused - the component of the key event block to be removed.

discardKeyEvents

protected abstract void discardKeyEvents(Component comp)
Discards all key event blocks relating to focus requirements for the supplied component, regardless of timestamp.

Parameters:
comp - the component of the key event block(s) to be removed.

focusNextComponent

public abstract void focusNextComponent(Component comp)
Moves the current focus to the next component following comp, based on the current focus traversal policy. By default, only visible, displayable, accepted components can receive focus. Canvases, Panels, Labels, ScrollPanes, Scrollbars, Windows and lightweight components are judged to be unacceptable by default. See the DefaultFocusTraversalPolicy for more details.

Parameters:
comp - the component prior to the one which will become the focus, following execution of this method.
See Also:
DefaultFocusTraversalPolicy

focusPreviousComponent

public abstract void focusPreviousComponent(Component comp)
Moves the current focus to the previous component, prior to comp, based on the current focus traversal policy. By default, only visible, displayable, accepted components can receive focus. Canvases, Panels, Labels, ScrollPanes, Scrollbars, Windows and lightweight components are judged to be unacceptable by default. See the DefaultFocusTraversalPolicy for more details.

Parameters:
comp - the component following the one which will become the focus, following execution of this method.
See Also:
DefaultFocusTraversalPolicy

upFocusCycle

public abstract void upFocusCycle(Component comp)
Moves the current focus upwards by one focus cycle. Both the current focus owner and current focus cycle root become the focus cycle root of the supplied component. However, in the case of a Window, the default focus component becomes the focus owner and the focus cycle root is not changed.

Parameters:
comp - the component used as part of the focus traversal.

downFocusCycle

public abstract void downFocusCycle(Container cont)
Moves the current focus downwards by one focus cycle. If the supplied container is a focus cycle root, then this becomes the current focus cycle root and the focus goes to the default component of the specified container. Nothing happens for non-focus cycle root containers.

Parameters:
cont - the container used as part of the focus traversal.

focusNextComponent

public final void focusNextComponent()
Moves the current focus to the next component, based on the current focus traversal policy. By default, only visible, displayable, accepted component can receive focus. Canvases, Panels, Labels, ScrollPanes, Scrollbars, Windows and lightweight components are judged to be unacceptable by default. See the DefaultFocusTraversalPolicy for more details.

See Also:
DefaultFocusTraversalPolicy

focusPreviousComponent

public final void focusPreviousComponent()
Moves the current focus to the previous component, based on the current focus traversal policy. By default, only visible, displayable, accepted component can receive focus. Canvases, Panels, Labels, ScrollPanes, Scrollbars, Windows and lightweight components are judged to be unacceptable by default. See the DefaultFocusTraversalPolicy for more details.

See Also:
DefaultFocusTraversalPolicy

upFocusCycle

public final void upFocusCycle()
Moves the current focus upwards by one focus cycle, so that the new focus owner is the focus cycle root of the current owner. The current focus cycle root then becomes the focus cycle root of the new focus owner. However, in the case of the focus cycle root of the current focus owner being a Window, the default component of this window becomes the focus owner and the focus cycle root is not changed.


downFocusCycle

public final void downFocusCycle()
Moves the current focus downwards by one focus cycle, iff the current focus cycle root is a Container. Usually, the new focus owner is set to the default component of the container and the current focus cycle root is set to the current focus owner. Nothing occurs if the current focus cycle root is not a container.