Docjar: A Java Source and Docuemnt Enginecom.*    java.*    javax.*    org.*    all    new    plug-in

Quick Search    Search Deep

java.awt
Class KeyboardFocusManager  view KeyboardFocusManager download KeyboardFocusManager.java

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

public abstract class KeyboardFocusManager
extends java.lang.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.
private static java.util.Map currentActiveWindows
          A java.util.Map keyed on java.lang.ThreadGroups that stores the active Window.
private static java.util.Map currentFocusCycleRoots
          A java.util.Map keyed on java.lang.ThreadGroups that stores the focus cycle root Container.
private static java.util.Map currentFocusedWindows
          A java.util.Map keyed on java.lang.ThreadGroups that stores the focused Window.
private static java.util.Map currentFocusOwners
          java.applet.Applets in one codebase must not be allowed to access Components in java.applet.Applets in other codebases.
private static java.util.Map currentKeyboardFocusManagers
          For security reasons, java.applet.Applets in different codebases must be insulated from one another.
private static java.util.Map currentPermanentFocusOwners
          A java.util.Map keyed on java.lang.ThreadGroups that stores the Component that owns the permanent keyboard focus.
private static java.util.Set DEFAULT_BACKWARD_KEYS
          The set of AWTKeyStrokes that cause focus to be moved to the previous focusable Component in the focus cycle.
private static java.util.Set DEFAULT_FORWARD_KEYS
          The set of AWTKeyStrokes that cause focus to be moved to the next focusable Component in the focus cycle.
private  java.util.Set[] defaultFocusKeys
          An array that stores the FORWARD_TRAVERSAL_KEYS 55 , BACKWARD_TRAVERSAL_KEYS 55 , UP_CYCLE_TRAVERSAL_KEYS 55 and DOWN_CYCLE_TRAVERSAL_KEYS 55 AWTKeyStrokes java.util.Sets.
private  FocusTraversalPolicy defaultPolicy
          The default FocusTraversalPolicy that focus-managing Containers will use to define their initial focus traversal policy.
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.
private  java.util.ArrayList keyEventDispatchers
          A list of KeyEventDispatchers that process java.awt.event.KeyEvents before they are processed the default keyboard focus manager.
private  java.util.ArrayList keyEventPostProcessors
          A list of KeyEventPostProcessors that process unconsumed java.awt.event.KeyEvents.
private  java.beans.PropertyChangeSupport propertyChangeSupport
          A utility class to support the handling of events relating to property changes.
static int UP_CYCLE_TRAVERSAL_KEYS
          Identifies AWTKeyStrokes that move the focus up to the parent focus cycle root.
