001: /*
002: *
003: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
004: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
005: *
006: * This program is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU General Public License version
008: * 2 only, as published by the Free Software Foundation.
009: *
010: * This program is distributed in the hope that it will be useful, but
011: * WITHOUT ANY WARRANTY; without even the implied warranty of
012: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
013: * General Public License version 2 for more details (a copy is
014: * included at /legal/license.txt).
015: *
016: * You should have received a copy of the GNU General Public License
017: * version 2 along with this work; if not, write to the Free Software
018: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
019: * 02110-1301 USA
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
022: * Clara, CA 95054 or visit www.sun.com if you need additional
023: * information or 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: *
045: * @author David Mendenhall
046: * @version 1.4, 01/23/03
047: *
048: * @see Container#setFocusTraversalPolicy
049: * @see Container#getFocusTraversalPolicy
050: * @see KeyboardFocusManager#setDefaultFocusTraversalPolicy
051: * @see KeyboardFocusManager#getDefaultFocusTraversalPolicy
052: * @since 1.4
053: */
054: public abstract class FocusTraversalPolicy {
055: /**
056: * Returns the Component that should receive the focus after aComponent.
057: * focusCycleRoot must be a focus cycle root of aComponent.
058: *
059: * @param focusCycleRoot a focus cycle root of aComponent
060: * @param aComponent a (possibly indirect) child of focusCycleRoot, or
061: * focusCycleRoot itself
062: * @return the Component that should receive the focus after aComponent, or
063: * null if no suitable Component can be found
064: * @throws IllegalArgumentException if focusCycleRoot is not a focus cycle
065: * root of aComponent, or if either focusCycleRoot or aComponent is
066: * null
067: */
068: public abstract Component getComponentAfter(
069: Container focusCycleRoot, Component aComponent);
070:
071: /**
072: * Returns the Component that should receive the focus before aComponent.
073: * focusCycleRoot must be a focus cycle root of aComponent.
074: *
075: * @param focusCycleRoot a focus cycle root of aComponent
076: * @param aComponent a (possibly indirect) child of focusCycleRoot, or
077: * focusCycleRoot itself
078: * @return the Component that should receive the focus before aComponent,
079: * or null if no suitable Component can be found
080: * @throws IllegalArgumentException if focusCycleRoot is not a focus cycle
081: * root of aComponent, or if either focusCycleRoot or aComponent is
082: * null
083: */
084: public abstract Component getComponentBefore(
085: Container focusCycleRoot, Component aComponent);
086:
087: /**
088: * Returns the first Component in the traversal cycle. This method is used
089: * to determine the next Component to focus when traversal wraps in the
090: * forward direction.
091: *
092: * @param focusCycleRoot the focus cycle root whose first Component is to
093: * be returned
094: * @return the first Component in the traversal cycle when focusCycleRoot
095: * is the focus cycle root, or null if no suitable Component can be
096: * found
097: * @throws IllegalArgumentException if focusCycleRoot is null
098: */
099: public abstract Component getFirstComponent(Container focusCycleRoot);
100:
101: /**
102: * Returns the last Component in the traversal cycle. This method is used
103: * to determine the next Component to focus when traversal wraps in the
104: * reverse direction.
105: *
106: * @param focusCycleRoot the focus cycle root whose last Component is to be
107: * returned
108: * @return the last Component in the traversal cycle when focusCycleRoot is
109: * the focus cycle root, or null if no suitable Component can be
110: * found
111: * @throws IllegalArgumentException if focusCycleRoot is null
112: */
113: public abstract Component getLastComponent(Container focusCycleRoot);
114:
115: /**
116: * Returns the default Component to focus. This Component will be the first
117: * to receive focus when traversing down into a new focus traversal cycle
118: * rooted at focusCycleRoot.
119: *
120: * @param focusCycleRoot the focus cycle root whose default Component is to
121: * be returned
122: * @return the default Component in the traversal cycle when focusCycleRoot
123: * is the focus cycle root, or null if no suitable Component can
124: * be found
125: * @throws IllegalArgumentException if focusCycleRoot is null
126: */
127: public abstract Component getDefaultComponent(
128: Container focusCycleRoot);
129:
130: /**
131: * Returns the Component that should receive the focus when a Window is
132: * made visible for the first time. Once the Window has been made visible
133: * by a call to <code>show()</code> or <code>setVisible(true)</code>, the
134: * initial Component will not be used again. Instead, if the Window loses
135: * and subsequently regains focus, or is made invisible or undisplayable
136: * and subsequently made visible and displayable, the Window's most
137: * recently focused Component will become the focus owner. The default
138: * implementation of this method returns the default Component.
139: *
140: * @param window the Window whose initial Component is to be returned
141: * @return the Component that should receive the focus when window is made
142: * visible for the first time, or null if no suitable Component can
143: * be found
144: * @see #getDefaultComponent
145: * @see Window#getMostRecentFocusOwner
146: * @throws IllegalArgumentException if window is null
147: */
148: public Component getInitialComponent(Window window) {
149: if (window == null) {
150: throw new IllegalArgumentException(
151: "window cannot be equal to null.");
152: }
153: Component def = getDefaultComponent(window);
154: if (def == null && window.isFocusableWindow()) {
155: def = window;
156: }
157: return def;
158: }
159: }
|