java.awt

Class KeyboardFocusManager

java.lang.Object

java.awt.KeyboardFocusManager

All Implemented Interfaces:

KeyEventDispatcher, KeyEventPostProcessor

Direct Known Subclasses:

DefaultKeyboardFocusManager

public abstract class KeyboardFocusManager
extends Object
implements KeyEventDispatcher, KeyEventPostProcessor

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

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

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

Please see How to Use the Focus Subsystem, a section in The Java Tutorial, and the Focus Specification for more information.

Since:

1.4

See Also:

Window, Frame, Dialog, FocusEvent, WindowEvent, KeyEvent

Field Summary

Fields

Modifier and Type	Field	Description
static int	BACKWARD_TRAVERSAL_KEYS	The identifier for the Backward focus traversal keys.
static int	DOWN_CYCLE_TRAVERSAL_KEYS	The identifier for the Down Cycle focus traversal keys.
static int	FORWARD_TRAVERSAL_KEYS	The identifier for the Forward focus traversal keys.
static int	UP_CYCLE_TRAVERSAL_KEYS	The identifier for the Up Cycle focus traversal keys.

Constructor Summary

Constructors

Constructor	Description
KeyboardFocusManager()	Initializes a KeyboardFocusManager.

Method Summary

Modifier and Type	Method	Description
void	addKeyEventDispatcher(KeyEventDispatcher dispatcher)	Adds a KeyEventDispatcher to this KeyboardFocusManager's dispatcher chain.
void	addKeyEventPostProcessor(KeyEventPostProcessor processor)	Adds a KeyEventPostProcessor to this KeyboardFocusManager's post- processor chain.
void	addPropertyChangeListener(PropertyChangeListener listener)	Adds a PropertyChangeListener to the listener list.
void	addPropertyChangeListener(String propertyName, PropertyChangeListener listener)	Adds a PropertyChangeListener to the listener list for a specific property.
void	addVetoableChangeListener(String propertyName, VetoableChangeListener listener)	Adds a VetoableChangeListener to the listener list for a specific property.
void	addVetoableChangeListener(VetoableChangeListener listener)	Adds a VetoableChangeListener to the listener list.
void	clearFocusOwner()	Clears the focus owner at both the Java and native levels if the focus owner exists and resides in the same context as the calling thread, otherwise the method returns silently.
void	clearGlobalFocusOwner()	Clears the global focus owner at both the Java and native levels.
protected abstract void	dequeueKeyEvents(long after, Component untilFocused)	Called by the AWT to notify the KeyboardFocusManager that it should cancel delayed dispatching of KeyEvents.
protected abstract void	discardKeyEvents(Component comp)	Called by the AWT to notify the KeyboardFocusManager that it should cancel delayed dispatching of KeyEvents.
abstract boolean	dispatchEvent(AWTEvent e)	This method is called by the AWT event dispatcher requesting that the current KeyboardFocusManager dispatch the specified event on its behalf.
abstract boolean	dispatchKeyEvent(KeyEvent e)	Typically this method will be called by dispatchEvent if no other KeyEventDispatcher in the dispatcher chain dispatched the KeyEvent, or if no other KeyEventDispatchers are registered.
void	downFocusCycle()	Moves the focus down one focus traversal cycle from the current focus owner, if and only if the current focus owner is a Container that is a focus cycle root.
abstract void	downFocusCycle(Container aContainer)	Moves the focus down one focus traversal cycle.
protected abstract void	enqueueKeyEvents(long after, Component untilFocused)	Called by the AWT to notify the KeyboardFocusManager that it should delay dispatching of KeyEvents until the specified Component becomes the focus owner.
protected void	firePropertyChange(String propertyName, Object oldValue, Object newValue)	Fires a PropertyChangeEvent in response to a change in a bound property.
protected void	fireVetoableChange(String propertyName, Object oldValue, Object newValue)	Fires a PropertyChangeEvent in response to a change in a vetoable property.
void	focusNextComponent()	Focuses the Component after the current focus owner.
abstract void	focusNextComponent(Component aComponent)	Focuses the Component after aComponent, typically based on a FocusTraversalPolicy.
void	focusPreviousComponent()	Focuses the Component before the current focus owner.
abstract void	focusPreviousComponent(Component aComponent)	Focuses the Component before aComponent, typically based on a FocusTraversalPolicy.
Window	getActiveWindow()	Returns the active Window, if the active Window is in the same context as the calling thread.
Container	getCurrentFocusCycleRoot()	Returns the current focus cycle root, if the current focus cycle root is in the same context as the calling thread.
static KeyboardFocusManager	getCurrentKeyboardFocusManager()	Returns the current KeyboardFocusManager instance for the calling thread's context.
Set<AWTKeyStroke>	getDefaultFocusTraversalKeys(int id)	Returns a Set of default focus traversal keys for a given traversal operation.
FocusTraversalPolicy	getDefaultFocusTraversalPolicy()	Returns the default FocusTraversalPolicy.
Window	getFocusedWindow()	Returns the focused Window, if the focused Window is in the same context as the calling thread.
Component	getFocusOwner()	Returns the focus owner, if the focus owner is in the same context as the calling thread.
protected Window	getGlobalActiveWindow()	Returns the active Window, even if the calling thread is in a different context than the active Window.
protected Container	getGlobalCurrentFocusCycleRoot()	Returns the current focus cycle root, even if the calling thread is in a different context than the current focus cycle root.
protected Window	getGlobalFocusedWindow()	Returns the focused Window, even if the calling thread is in a different context than the focused Window.
protected Component	getGlobalFocusOwner()	Returns the focus owner, even if the calling thread is in a different context than the focus owner.
protected Component	getGlobalPermanentFocusOwner()	Returns the permanent focus owner, even if the calling thread is in a different context than the permanent focus owner.
protected List<KeyEventDispatcher>	getKeyEventDispatchers()	Returns this KeyboardFocusManager's KeyEventDispatcher chain as a List.
protected List<KeyEventPostProcessor>	getKeyEventPostProcessors()	Returns this KeyboardFocusManager's KeyEventPostProcessor chain as a List.
Component	getPermanentFocusOwner()	Returns the permanent focus owner, if the permanent focus owner is in the same context as the calling thread.
PropertyChangeListener[]	getPropertyChangeListeners()	Returns an array of all the property change listeners registered on this keyboard focus manager.
PropertyChangeListener[]	getPropertyChangeListeners(String propertyName)	Returns an array of all the PropertyChangeListeners associated with the named property.
VetoableChangeListener[]	getVetoableChangeListeners()	Returns an array of all the vetoable change listeners registered on this keyboard focus manager.
VetoableChangeListener[]	getVetoableChangeListeners(String propertyName)	Returns an array of all the VetoableChangeListeners associated with the named property.
abstract boolean	postProcessKeyEvent(KeyEvent e)	This method will be called by dispatchKeyEvent.
abstract void	processKeyEvent(Component focusedComponent, KeyEvent e)	This method initiates a focus traversal operation if and only if the KeyEvent represents a focus traversal key for the specified focusedComponent.
void	redispatchEvent(Component target, AWTEvent e)	Redispatches an AWTEvent in such a way that the AWT event dispatcher will not recursively request that the KeyboardFocusManager, or any installed KeyEventDispatchers, dispatch the event again.
void	removeKeyEventDispatcher(KeyEventDispatcher dispatcher)	Removes a KeyEventDispatcher which was previously added to this KeyboardFocusManager's dispatcher chain.
void	removeKeyEventPostProcessor(KeyEventPostProcessor processor)	Removes a previously added KeyEventPostProcessor from this KeyboardFocusManager's post-processor chain.
void	removePropertyChangeListener(PropertyChangeListener listener)	Removes a PropertyChangeListener from the listener list.
void	removePropertyChangeListener(String propertyName, PropertyChangeListener listener)	Removes a PropertyChangeListener from the listener list for a specific property.
void	removeVetoableChangeListener(String propertyName, VetoableChangeListener listener)	Removes a VetoableChangeListener from the listener list for a specific property.
void	removeVetoableChangeListener(VetoableChangeListener listener)	Removes a VetoableChangeListener from the listener list.
static void	setCurrentKeyboardFocusManager(KeyboardFocusManager newManager)	Sets the current KeyboardFocusManager instance for the calling thread's context.
void	setDefaultFocusTraversalKeys(int id, Set<? extends AWTKeyStroke> keystrokes)	Sets the default focus traversal keys for a given traversal operation.
void	setDefaultFocusTraversalPolicy(FocusTraversalPolicy defaultPolicy)	Sets the default FocusTraversalPolicy.
protected void	setGlobalActiveWindow(Window activeWindow)	Sets the active Window.
void	setGlobalCurrentFocusCycleRoot(Container newFocusCycleRoot)	Sets the current focus cycle root.
protected void	setGlobalFocusedWindow(Window focusedWindow)	Sets the focused Window.
protected void	setGlobalFocusOwner(Component focusOwner)	Sets the focus owner.
protected void	setGlobalPermanentFocusOwner(Component permanentFocusOwner)	Sets the permanent focus owner.
void	upFocusCycle()	Moves the focus up one focus traversal cycle from the current focus owner.
abstract void	upFocusCycle(Component aComponent)	Moves the focus up one focus traversal cycle.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FORWARD_TRAVERSAL_KEYS

