Class KeyboardFocusManager

public static final int BACKWARD_TRAVERSAL_KEYS

Identifies AWTKeyStrokes that move the focus backward in the focus cycle.

Field Value:

1

public static final int DOWN_CYCLE_TRAVERSAL_KEYS

Identifies AWTKeyStrokes that move the focus down to the child focus cycle root.

Field Value:

3

public static final int FORWARD_TRAVERSAL_KEYS

Identifies AWTKeyStrokes that move the focus forward in the focus cycle.

Field Value:

0

public static final int UP_CYCLE_TRAVERSAL_KEYS

Identifies AWTKeyStrokes that move the focus up to the parent focus cycle root.

Field Value:

2

public KeyboardFocusManager()

Construct a KeyboardFocusManager.

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.

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(KeyEventDispatcher)

public 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.

Parameters:

l - the new listener to register.

See Also:

addPropertyChangeListener(String,PropertyChangeListener)

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:

• 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.

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(PropertyChangeListener)

public 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.

Parameters:

l - the listener to register.

See Also:

addVetoableChangeListener(String,VetoableChangeListener)

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:

• 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.

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(VetoableChangeListener)

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.

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.

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.

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(Component,AWTEvent), KeyEvent, FocusEvent, WindowEvent

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.

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.

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.

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.

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.

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.

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

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

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

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

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

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

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

public Set 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

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

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

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

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

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

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

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

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

protected 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.

Returns:

A list of explicitly registered key event dispatchers.

See Also:

addKeyEventDispatcher(KeyEventDispatcher)

protected 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.

Returns:

A list of explicitly registered key event post processors.

See Also:

addKeyEventPostProcessor(KeyEventPostProcessor)

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

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.

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.

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

public void setDefaultFocusTraversalKeys(int id,
                                         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

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

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

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

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()

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

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()

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.

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.