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 }
|