public static final int FORWARD_TRAVERSAL_KEYS

The identifier for the Forward focus traversal keys.

See Also:

setDefaultFocusTraversalKeys(int, java.util.Set<? extends java.awt.AWTKeyStroke>), getDefaultFocusTraversalKeys(int), Component.setFocusTraversalKeys(int, java.util.Set<? extends java.awt.AWTKeyStroke>), Component.getFocusTraversalKeys(int), Constant Field Values

BACKWARD_TRAVERSAL_KEYS

public static final int BACKWARD_TRAVERSAL_KEYS

The identifier for the Backward focus traversal keys.

See Also:

setDefaultFocusTraversalKeys(int, java.util.Set<? extends java.awt.AWTKeyStroke>), getDefaultFocusTraversalKeys(int), Component.setFocusTraversalKeys(int, java.util.Set<? extends java.awt.AWTKeyStroke>), Component.getFocusTraversalKeys(int), Constant Field Values

UP_CYCLE_TRAVERSAL_KEYS

public static final int UP_CYCLE_TRAVERSAL_KEYS

The identifier for the Up Cycle focus traversal keys.

See Also:

setDefaultFocusTraversalKeys(int, java.util.Set<? extends java.awt.AWTKeyStroke>), getDefaultFocusTraversalKeys(int), Component.setFocusTraversalKeys(int, java.util.Set<? extends java.awt.AWTKeyStroke>), Component.getFocusTraversalKeys(int), Constant Field Values

DOWN_CYCLE_TRAVERSAL_KEYS

public static final int DOWN_CYCLE_TRAVERSAL_KEYS

The identifier for the Down Cycle focus traversal keys.

See Also:

setDefaultFocusTraversalKeys(int, java.util.Set<? extends java.awt.AWTKeyStroke>), getDefaultFocusTraversalKeys(int), Component.setFocusTraversalKeys(int, java.util.Set<? extends java.awt.AWTKeyStroke>), Component.getFocusTraversalKeys(int), Constant Field Values

Constructor Detail

KeyboardFocusManager

public KeyboardFocusManager()

Initializes a KeyboardFocusManager.

Method Detail

getCurrentKeyboardFocusManager

public static KeyboardFocusManager getCurrentKeyboardFocusManager()

Returns the current KeyboardFocusManager instance for the calling thread's context.

Returns:

this thread's context's KeyboardFocusManager

See Also:

setCurrentKeyboardFocusManager(java.awt.KeyboardFocusManager)

setCurrentKeyboardFocusManager

public static void setCurrentKeyboardFocusManager(KeyboardFocusManager newManager)
                                           throws SecurityException

Sets the current KeyboardFocusManager instance for the calling thread's context. If null is specified, then the current KeyboardFocusManager is replaced with a new instance of DefaultKeyboardFocusManager.

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

Parameters:

newManager - the new KeyboardFocusManager for this thread's context

Throws:

SecurityException - if the calling thread does not have permission to replace the current KeyboardFocusManager

See Also:

getCurrentKeyboardFocusManager(), DefaultKeyboardFocusManager

getFocusOwner

public Component getFocusOwner()

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

Returns:

the focus owner, or null if the focus owner is not a member of the calling thread's context

See Also:

getGlobalFocusOwner(), setGlobalFocusOwner(java.awt.Component)

getGlobalFocusOwner

protected Component getGlobalFocusOwner()
                                 throws SecurityException

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

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

Returns:

the focus owner

Throws:

SecurityException - if this KeyboardFocusManager is not the current KeyboardFocusManager for the calling thread's context and if the calling thread does not have "replaceKeyboardFocusManager" permission

See Also:

getFocusOwner(), setGlobalFocusOwner(java.awt.Component)

setGlobalFocusOwner