private  java.beans.VetoableChangeSupport vetoableChangeSupport
          A utility class to support the handling of events relating to vetoable changes.
 
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(java.beans.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(java.lang.String name, java.beans.PropertyChangeListener l)
          Registers a property change listener for receiving events relating to a change to a specified property.
 void addVetoableChangeListener(java.lang.String name, java.beans.VetoableChangeListener l)
          Registers a vetoable property change listener for receiving events relating to a vetoable change to a specified property.
 void addVetoableChangeListener(java.beans.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(java.awt.event.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(java.lang.String name, java.lang.Object o, java.lang.Object n)
          Fires a property change event as a response to a change to to the specified property.
protected  void fireVetoableChange(java.lang.String name, java.lang.Object o, java.lang.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 java.lang.ThreadGroup.
 Container getCurrentFocusCycleRoot()
          Retrieve the current focus cycle root, or null if the focus owner was not set by a thread in the current java.lang.ThreadGroup.
static KeyboardFocusManager getCurrentKeyboardFocusManager()
          Retrieve the keyboard focus manager associated with the java.lang.ThreadGroup to which the calling thread belongs.
 java.util.Set getDefaultFocusTraversalKeys(int id)
          Retrieve the default java.util.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 java.lang.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 java.lang.ThreadGroup.
protected  Window getGlobalActiveWindow()
          Retrieve the active Window, regardless of whether or not the Window was made active by a thread in the current java.lang.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 java.lang.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 java.lang.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 java.lang.ThreadGroup.
private  java.lang.Object getGlobalObject(java.util.Map globalMap)
          Retrieve an object from one of the global object java.util.Maps, regardless of whether or not the object was set by a thread in the current java.lang.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 java.lang.ThreadGroup.
protected  java.util.List getKeyEventDispatchers()
          Returns the currently registered key event dispatchers in List form.
protected  java.util.List getKeyEventPostProcessors()
          Returns the currently registered key event post processors in List form.
private  java.lang.Object getObject(java.util.Map globalMap)
          Retrieve an object from one of the global object java.util.Maps, if the object was set by the a thread in the current java.lang.ThreadGroup.
 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 java.lang.ThreadGroup.
 java.beans.PropertyChangeListener[] getPropertyChangeListeners()
          Returns the currently registered property change listeners in array form.
 java.beans.PropertyChangeListener[] getPropertyChangeListeners(java.lang.String name)
          Returns the currently registered property change listeners in array form, which listen for changes to the supplied property.
 java.beans.VetoableChangeListener[] getVetoableChangeListeners()
          Returns the currently registered vetoable property change listeners in array form.
 java.beans.VetoableChangeListener[] getVetoableChangeListeners(java.lang.String name)
          Returns the currently registered vetoable property change listeners in array form, which listen for changes to the supplied property.
abstract  boolean postProcessKeyEvent(java.awt.event.KeyEvent e)
          Handles the post processing of key events.
abstract  void processKeyEvent(Component focused, java.awt.event.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(java.beans.PropertyChangeListener l)
          Removes the supplied property change listener from the list of registered listeners.
 void removePropertyChangeListener(java.lang.String name, java.beans.PropertyChangeListener l)
          Removes the supplied property change listener registered for the specified property from the list of registered listeners.
 void removeVetoableChangeListener(java.lang.String name, java.beans.VetoableChangeListener l)
          Removes the supplied vetoable property change listener registered for the specified property from the list of registered listeners.
 void removeVetoableChangeListener(java.beans.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 java.lang.ThreadGroup to which the calling thread belongs.
 void setDefaultFocusTraversalKeys(int id, java.util.Set keystrokes)
          Set the default java.util.Set of focus traversal keys for one of the focus traversal directions.
 void setDefaultFocusTraversalPolicy(FocusTraversalPolicy policy)
          Set the FocusTraversalPolicy returned by getDefaultFocusTraversalPolicy() 55 .
protected  void setGlobalActiveWindow(Window window)
          Set the Window that will be returned by getActiveWindow() 55 (when it is called from the current java.lang.ThreadGroup) and getGlobalActiveWindow() 55 .
 void setGlobalCurrentFocusCycleRoot(Container cycleRoot)
          Set the Container that will be returned by getCurrentFocusCycleRoot() 55 (when it is called from the current java.lang.ThreadGroup) and getGlobalCurrentFocusCycleRoot() 55 .
protected  void setGlobalFocusedWindow(Window window)
          Set the Window that will be returned by getFocusedWindow() 55 (when it is called from the current java.lang.ThreadGroup) and getGlobalFocusedWindow() 55 .
protected  void setGlobalFocusOwner(Component owner)
          Set the Component that will be returned by getFocusOwner() 55 (when it is called from the current java.lang.ThreadGroup) and getGlobalFocusOwner() 55 .
private  void setGlobalObject(java.util.Map globalMap, java.lang.Object newObject, java.lang.String property)
          Set an object in one of the global object java.util.Maps, that will be returned by subsequent calls to getGlobalObject on the same java.util.Map.
protected  void setGlobalPermanentFocusOwner(Component focusOwner)
          Set the Component that will be returned by getPermanentFocusOwner() 55 (when it is called from the current java.lang.ThreadGroup) and getGlobalPermanentFocusOwner() 55 .
 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

DEFAULT_FORWARD_KEYS

private static final java.util.Set DEFAULT_FORWARD_KEYS
The set of AWTKeyStrokes that cause focus to be moved to the next focusable Component in the focus cycle.


DEFAULT_BACKWARD_KEYS

private static final java.util.Set DEFAULT_BACKWARD_KEYS
The set of AWTKeyStrokes that cause focus to be moved to the previous focusable Component in the focus cycle.


currentKeyboardFocusManagers

private static java.util.Map currentKeyboardFocusManagers
For security reasons, java.applet.Applets in different codebases must be insulated from one another. Since KeyboardFocusManagers have the ability to return Components from a given java.applet.Applet, each codebase must have an independent KeyboardFocusManager. Since each codebase has its own java.lang.ThreadGroup in which its java.applet.Applets run, it makes sense to partition KeyboardFocusManagers according to java.lang.ThreadGroup. Thus, currentKeyboardFocusManagers is a java.util.Map keyed on java.lang.ThreadGroup.


currentFocusOwners

private static java.util.Map currentFocusOwners
java.applet.Applets in one codebase must not be allowed to access Components in java.applet.Applets in other codebases. To enforce this restriction, we key the following java.util.Maps on java.lang.ThreadGroups (which are per-codebase). For example, if java.lang.ThreadGroup A calls setGlobalFocusOwner(java.awt.Component) 55 , passing Component C, currentFocusOwners[A] is assigned C, and all other currentFocusOwners values are nullified. Then if java.lang.ThreadGroup A subsequently calls getGlobalFocusOwner() 55 , it will return currentFocusOwners[A], that is, Component C. If another java.lang.ThreadGroup K calls getGlobalFocusOwner() 55 , it will return currentFocusOwners[K], that is, null. Since this is a static field, we ensure that there is only one focused Component per class loader.


currentPermanentFocusOwners

private static java.util.Map currentPermanentFocusOwners
A java.util.Map keyed on java.lang.ThreadGroups that stores the Component that owns the permanent keyboard focus. @see currentFocusOwners


currentFocusedWindows

private static java.util.Map currentFocusedWindows
A java.util.Map keyed on java.lang.ThreadGroups that stores the focused Window. @see currentFocusOwners


currentActiveWindows

private static java.util.Map currentActiveWindows
A java.util.Map keyed on java.lang.ThreadGroups that stores the active Window. @see currentFocusOwners


currentFocusCycleRoots

private static java.util.Map currentFocusCycleRoots
A java.util.Map keyed on java.lang.ThreadGroups that stores the focus cycle root Container. @see currentFocusOwners


defaultPolicy

private FocusTraversalPolicy defaultPolicy
The default FocusTraversalPolicy that focus-managing Containers will use to define their initial focus traversal policy.


defaultFocusKeys

private java.util.Set[] defaultFocusKeys
An array that stores the FORWARD_TRAVERSAL_KEYS 55 , BACKWARD_TRAVERSAL_KEYS 55 , UP_CYCLE_TRAVERSAL_KEYS 55 and DOWN_CYCLE_TRAVERSAL_KEYS 55 AWTKeyStrokes java.util.Sets.


propertyChangeSupport

private final java.beans.PropertyChangeSupport propertyChangeSupport
A utility class to support the handling of events relating to property changes.


vetoableChangeSupport

private final java.beans.VetoableChangeSupport vetoableChangeSupport
A utility class to support the handling of events relating to vetoable changes.


keyEventDispatchers

private final java.util.ArrayList keyEventDispatchers
A list of KeyEventDispatchers that process java.awt.event.KeyEvents before they are processed the default keyboard focus manager.


keyEventPostProcessors

private final java.util.ArrayList keyEventPostProcessors
A list of KeyEventPostProcessors that process unconsumed java.awt.event.KeyEvents.

Constructor Detail

KeyboardFocusManager

public KeyboardFocusManager()
Construct a KeyboardFocusManager.

Method Detail

getCurrentKeyboardFocusManager

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


setCurrentKeyboardFocusManager

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


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 java.lang.ThreadGroup.


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 java.lang.ThreadGroup. If there is no temporary focus owner in effect then this method will return the same value as getGlobalPermanentFocusOwner() 55 .


setGlobalFocusOwner

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


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 java.lang.ThreadGroup.


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 java.lang.ThreadGroup.


setGlobalPermanentFocusOwner

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


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 java.lang.ThreadGroup.


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 java.lang.ThreadGroup.


setGlobalFocusedWindow

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


getActiveWindow

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


getGlobalActiveWindow

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


setGlobalActiveWindow

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


getDefaultFocusTraversalPolicy

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


setDefaultFocusTraversalPolicy

public void setDefaultFocusTraversalPolicy(FocusTraversalPolicy policy)
Set the FocusTraversalPolicy returned by getDefaultFocusTraversalPolicy() 55 . 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.


setDefaultFocusTraversalKeys

public void setDefaultFocusTraversalKeys(int id,
                                         java.util.Set keystrokes)
Set the default java.util.Set of focus traversal keys for one of the focus traversal directions.


getDefaultFocusTraversalKeys

public java.util.Set getDefaultFocusTraversalKeys(int id)
Retrieve the default java.util.Set of focus traversal keys for one of the focus traversal directions.


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 java.lang.ThreadGroup.


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 java.lang.ThreadGroup.


setGlobalCurrentFocusCycleRoot

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


addPropertyChangeListener

public void addPropertyChangeListener(java.beans.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.


removePropertyChangeListener

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


getPropertyChangeListeners

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


addPropertyChangeListener

public void addPropertyChangeListener(java.lang.String name,
                                      java.beans.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:
  • 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")
Nothing occurs if a null listener is supplied. null is regarded as a valid property name.


removePropertyChangeListener

public void removePropertyChangeListener(java.lang.String name,
                                         java.beans.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.


getPropertyChangeListeners

public java.beans.PropertyChangeListener[] getPropertyChangeListeners(java.lang.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.


firePropertyChange

protected void firePropertyChange(java.lang.String name,
                                  java.lang.Object o,
                                  java.lang.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).


addVetoableChangeListener

public void addVetoableChangeListener(java.beans.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.


removeVetoableChangeListener

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


getVetoableChangeListeners

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

Since:
1.4

addVetoableChangeListener

public void addVetoableChangeListener(java.lang.String name,
                                      java.beans.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:
  • 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. null is regarded as a valid property name.


removeVetoableChangeListener

public void removeVetoableChangeListener(java.lang.String name,
                                         java.beans.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.


getVetoableChangeListeners

public java.beans.VetoableChangeListener[] getVetoableChangeListeners(java.lang.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.

Since:
1.4

fireVetoableChange

protected void fireVetoableChange(java.lang.String name,
                                  java.lang.Object o,
                                  java.lang.Object n)
                           throws java.beans.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.


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.


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.


getKeyEventDispatchers

protected java.util.List 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.


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.


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.


getKeyEventPostProcessors

protected java.util.List 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.


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.


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.


dispatchKeyEvent

public abstract boolean dispatchKeyEvent(java.awt.event.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

postProcessKeyEvent

public abstract boolean postProcessKeyEvent(java.awt.event.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

processKeyEvent

public abstract void processKeyEvent(Component focused,
                                     java.awt.event.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.


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.


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.


discardKeyEvents

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


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.


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.


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.


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.


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.


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.


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.


getObject

private java.lang.Object getObject(java.util.Map globalMap)
Retrieve an object from one of the global object java.util.Maps, if the object was set by the a thread in the current java.lang.ThreadGroup. Otherwise, return null.


getGlobalObject

private java.lang.Object getGlobalObject(java.util.Map globalMap)
Retrieve an object from one of the global object java.util.Maps, regardless of whether or not the object was set by a thread in the current java.lang.ThreadGroup.


setGlobalObject

private void setGlobalObject(java.util.Map globalMap,
                             java.lang.Object newObject,
                             java.lang.String property)
Set an object in one of the global object java.util.Maps, that will be returned by subsequent calls to getGlobalObject on the same java.util.Map.