bibliothek.gui.dock.control.focus
Interface FocusRequest

All Known Implementing Classes:

DefaultFocusRequest, EnsuringFocusRequest, RepeatingFocusRequest

public interface FocusRequest

A FocusRequest can be sent to the FocusController in order for a Component to gain the focus. Whether the request is granted depends on the FocusController. A FocusRequest does not necessarily need to point to a specific Component, it can also point e.g. to a Dockable telling that one of its child Components should be focused.
A FocusRequest can have a delay, meaning it will be executed not right away but at a later time. Hence it is possible for a FocusRequest to be overtaken by another request. In such a case the request that is executed first wins and cancels the other request.

Author:

Benjamin Sigg

Method Summary

boolean	acceptable(Component component) Tells whether component would be an acceptable Component to receive the focus.
Component	getComponent() Gets the Component which may receive the focus.
int	getDelay() Gets a delay in milliseconds, the FocusController will wait executing this request until the delay has passed.
DockElementRepresentative	getSource() Gets the source of this request.
FocusRequest	grant(Component component) Called once this FocusRequest is granted, this request must now call a method like Component.requestFocusInWindow() on component.
boolean	validate(FocusController controller) Invoked by controller right before this request is processed.
void	veto(FocusVetoListener.FocusVeto veto) Informs this request of the result of calling the FocusVetoListeners.

Method Detail

getDelay

int getDelay()

Gets a delay in milliseconds, the FocusController will wait executing this request until the delay has passed.

Returns:

the delay in milliseconds, can be 0

validate

boolean validate(FocusController controller)

Invoked by controller right before this request is processed. The method checks whether this request is still valid, e.g. a request may no longer be valid because it points to a Dockable that is no longer visible.

Parameters:

controller - the controller which will process this request

Returns:

true if this request is valid, false if this request is invalid and should be ignored

veto

void veto(FocusVetoListener.FocusVeto veto)

Informs this request of the result of calling the FocusVetoListeners. This method is called after validate(FocusController).

Parameters:

veto - the veto that was cast, including no veto

getSource

DockElementRepresentative getSource()

Gets the source of this request. The source may be the Dockable which receives the focus, or the Component which received a MouseEvent. The source will be used to ask the FocusVetoListeners whether to accept this request or not.

Returns:

the source of this request, may be null

getComponent

Component getComponent()

Gets the Component which may receive the focus. This is no necessarily the Component that gains the focus because the FocusStrategy may choose another Component. This Component may be not focusable, not visible, not showing, or not valid in any other respect. It is the FocusController's job to correct such issues.

Returns:

the Component which may receive the focus, can be null

acceptable

boolean acceptable(Component component)

Tells whether component would be an acceptable Component to receive the focus. This method usually is called when getComponent() returned an invalid Component (e.g. null or a component that is not focusable) and that Component gets replaced.

Parameters:

component - the component that might gain the focus

Returns:

true if this request approves on component replacing the result of getComponent()

grant

FocusRequest grant(Component component)

Called once this FocusRequest is granted, this request must now call a method like Component.requestFocusInWindow() on component.

Parameters:

component - the Component which gains the focus. Usually this Component is valid in the sense of that it is focusable, visible and showing. There are no guarantees for this properties tough.

Returns:

a new FocusRequest that will be executed. If the result of getSource() of this and of the result matches, and if the result of getComponent() is the same as component, then the FocusController will accept the request without calling neither FocusVetoListener nor FocusStrategy. In any other case the request will be treated like a completely new request. The result of this method can also be null. The result of this method can also by this.