001: /*
002: * Copyright 2000-2005 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025: package java.awt;
026:
027: /**
028: * A FocusTraversalPolicy defines the order in which Components with a
029: * particular focus cycle root are traversed. Instances can apply the policy to
030: * arbitrary focus cycle roots, allowing themselves to be shared across
031: * Containers. They do not need to be reinitialized when the focus cycle roots
032: * of a Component hierarchy change.
033: * <p>
034: * The core responsibility of a FocusTraversalPolicy is to provide algorithms
035: * determining the next and previous Components to focus when traversing
036: * forward or backward in a UI. Each FocusTraversalPolicy must also provide
037: * algorithms for determining the first, last, and default Components in a
038: * traversal cycle. First and last Components are used when normal forward and
039: * backward traversal, respectively, wraps. The default Component is the first
040: * to receive focus when traversing down into a new focus traversal cycle.
041: * A FocusTraversalPolicy can optionally provide an algorithm for determining
042: * a Window's initial Component. The initial Component is the first to receive
043: * focus when a Window is first made visible.
044: * <p>
045: * FocusTraversalPolicy takes into account <a
046: * href="doc-files/FocusSpec.html#FocusTraversalPolicyProviders">focus traversal
047: * policy providers</a>. When searching for first/last/next/previous Component,
048: * if a focus traversal policy provider is encountered, its focus traversal
049: * policy is used to perform the search operation.
050: * <p>
051: * Please see
052: * <a href="http://java.sun.com/docs/books/tutorial/uiswing/misc/focus.html">
053: * How to Use the Focus Subsystem</a>,
054: * a section in <em>The Java Tutorial</em>, and the
055: * <a href="../../java/awt/doc-files/FocusSpec.html">Focus Specification</a>
056: * for more information.
057: *
058: * @author David Mendenhall
059: * @version 1.15, 05/05/07
060: *
061: * @see Container#setFocusTraversalPolicy
062: * @see Container#getFocusTraversalPolicy
063: * @see Container#setFocusCycleRoot
064: * @see Container#isFocusCycleRoot
065: * @see Container#setFocusTraversalPolicyProvider
066: * @see Container#isFocusTraversalPolicyProvider
067: * @see KeyboardFocusManager#setDefaultFocusTraversalPolicy
068: * @see KeyboardFocusManager#getDefaultFocusTraversalPolicy
069: * @since 1.4
070: */
071: public abstract class FocusTraversalPolicy {
072:
073: /**
074: * Returns the Component that should receive the focus after aComponent.
075: * aContainer must be a focus cycle root of aComponent or a focus traversal
076: * policy provider.
077: *
078: * @param aContainer a focus cycle root of aComponent or focus traversal
079: * policy provider
080: * @param aComponent a (possibly indirect) child of aContainer, or
081: * aContainer itself
082: * @return the Component that should receive the focus after aComponent, or
083: * null if no suitable Component can be found
084: * @throws IllegalArgumentException if aContainer is not a focus cycle
085: * root of aComponent or a focus traversal policy provider, or if
086: * either aContainer or aComponent is null
087: */
088: public abstract Component getComponentAfter(Container aContainer,
089: Component aComponent);
090:
091: /**
092: * Returns the Component that should receive the focus before aComponent.
093: * aContainer must be a focus cycle root of aComponent or a focus traversal
094: * policy provider.
095: *
096: * @param aContainer a focus cycle root of aComponent or focus traversal
097: * policy provider
098: * @param aComponent a (possibly indirect) child of aContainer, or
099: * aContainer itself
100: * @return the Component that should receive the focus before aComponent,
101: * or null if no suitable Component can be found
102: * @throws IllegalArgumentException if aContainer is not a focus cycle
103: * root of aComponent or a focus traversal policy provider, or if
104: * either aContainer or aComponent is null
105: */
106: public abstract Component getComponentBefore(Container aContainer,
107: Component aComponent);
108:
109: /**
110: * Returns the first Component in the traversal cycle. This method is used
111: * to determine the next Component to focus when traversal wraps in the
112: * forward direction.
113: *
114: * @param aContainer the focus cycle root or focus traversal policy provider
115: * whose first Component is to be returned
116: * @return the first Component in the traversal cycle of aContainer,
117: * or null if no suitable Component can be found
118: * @throws IllegalArgumentException if aContainer is null
119: */
120: public abstract Component getFirstComponent(Container aContainer);
121:
122: /**
123: * Returns the last Component in the traversal cycle. This method is used
124: * to determine the next Component to focus when traversal wraps in the
125: * reverse direction.
126: *
127: * @param aContainer the focus cycle root or focus traversal policy
128: * provider whose last Component is to be returned
129: * @return the last Component in the traversal cycle of aContainer,
130: * or null if no suitable Component can be found
131: * @throws IllegalArgumentException if aContainer is null
132: */
133: public abstract Component getLastComponent(Container aContainer);
134:
135: /**
136: * Returns the default Component to focus. This Component will be the first
137: * to receive focus when traversing down into a new focus traversal cycle
138: * rooted at aContainer.
139: *
140: * @param aContainer the focus cycle root or focus traversal policy
141: * provider whose default Component is to be returned
142: * @return the default Component in the traversal cycle of aContainer,
143: * or null if no suitable Component can be found
144: * @throws IllegalArgumentException if aContainer is null
145: */
146: public abstract Component getDefaultComponent(Container aContainer);
147:
148: /**
149: * Returns the Component that should receive the focus when a Window is
150: * made visible for the first time. Once the Window has been made visible
151: * by a call to <code>show()</code> or <code>setVisible(true)</code>, the
152: * initial Component will not be used again. Instead, if the Window loses
153: * and subsequently regains focus, or is made invisible or undisplayable
154: * and subsequently made visible and displayable, the Window's most
155: * recently focused Component will become the focus owner. The default
156: * implementation of this method returns the default Component.
157: *
158: * @param window the Window whose initial Component is to be returned
159: * @return the Component that should receive the focus when window is made
160: * visible for the first time, or null if no suitable Component can
161: * be found
162: * @see #getDefaultComponent
163: * @see Window#getMostRecentFocusOwner
164: * @throws IllegalArgumentException if window is null
165: */
166: public Component getInitialComponent(Window window) {
167: if (window == null) {
168: throw new IllegalArgumentException(
169: "window cannot be equal to null.");
170: }
171: Component def = getDefaultComponent(window);
172: if (def == null && window.isFocusableWindow()) {
173: def = window;
174: }
175: return def;
176: }
177: }
| 