Your browser does not support JavaScript and this site utilizes JavaScript to build content and provide links to additional information. You should either enable JavaScript in your browser settings or use a browser that supports JavaScript in order to take full advantage of this site.

1 /*2 * @(#)FocusTraversalPolicy.java 1.7 03/12/193 *4 * Copyright 2004 Sun Microsystems, Inc. All rights reserved.5 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.6 */7 package java.awt;8 9 /**10 * A FocusTraversalPolicy defines the order in which Components with a11 * particular focus cycle root are traversed. Instances can apply the policy to12 * arbitrary focus cycle roots, allowing themselves to be shared across13 * Containers. They do not need to be reinitialized when the focus cycle roots14 * of a Component hierarchy change.15 * <p>16 * The core responsibility of a FocusTraversalPolicy is to provide algorithms17 * determining the next and previous Components to focus when traversing18 * forward or backward in a UI. Each FocusTraversalPolicy must also provide19 * algorithms for determining the first, last, and default Components in a20 * traversal cycle. First and last Components are used when normal forward and21 * backward traversal, respectively, wraps. The default Component is the first22 * to receive focus when traversing down into a new focus traversal cycle.23 * A FocusTraversalPolicy can optionally provide an algorithm for determining24 * a Window's initial Component. The initial Component is the first to receive25 * focus when a Window is first made visible.26 * <p>27 * FocusTraversalPolicy takes into account <a28 * HREF="doc-files/FocusSpec.html#FocusTraversalPolicyProviders">focus traversal29 * policy providers</a>. When searching for first/last/next/previous Component,30 * if a focus traversal policy provider is encountered, its focus traversal31 * policy is used to perform the search operation.32 * <p>33 * Please see34 * <a HREF="http://java.sun.com/docs/books/tutorial/uiswing/misc/focus.html">35 * How to Use the Focus Subsystem</a>,36 * a section in <em>The Java Tutorial</em>, and the37 * <a HREF="../../java/awt/doc-files/FocusSpec.html">Focus Specification</a>38 * for more information.39 *40 * @author David Mendenhall41 * @version 1.7, 12/19/0342 *43 * @see Container#setFocusTraversalPolicy44 * @see Container#getFocusTraversalPolicy45 * @see Container#setFocusCycleRoot46 * @see Container#isFocusCycleRoot47 * @see Container#setFocusTraversalPolicyProvider48 * @see Container#isFocusTraversalPolicyProvider49 * @see KeyboardFocusManager#setDefaultFocusTraversalPolicy50 * @see KeyboardFocusManager#getDefaultFocusTraversalPolicy51 * @since 1.452 */53 publicabstractclass FocusTraversalPolicy {54 55 /**56 * Returns the Component that should receive the focus after aComponent.57 * aContainer must be a focus cycle root of aComponent or a focus traversal58 * policy provider.59 *60 * @param aContainer a focus cycle root of aComponent or focus traversal61 * policy provider62 * @param aComponent a (possibly indirect) child of aContainer, or63 * aContainer itself64 * @return the Component that should receive the focus after aComponent, or65 * null if no suitable Component can be found66 * @throws IllegalArgumentException if aContainer is not a focus cycle67 * root of aComponent or a focus traversal policy provider, or if 68 * either aContainer or aComponent is null69 */70 publicabstractComponent getComponentAfter(Container aContainer,71 Component aComponent);72 73 /**74 * Returns the Component that should receive the focus before aComponent.75 * aContainer must be a focus cycle root of aComponent or a focus traversal76 * policy provider.77 *78 * @param aContainer a focus cycle root of aComponent or focus traversal79 * policy provider80 * @param aComponent a (possibly indirect) child of aContainer, or81 * aContainer itself82 * @return the Component that should receive the focus before aComponent,83 * or null if no suitable Component can be found84 * @throws IllegalArgumentException if aContainer is not a focus cycle85 * root of aComponent or a focus traversal policy provider, or if 86 * either aContainer or aComponent is null87 */88 publicabstractComponent getComponentBefore(Container aContainer,89 Component aComponent);90 91 /**92 * Returns the first Component in the traversal cycle. This method is used93 * to determine the next Component to focus when traversal wraps in the94 * forward direction.95 *96 * @param aContainer the focus cycle root or focus traversal policy provider97 * whose first Component is to be returned98 * @return the first Component in the traversal cycle of aContainer,99 * or null if no suitable Component can be found100 * @throws IllegalArgumentException if aContainer is null101 */102 publicabstractComponent getFirstComponent(Container aContainer);103 104 /**105 * Returns the last Component in the traversal cycle. This method is used106 * to determine the next Component to focus when traversal wraps in the107 * reverse direction.108 *109 * @param aContainer the focus cycle root or focus traversal policy110 * provider whose last Component is to be returned111 * @return the last Component in the traversal cycle of aContainer,112 * or null if no suitable Component can be found113 * @throws IllegalArgumentException if aContainer is null114 */115 publicabstractComponent getLastComponent(Container aContainer);116 117 /**118 * Returns the default Component to focus. This Component will be the first119 * to receive focus when traversing down into a new focus traversal cycle120 * rooted at aContainer.121 *122 * @param aContainer the focus cycle root or focus traversal policy123 * provider whose default Component is to be returned124 * @return the default Component in the traversal cycle of aContainer, 125 * or null if no suitable Component can be found126 * @throws IllegalArgumentException if aContainer is null127 */128 publicabstractComponent getDefaultComponent(Container aContainer);129 130 /**131 * Returns the Component that should receive the focus when a Window is132 * made visible for the first time. Once the Window has been made visible133 * by a call to <code>show()</code> or <code>setVisible(true)</code>, the134 * initial Component will not be used again. Instead, if the Window loses135 * and subsequently regains focus, or is made invisible or undisplayable136 * and subsequently made visible and displayable, the Window's most137 * recently focused Component will become the focus owner. The default138 * implementation of this method returns the default Component.139 *140 * @param window the Window whose initial Component is to be returned141 * @return the Component that should receive the focus when window is made142 * visible for the first time, or null if no suitable Component can143 * be found144 * @see #getDefaultComponent145 * @see Window#getMostRecentFocusOwner146 * @throws IllegalArgumentException if window is null147 */148 publicComponent getInitialComponent(Window window) {149 Component def = getDefaultComponent(window);150 if (def == null && window.isFocusableWindow()) {151 def = window;152 }153 return def;154 }155 }156