protected void setGlobalFocusOwner(Component focusOwner)
                            throws SecurityException

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

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

Parameters:

focusOwner - the focus owner

Throws:

SecurityException - if this KeyboardFocusManager is not the current KeyboardFocusManager for the calling thread's context and if the calling thread does not have "replaceKeyboardFocusManager" permission

See Also:

getFocusOwner(), getGlobalFocusOwner(), Component.requestFocus(), Component.requestFocusInWindow(), Component.isFocusable()

clearFocusOwner

public void clearFocusOwner()

Clears the focus owner at both the Java and native levels if the focus owner exists and resides in the same context as the calling thread, otherwise the method returns silently.

The focus owner component will receive a permanent FOCUS_LOST event. After this operation completes, the native windowing system will discard all user-generated KeyEvents until the user selects a new Component to receive focus, or a Component is given focus explicitly via a call to requestFocus(). This operation does not change the focused or active Windows.

Since:

1.8

See Also:

Component.requestFocus(), FocusEvent.FOCUS_LOST

clearGlobalFocusOwner

public void clearGlobalFocusOwner()
                           throws SecurityException

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

If a SecurityManager is installed, the calling thread must be granted the "replaceKeyboardFocusManager" AWTPermission. If this permission is not granted, this method will throw a SecurityException, and the current focus owner will not be cleared.

This method is intended to be used only by KeyboardFocusManager set as current KeyboardFocusManager for the calling thread's context. It is not for general client use.

Throws:

SecurityException - if the calling thread does not have "replaceKeyboardFocusManager" permission

See Also:

clearFocusOwner(), Component.requestFocus(), FocusEvent.FOCUS_LOST

getPermanentFocusOwner

public Component getPermanentFocusOwner()

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

Returns:

the permanent focus owner, or null if the permanent focus owner is not a member of the calling thread's context

See Also:

getGlobalPermanentFocusOwner(), setGlobalPermanentFocusOwner(java.awt.Component)

getGlobalPermanentFocusOwner

protected Component getGlobalPermanentFocusOwner()
                                          throws SecurityException

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

Returns:

the permanent focus owner

Throws:

SecurityException - if this KeyboardFocusManager is not the current KeyboardFocusManager for the calling thread's context and if the calling thread does not have "replaceKeyboardFocusManager" permission

See Also:

getPermanentFocusOwner(), setGlobalPermanentFocusOwner(java.awt.Component)

setGlobalPermanentFocusOwner

protected void setGlobalPermanentFocusOwner(Component permanentFocusOwner)
                                     throws SecurityException

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

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

Parameters:

permanentFocusOwner - the permanent focus owner

Throws:

SecurityException - if this KeyboardFocusManager is not the current KeyboardFocusManager for the calling thread's context and if the calling thread does not have "replaceKeyboardFocusManager" permission

See Also:

getPermanentFocusOwner(), getGlobalPermanentFocusOwner(), Component.requestFocus(), Component.requestFocusInWindow(), Component.isFocusable()

getFocusedWindow

public Window getFocusedWindow()

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

Returns:

the focused Window, or null if the focused Window is not a member of the calling thread's context

See Also:

getGlobalFocusedWindow(), setGlobalFocusedWindow(java.awt.Window)

getGlobalFocusedWindow

protected Window getGlobalFocusedWindow()
                                 throws SecurityException

Returns the focused Window, even if the calling thread is in a different context than the focused Window. The focused Window is the Window that is or contains the focus owner.

Returns:

the focused Window

Throws:

SecurityException - if this KeyboardFocusManager is not the current KeyboardFocusManager for the calling thread's context and if the calling thread does not have "replaceKeyboardFocusManager" permission

See Also:

getFocusedWindow(), setGlobalFocusedWindow(java.awt.Window)

setGlobalFocusedWindow

protected void setGlobalFocusedWindow(Window focusedWindow)
                               throws SecurityException

Sets the focused Window. The focused Window is the Window that is or contains the focus owner. The operation will be cancelled if the specified Window to focus is not a focusable Window.

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

Parameters:

focusedWindow - the focused Window

Throws:

SecurityException - if this KeyboardFocusManager is not the current KeyboardFocusManager for the calling thread's context and if the calling thread does not have "replaceKeyboardFocusManager" permission

See Also:

getFocusedWindow(), getGlobalFocusedWindow(), Component.requestFocus(), Component.requestFocusInWindow(), Window.isFocusableWindow()

getActiveWindow

public Window getActiveWindow()

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

Returns:

the active Window, or null if the active Window is not a member of the calling thread's context

See Also:

getGlobalActiveWindow(), setGlobalActiveWindow(java.awt.Window)

getGlobalActiveWindow

protected Window getGlobalActiveWindow()
                                throws SecurityException

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

Returns:

the active Window

Throws:

SecurityException - if this KeyboardFocusManager is not the current KeyboardFocusManager for the calling thread's context and if the calling thread does not have "replaceKeyboardFocusManager" permission

See Also:

getActiveWindow(), setGlobalActiveWindow(java.awt.Window)

setGlobalActiveWindow

protected void setGlobalActiveWindow(Window activeWindow)
                              throws SecurityException

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

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

Parameters:

activeWindow - the active Window

Throws:

SecurityException - if this KeyboardFocusManager is not the current KeyboardFocusManager for the calling thread's context and if the calling thread does not have "replaceKeyboardFocusManager" permission

See Also:

getActiveWindow(), getGlobalActiveWindow(), Component.requestFocus(), Component.requestFocusInWindow()

getDefaultFocusTraversalPolicy

public FocusTraversalPolicy getDefaultFocusTraversalPolicy()

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

Returns:

the default FocusTraversalPolicy. null will never be returned.

See Also:

setDefaultFocusTraversalPolicy(java.awt.FocusTraversalPolicy), Container.setFocusTraversalPolicy(java.awt.FocusTraversalPolicy), Container.getFocusTraversalPolicy()

setDefaultFocusTraversalPolicy

public void setDefaultFocusTraversalPolicy(FocusTraversalPolicy defaultPolicy)

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

Parameters:

defaultPolicy - the new, default FocusTraversalPolicy

Throws:

IllegalArgumentException - if defaultPolicy is null

See Also:

getDefaultFocusTraversalPolicy(), Container.setFocusTraversalPolicy(java.awt.FocusTraversalPolicy), Container.getFocusTraversalPolicy()

setDefaultFocusTraversalKeys

public void setDefaultFocusTraversalKeys(int id,
                                         Set<? extends AWTKeyStroke> keystrokes)

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

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

Identifier	Meaning	Default
KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS	Normal forward keyboard traversal	TAB on KEY_PRESSED, CTRL-TAB on KEY_PRESSED
KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS	Normal reverse keyboard traversal	SHIFT-TAB on KEY_PRESSED, CTRL-SHIFT-TAB on KEY_PRESSED
KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS	Go up one focus traversal cycle	none
KeyboardFocusManager.DOWN_CYCLE_TRAVERSAL_KEYS	Go down one focus traversal cycle	none

To disable a traversal key, use an empty Set; Collections.EMPTY_SET is recommended.

Using the AWTKeyStroke API, client code can specify on which of two specific KeyEvents, KEY_PRESSED or KEY_RELEASED, the focus traversal operation will occur. Regardless of which KeyEvent is specified, however, all KeyEvents related to the focus traversal key, including the associated KEY_TYPED event, will be consumed, and will not be dispatched to any Component. It is a runtime error to specify a KEY_TYPED event as mapping to a focus traversal operation, or to map the same event to multiple default focus traversal operations.

This method may throw a ClassCastException if any Object in keystrokes is not an AWTKeyStroke.

Parameters:

id - one of KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS, KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS, KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS, or KeyboardFocusManager.DOWN_CYCLE_TRAVERSAL_KEYS

keystrokes - the Set of AWTKeyStrokes for the specified operation

Throws:

IllegalArgumentException - if id is not one of KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS, KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS, KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS, or KeyboardFocusManager.DOWN_CYCLE_TRAVERSAL_KEYS, or if keystrokes is null, or if keystrokes contains null, or if any keystroke represents a KEY_TYPED event, or if any keystroke already maps to another default focus traversal operation

See Also:

getDefaultFocusTraversalKeys(int), Component.setFocusTraversalKeys(int, java.util.Set<? extends java.awt.AWTKeyStroke>), Component.getFocusTraversalKeys(int)

getDefaultFocusTraversalKeys

public Set<AWTKeyStroke> getDefaultFocusTraversalKeys(int id)

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

Parameters:

id - one of KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS, KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS, KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS, or KeyboardFocusManager.DOWN_CYCLE_TRAVERSAL_KEYS

Returns:

