FocusTraversalPolicy


1   /*
2    * @(#)FocusTraversalPolicy.java    1.7 03/12/19
3    *
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 a
11   * particular focus cycle root are traversed. Instances can apply the policy to
12   * arbitrary focus cycle roots, allowing themselves to be shared across
13   * Containers. They do not need to be reinitialized when the focus cycle roots
14   * of a Component hierarchy change.
15   * <p>
16   * The core responsibility of a FocusTraversalPolicy is to provide algorithms
17   * determining the next and previous Components to focus when traversing
18   * forward or backward in a UI. Each FocusTraversalPolicy must also provide
19   * algorithms for determining the first, last, and default Components in a
20   * traversal cycle. First and last Components are used when normal forward and
21   * backward traversal, respectively, wraps. The default Component is the first
22   * to receive focus when traversing down into a new focus traversal cycle.
23   * A FocusTraversalPolicy can optionally provide an algorithm for determining
24   * a Window's initial Component. The initial Component is the first to receive
25   * focus when a Window is first made visible.
26   * <p>
27   * FocusTraversalPolicy takes into account <a
28   * HREF="doc-files/FocusSpec.html#FocusTraversalPolicyProviders">focus traversal
29   * policy providers</a>.  When searching for first/last/next/previous Component,
30   * if a focus traversal policy provider is encountered, its focus traversal
31   * policy is used to perform the search operation.
32   * <p>
33   * Please see
34   * <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 the
37   * <a HREF="../../java/awt/doc-files/FocusSpec.html">Focus Specification</a>
38   * for more information.
39   *
40   * @author David Mendenhall
41   * @version 1.7, 12/19/03
42   *
43   * @see Container#setFocusTraversalPolicy
44   * @see Container#getFocusTraversalPolicy
45   * @see Container#setFocusCycleRoot
46   * @see Container#isFocusCycleRoot
47   * @see Container#setFocusTraversalPolicyProvider
48   * @see Container#isFocusTraversalPolicyProvider
49   * @see KeyboardFocusManager#setDefaultFocusTraversalPolicy
50   * @see KeyboardFocusManager#getDefaultFocusTraversalPolicy
51   * @since 1.4
52   */
53  public abstract class 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 traversal
58       * policy provider.
59       *
60       * @param aContainer a focus cycle root of aComponent or focus traversal
61       *        policy provider
62       * @param aComponent a (possibly indirect) child of aContainer, or
63       *        aContainer itself
64       * @return the Component that should receive the focus after aComponent, or
65       *         null if no suitable Component can be found
66       * @throws IllegalArgumentException if aContainer is not a focus cycle
67       *         root of aComponent or a focus traversal policy provider, or if 
68       *         either aContainer or aComponent is null
69       */
70      public abstract Component   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 traversal
76       * policy provider.
77       *
78       * @param aContainer a focus cycle root of aComponent or focus traversal
79       *        policy provider
80       * @param aComponent a (possibly indirect) child of aContainer, or
81       *        aContainer itself
82       * @return the Component that should receive the focus before aComponent,
83       *         or null if no suitable Component can be found
84       * @throws IllegalArgumentException if aContainer is not a focus cycle
85       *         root of aComponent or a focus traversal policy provider, or if 
86       *         either aContainer or aComponent is null
87       */
88      public abstract Component   getComponentBefore(Container   aContainer,
89                                                   Component   aComponent);
90  
91      /**
92       * Returns the first Component in the traversal cycle. This method is used
93       * to determine the next Component to focus when traversal wraps in the
94       * forward direction.
95       *
96       * @param aContainer the focus cycle root or focus traversal policy provider
97       *        whose first Component is to be returned
98       * @return the first Component in the traversal cycle of aContainer,
99       *         or null if no suitable Component can be found
100      * @throws IllegalArgumentException if aContainer is null
101      */
102     public abstract Component   getFirstComponent(Container   aContainer);
103 
104     /**
105      * Returns the last Component in the traversal cycle. This method is used
106      * to determine the next Component to focus when traversal wraps in the
107      * reverse direction.
108      *
109      * @param aContainer the focus cycle root or focus traversal policy
110      *        provider whose last Component is to be returned
111      * @return the last Component in the traversal cycle of aContainer,
112      *         or null if no suitable Component can be found
113      * @throws IllegalArgumentException if aContainer is null
114      */
115     public abstract Component   getLastComponent(Container   aContainer);
116 
117     /**
118      * Returns the default Component to focus. This Component will be the first
119      * to receive focus when traversing down into a new focus traversal cycle
120      * rooted at aContainer.
121      *
122      * @param aContainer the focus cycle root or focus traversal policy
123      *        provider whose default Component is to be returned
124      * @return the default Component in the traversal cycle of aContainer, 
125      *         or null if no suitable Component can be found
126      * @throws IllegalArgumentException if aContainer is null
127      */
128     public abstract Component   getDefaultComponent(Container   aContainer);
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         Component   def = getDefaultComponent(window);
150         if (def == null && window.isFocusableWindow()) {
151             def = window;
152     }
153         return def;
154     }
155 }
156
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags