OpenJDK 27 · java.awt.FocusTraversalPolicy · APIdia, the JavaDoc alternative

A FocusTraversalPolicy defines the order in which Components with a particular focus cycle root are traversed. Instances can apply the policy to arbitrary focus cycle roots, allowing themselves to be shared across Containers. They do not need to be reinitialized when the focus cycle roots of a Component hierarchy change.

The core responsibility of a FocusTraversalPolicy is to provide algorithms determining the next and previous Components to focus when traversing forward or backward in a UI. Each FocusTraversalPolicy must also provide algorithms for determining the first, last, and default Components in a traversal cycle. First and last Components are used when normal forward and backward traversal, respectively, wraps. The default Component is the first to receive focus when traversing down into a new focus traversal cycle. A FocusTraversalPolicy can optionally provide an algorithm for determining a Window's initial Component. The initial Component is the first to receive focus when a Window is first made visible.

FocusTraversalPolicy takes into account focus traversal policy providers. When searching for first/last/next/previous Component, if a focus traversal policy provider is encountered, its focus traversal policy is used to perform the search operation.

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

Access	Constructor and Description
protected	FocusTraversalPolicy() Constructs a `FocusTraversalPolicy`.

Method Summary

Modifier and Type	Method and Description
public abstract Component	Returns: the Component that should receive the focus after aComponent, or null if no suitable Component can be found getComponentAfter(Container a focus cycle root of aComponent or focus traversal policy provider aContainer, Component a (possibly indirect) child of aContainer, or aContainer itself aComponent) Returns the Component that should receive the focus after aComponent.
public abstract Component	Returns: the Component that should receive the focus before aComponent, or null if no suitable Component can be found getComponentBefore(Container a focus cycle root of aComponent or focus traversal policy provider aContainer, Component a (possibly indirect) child of aContainer, or aContainer itself aComponent) Returns the Component that should receive the focus before aComponent.
public abstract Component	Returns: the default Component in the traversal cycle of aContainer, or null if no suitable Component can be found getDefaultComponent(Container the focus cycle root or focus traversal policy provider whose default Component is to be returned aContainer) Returns the default Component to focus.
public abstract Component	Returns: the first Component in the traversal cycle of aContainer, or null if no suitable Component can be found getFirstComponent(Container the focus cycle root or focus traversal policy provider whose first Component is to be returned aContainer) Returns the first Component in the traversal cycle.
public Component	Returns: the Component that should receive the focus when window is made visible for the first time, or null if no suitable Component can be found getInitialComponent(Window the Window whose initial Component is to be returned window) Returns the Component that should receive the focus when a Window is made visible for the first time.
public abstract Component	Returns: the last Component in the traversal cycle of aContainer, or null if no suitable Component can be found getLastComponent(Container the focus cycle root or focus traversal policy provider whose last Component is to be returned aContainer) Returns the last Component in the traversal cycle.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Constructor Detail

FocusTraversalPolicy	back to summary
protected FocusTraversalPolicy() Constructs a `FocusTraversalPolicy`.

Method Detail

getComponentAfter	back to summary
public abstract Component getComponentAfter(Container aContainer, Component aComponent) Returns the Component that should receive the focus after aComponent. aContainer must be a focus cycle root of aComponent or a focus traversal policy provider. Parameters aContainer:Container a focus cycle root of aComponent or focus traversal policy provider aComponent:Component a (possibly indirect) child of aContainer, or aContainer itself Returns:Component the Component that should receive the focus after aComponent, or null if no suitable Component can be found Exceptions IllegalArgumentException: if aContainer is not a focus cycle root of aComponent or a focus traversal policy provider, or if either aContainer or aComponent is null

getComponentAfter

back to summary

public abstract Component getComponentAfter(Container aContainer, Component aComponent)

Returns the Component that should receive the focus after aComponent. aContainer must be a focus cycle root of aComponent or a focus traversal policy provider.

Parameters

aContainer:Container: a focus cycle root of aComponent or focus traversal policy provider
aComponent:Component: a (possibly indirect) child of aContainer, or aContainer itself

Returns:Component

the Component that should receive the focus after aComponent, or null if no suitable Component can be found

Exceptions

IllegalArgumentException:: if aContainer is not a focus cycle root of aComponent or a focus traversal policy provider, or if either aContainer or aComponent is null

getComponentBefore	back to summary
public abstract Component getComponentBefore(Container aContainer, Component aComponent) Returns the Component that should receive the focus before aComponent. aContainer must be a focus cycle root of aComponent or a focus traversal policy provider. Parameters aContainer:Container a focus cycle root of aComponent or focus traversal policy provider aComponent:Component a (possibly indirect) child of aContainer, or aContainer itself Returns:Component the Component that should receive the focus before aComponent, or null if no suitable Component can be found Exceptions IllegalArgumentException: if aContainer is not a focus cycle root of aComponent or a focus traversal policy provider, or if either aContainer or aComponent is null

getComponentBefore

back to summary

public abstract Component getComponentBefore(Container aContainer, Component aComponent)

Returns the Component that should receive the focus before aComponent. aContainer must be a focus cycle root of aComponent or a focus traversal policy provider.

Parameters

aContainer:Container: a focus cycle root of aComponent or focus traversal policy provider
aComponent:Component: a (possibly indirect) child of aContainer, or aContainer itself

Returns:Component

the Component that should receive the focus before aComponent, or null if no suitable Component can be found

Exceptions

IllegalArgumentException:: if aContainer is not a focus cycle root of aComponent or a focus traversal policy provider, or if either aContainer or aComponent is null

getDefaultComponent	back to summary
public abstract Component getDefaultComponent(Container aContainer) Returns the default Component to focus. This Component will be the first to receive focus when traversing down into a new focus traversal cycle rooted at aContainer. Parameters aContainer:Container the focus cycle root or focus traversal policy provider whose default Component is to be returned Returns:Component the default Component in the traversal cycle of aContainer, or null if no suitable Component can be found Exceptions IllegalArgumentException: if aContainer is null

getDefaultComponent

back to summary

public abstract Component getDefaultComponent(Container aContainer)

Returns the default Component to focus. This Component will be the first to receive focus when traversing down into a new focus traversal cycle rooted at aContainer.

Parameters

aContainer:Container: the focus cycle root or focus traversal policy provider whose default Component is to be returned

Returns:Component

the default Component in the traversal cycle of aContainer, or null if no suitable Component can be found

Exceptions

IllegalArgumentException:: if aContainer is null

getFirstComponent	back to summary
public abstract Component getFirstComponent(Container aContainer) Returns the first Component in the traversal cycle. This method is used to determine the next Component to focus when traversal wraps in the forward direction. Parameters aContainer:Container the focus cycle root or focus traversal policy provider whose first Component is to be returned Returns:Component the first Component in the traversal cycle of aContainer, or null if no suitable Component can be found Exceptions IllegalArgumentException: if aContainer is null

getFirstComponent

back to summary

public abstract Component getFirstComponent(Container aContainer)

Returns the first Component in the traversal cycle. This method is used to determine the next Component to focus when traversal wraps in the forward direction.

Parameters

aContainer:Container: the focus cycle root or focus traversal policy provider whose first Component is to be returned

Returns:Component

the first Component in the traversal cycle of aContainer, or null if no suitable Component can be found

Exceptions

IllegalArgumentException:: if aContainer is null

getInitialComponent back to summary

getInitialComponent	back to summary
public Component getInitialComponent(Window window) Returns the Component that should receive the focus when a Window is made visible for the first time. Once the Window has been made visible by a call to `show()` or `setVisible(true)`, the initial Component will not be used again. Instead, if the Window loses and subsequently regains focus, or is made invisible or undisplayable and subsequently made visible and displayable, the Window's most recently focused Component will become the focus owner. The default implementation of this method returns the default Component. Parameters window:Window the Window whose initial Component is to be returned Returns:Component the Component that should receive the focus when window is made visible for the first time, or null if no suitable Component can be found Exceptions IllegalArgumentException: if window is null See Also `getDefaultComponent`, `Window#getMostRecentFocusOwner`

public Component getInitialComponent(Window window)

Returns the Component that should receive the focus when a Window is made visible for the first time. Once the Window has been made visible by a call to show() or setVisible(true), the initial Component will not be used again. Instead, if the Window loses and subsequently regains focus, or is made invisible or undisplayable and subsequently made visible and displayable, the Window's most recently focused Component will become the focus owner. The default implementation of this method returns the default Component.

Parameters

window:Window: the Window whose initial Component is to be returned

Returns:Component

the Component that should receive the focus when window is made visible for the first time, or null if no suitable Component can be found

Exceptions

IllegalArgumentException:: if window is null

getLastComponent	back to summary
public abstract Component getLastComponent(Container aContainer) Returns the last Component in the traversal cycle. This method is used to determine the next Component to focus when traversal wraps in the reverse direction. Parameters aContainer:Container the focus cycle root or focus traversal policy provider whose last Component is to be returned Returns:Component the last Component in the traversal cycle of aContainer, or null if no suitable Component can be found Exceptions IllegalArgumentException: if aContainer is null

getLastComponent

back to summary

public abstract Component getLastComponent(Container aContainer)

Returns the last Component in the traversal cycle. This method is used to determine the next Component to focus when traversal wraps in the reverse direction.

Parameters

aContainer:Container: the focus cycle root or focus traversal policy provider whose last Component is to be returned

Returns:Component

the last Component in the traversal cycle of aContainer, or null if no suitable Component can be found

Exceptions

IllegalArgumentException:: if aContainer is null

public abstract Class FocusTraversalPolicy

Constructor Summary

Method Summary

Constructor Detail

Method Detail