176 lines
7.3 KiB
176 lines
7.3 KiB
/*
|
|
* Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
|
|
* ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*
|
|
*/
|
|
package java.awt;
|
|
|
|
/**
|
|
* 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.
|
|
* <p>
|
|
* 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.
|
|
* <p>
|
|
* FocusTraversalPolicy takes into account <a
|
|
* href="doc-files/FocusSpec.html#FocusTraversalPolicyProviders">focus traversal
|
|
* policy providers</a>. 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.
|
|
* <p>
|
|
* Please see
|
|
* <a href="https://docs.oracle.com/javase/tutorial/uiswing/misc/focus.html">
|
|
* How to Use the Focus Subsystem</a>,
|
|
* a section in <em>The Java Tutorial</em>, and the
|
|
* <a href="../../java/awt/doc-files/FocusSpec.html">Focus Specification</a>
|
|
* for more information.
|
|
*
|
|
* @author David Mendenhall
|
|
*
|
|
* @see Container#setFocusTraversalPolicy
|
|
* @see Container#getFocusTraversalPolicy
|
|
* @see Container#setFocusCycleRoot
|
|
* @see Container#isFocusCycleRoot
|
|
* @see Container#setFocusTraversalPolicyProvider
|
|
* @see Container#isFocusTraversalPolicyProvider
|
|
* @see KeyboardFocusManager#setDefaultFocusTraversalPolicy
|
|
* @see KeyboardFocusManager#getDefaultFocusTraversalPolicy
|
|
* @since 1.4
|
|
*/
|
|
public abstract class FocusTraversalPolicy {
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param aContainer a focus cycle root of aComponent or focus traversal
|
|
* policy provider
|
|
* @param aComponent a (possibly indirect) child of aContainer, or
|
|
* aContainer itself
|
|
* @return the Component that should receive the focus after aComponent, or
|
|
* null if no suitable Component can be found
|
|
* @throws 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
|
|
*/
|
|
public abstract Component getComponentAfter(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.
|
|
*
|
|
* @param aContainer a focus cycle root of aComponent or focus traversal
|
|
* policy provider
|
|
* @param aComponent a (possibly indirect) child of aContainer, or
|
|
* aContainer itself
|
|
* @return the Component that should receive the focus before aComponent,
|
|
* or null if no suitable Component can be found
|
|
* @throws 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
|
|
*/
|
|
public abstract Component getComponentBefore(Container aContainer,
|
|
Component aComponent);
|
|
|
|
/**
|
|
* 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.
|
|
*
|
|
* @param aContainer the focus cycle root or focus traversal policy provider
|
|
* whose first Component is to be returned
|
|
* @return the first Component in the traversal cycle of aContainer,
|
|
* or null if no suitable Component can be found
|
|
* @throws IllegalArgumentException if aContainer is null
|
|
*/
|
|
public abstract Component getFirstComponent(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.
|
|
*
|
|
* @param aContainer the focus cycle root or focus traversal policy
|
|
* provider whose last Component is to be returned
|
|
* @return the last Component in the traversal cycle of aContainer,
|
|
* or null if no suitable Component can be found
|
|
* @throws IllegalArgumentException if aContainer is null
|
|
*/
|
|
public abstract Component getLastComponent(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.
|
|
*
|
|
* @param aContainer the focus cycle root or focus traversal policy
|
|
* provider whose default Component is to be returned
|
|
* @return the default Component in the traversal cycle of aContainer,
|
|
* or null if no suitable Component can be found
|
|
* @throws IllegalArgumentException if aContainer is null
|
|
*/
|
|
public abstract Component getDefaultComponent(Container aContainer);
|
|
|
|
/**
|
|
* 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 <code>show()</code> or <code>setVisible(true)</code>, 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.
|
|
*
|
|
* @param window the Window whose initial Component is to be returned
|
|
* @return 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
|
|
* @see #getDefaultComponent
|
|
* @see Window#getMostRecentFocusOwner
|
|
* @throws IllegalArgumentException if window is null
|
|
*/
|
|
public Component getInitialComponent(Window window) {
|
|
if ( window == null ){
|
|
throw new IllegalArgumentException("window cannot be equal to null.");
|
|
}
|
|
Component def = getDefaultComponent(window);
|
|
if (def == null && window.isFocusableWindow()) {
|
|
def = window;
|
|
}
|
|
return def;
|
|
}
|
|
}
|