the Set of AWTKeyStrokes for the specified operation; the Set will be unmodifiable, and may be empty; null will never be returned

Throws:

IllegalArgumentException - if id is not one of KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS, KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS, KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS, or KeyboardFocusManager.DOWN_CYCLE_TRAVERSAL_KEYS

See Also:

setDefaultFocusTraversalKeys(int, java.util.Set<? extends java.awt.AWTKeyStroke>), Component.setFocusTraversalKeys(int, java.util.Set<? extends java.awt.AWTKeyStroke>), Component.getFocusTraversalKeys(int)

getCurrentFocusCycleRoot

public Container getCurrentFocusCycleRoot()

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

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

Returns:

the current focus cycle root, or null if the current focus cycle root is not a member of the calling thread's context

See Also:

getGlobalCurrentFocusCycleRoot(), setGlobalCurrentFocusCycleRoot(java.awt.Container)

getGlobalCurrentFocusCycleRoot

protected Container getGlobalCurrentFocusCycleRoot()
                                            throws SecurityException

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

Returns:

the current focus cycle root, or null if the current focus cycle root is not a member of the calling thread's context

Throws:

SecurityException - if this KeyboardFocusManager is not the current KeyboardFocusManager for the calling thread's context and if the calling thread does not have "replaceKeyboardFocusManager" permission

See Also:

getCurrentFocusCycleRoot(), setGlobalCurrentFocusCycleRoot(java.awt.Container)

setGlobalCurrentFocusCycleRoot

public void setGlobalCurrentFocusCycleRoot(Container newFocusCycleRoot)
                                    throws SecurityException

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

If a SecurityManager is installed, the calling thread must be granted the "replaceKeyboardFocusManager" AWTPermission. If this permission is not granted, this method will throw a SecurityException, and the current focus cycle root will not be changed.

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

Parameters:

newFocusCycleRoot - the new focus cycle root

Throws:

SecurityException - if the calling thread does not have "replaceKeyboardFocusManager" permission

See Also:

getCurrentFocusCycleRoot(), getGlobalCurrentFocusCycleRoot()

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener listener)

Adds a PropertyChangeListener to the listener list. The listener is registered for all bound properties of this class, including the following:

• whether the KeyboardFocusManager is currently managing focus for this application or applet's browser context ("managingFocus")
• the focus owner ("focusOwner")
• the permanent focus owner ("permanentFocusOwner")
• the focused Window ("focusedWindow")
• the active Window ("activeWindow")
• the default focus traversal policy ("defaultFocusTraversalPolicy")
• the Set of default FORWARD_TRAVERSAL_KEYS ("forwardDefaultFocusTraversalKeys")
• the Set of default BACKWARD_TRAVERSAL_KEYS ("backwardDefaultFocusTraversalKeys")
• the Set of default UP_CYCLE_TRAVERSAL_KEYS ("upCycleDefaultFocusTraversalKeys")
• the Set of default DOWN_CYCLE_TRAVERSAL_KEYS ("downCycleDefaultFocusTraversalKeys")
• the current focus cycle root ("currentFocusCycleRoot")

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

Parameters:

listener - the PropertyChangeListener to be added

See Also:

removePropertyChangeListener(java.beans.PropertyChangeListener), getPropertyChangeListeners(), addPropertyChangeListener(java.lang.String,java.beans.PropertyChangeListener)

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener listener)

Removes a PropertyChangeListener from the listener list. This method should be used to remove the PropertyChangeListeners that were registered for all bound properties of this class.

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

Parameters:

listener - the PropertyChangeListener to be removed

See Also:

addPropertyChangeListener(java.beans.PropertyChangeListener), getPropertyChangeListeners(), removePropertyChangeListener(java.lang.String,java.beans.PropertyChangeListener)

getPropertyChangeListeners

public PropertyChangeListener[] getPropertyChangeListeners()

Returns an array of all the property change listeners registered on this keyboard focus manager.

Returns:

all of this keyboard focus manager's PropertyChangeListeners or an empty array if no property change listeners are currently registered

Since:

1.4

See Also:

addPropertyChangeListener(java.beans.PropertyChangeListener), removePropertyChangeListener(java.beans.PropertyChangeListener), getPropertyChangeListeners(java.lang.String)

addPropertyChangeListener

public void addPropertyChangeListener(String propertyName,
                                      PropertyChangeListener listener)

Adds a PropertyChangeListener to the listener list for a specific property. The specified property may be user-defined, or one of the following:

• whether the KeyboardFocusManager is currently managing focus for this application or applet's browser context ("managingFocus")
• the focus owner ("focusOwner")
• the permanent focus owner ("permanentFocusOwner")
• the focused Window ("focusedWindow")
• the active Window ("activeWindow")
• the default focus traversal policy ("defaultFocusTraversalPolicy")
• the Set of default FORWARD_TRAVERSAL_KEYS ("forwardDefaultFocusTraversalKeys")
• the Set of default BACKWARD_TRAVERSAL_KEYS ("backwardDefaultFocusTraversalKeys")
• the Set of default UP_CYCLE_TRAVERSAL_KEYS ("upCycleDefaultFocusTraversalKeys")
• the Set of default DOWN_CYCLE_TRAVERSAL_KEYS ("downCycleDefaultFocusTraversalKeys")
• the current focus cycle root ("currentFocusCycleRoot")

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

Parameters:

propertyName - one of the property names listed above

listener - the PropertyChangeListener to be added

See Also:

addPropertyChangeListener(java.beans.PropertyChangeListener), removePropertyChangeListener(java.lang.String,java.beans.PropertyChangeListener), getPropertyChangeListeners(java.lang.String)

removePropertyChangeListener

public void removePropertyChangeListener(String propertyName,
                                         PropertyChangeListener listener)

Removes a PropertyChangeListener from the listener list for a specific property. This method should be used to remove PropertyChangeListeners that were registered for a specific bound property.

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

Parameters:

propertyName - a valid property name

listener - the PropertyChangeListener to be removed

See Also:

addPropertyChangeListener(java.lang.String,java.beans.PropertyChangeListener), getPropertyChangeListeners(java.lang.String), removePropertyChangeListener(java.beans.PropertyChangeListener)

getPropertyChangeListeners

public PropertyChangeListener[] getPropertyChangeListeners(String propertyName)

Returns an array of all the PropertyChangeListeners associated with the named property.

Returns:

all of the PropertyChangeListeners associated with the named property or an empty array if no such listeners have been added.

Since:

1.4

See Also:

addPropertyChangeListener(java.lang.String,java.beans.PropertyChangeListener), removePropertyChangeListener(java.lang.String,java.beans.PropertyChangeListener)

firePropertyChange

protected void firePropertyChange(String propertyName,
                                  Object oldValue,
                                  Object newValue)

Fires a PropertyChangeEvent in response to a change in a bound property. The event will be delivered to all registered PropertyChangeListeners. No event will be delivered if oldValue and newValue are the same.

Parameters:

propertyName - the name of the property that has changed

oldValue - the property's previous value

newValue - the property's new value

addVetoableChangeListener

public void addVetoableChangeListener(VetoableChangeListener listener)

Adds a VetoableChangeListener to the listener list. The listener is registered for all vetoable properties of this class, including the following:

• the focus owner ("focusOwner")
• the permanent focus owner ("permanentFocusOwner")
• the focused Window ("focusedWindow")
• the active Window ("activeWindow")

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

Parameters:

listener - the VetoableChangeListener to be added

See Also:

removeVetoableChangeListener(java.beans.VetoableChangeListener), getVetoableChangeListeners(), addVetoableChangeListener(java.lang.String,java.beans.VetoableChangeListener)

removeVetoableChangeListener

public void removeVetoableChangeListener(VetoableChangeListener listener)

Removes a VetoableChangeListener from the listener list. This method should be used to remove the VetoableChangeListeners that were registered for all vetoable properties of this class.

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

Parameters:

listener - the VetoableChangeListener to be removed

See Also:

addVetoableChangeListener(java.beans.VetoableChangeListener), getVetoableChangeListeners(), removeVetoableChangeListener(java.lang.String,java.beans.VetoableChangeListener)

getVetoableChangeListeners

public VetoableChangeListener[] getVetoableChangeListeners()

Returns an array of all the vetoable change listeners registered on this keyboard focus manager.

Returns:

all of this keyboard focus manager's VetoableChangeListeners or an empty array if no vetoable change listeners are currently registered

Since:

1.4

See Also:

addVetoableChangeListener(java.beans.VetoableChangeListener), removeVetoableChangeListener(java.beans.VetoableChangeListener), getVetoableChangeListeners(java.lang.String)

addVetoableChangeListener

public void addVetoableChangeListener(