Java > Open Source Codes > java > awt > ContainerOrderFocusTraversalPolicy


1 /*
2  * @(#)ContainerOrderFocusTraversalPolicy.java 1.8 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 import java.util.logging.*;
10
11 /**
12  * A FocusTraversalPolicy that determines traversal order based on the order
13  * of child Components in a Container. From a particular focus cycle root, the
14  * policy makes a pre-order traversal of the Component hierarchy, and traverses
15  * a Container's children according to the ordering of the array returned by
16  * <code>Container.getComponents()</code>. Portions of the hierarchy that are
17  * not visible and displayable will not be searched.
18  * <p>
19  * By default, ContainerOrderFocusTraversalPolicy implicitly transfers focus
20  * down-cycle. That is, during normal forward focus traversal, the Component
21  * traversed after a focus cycle root will be the focus-cycle-root's default
22  * Component to focus. This behavior can be disabled using the
23  * <code>setImplicitDownCycleTraversal</code> method.
24  * <p>
25  * By default, methods of this class with return a Component only if it is
26  * visible, displayable, enabled, and focusable. Subclasses can modify this
27  * behavior by overriding the <code>accept</code> method.
28  * <p>
29  * This policy takes into account <a
30  * HREF="doc-files/FocusSpec.html#FocusTraversalPolicyProviders">focus traversal
31  * policy providers</a>. When searching for first/last/next/previous Component,
32  * if a focus traversal policy provider is encountered, its focus traversal
33  * policy is used to perform the search operation.
34  *
35  * @author David Mendenhall
36  * @version 1.8, 12/19/03
37  *
38  * @see Container#getComponents
39  * @since 1.4
40  */
41 public class ContainerOrderFocusTraversalPolicy extends FocusTraversalPolicy
42     implements java.io.Serializable
43 {
44     private static final MutableBoolean found = new MutableBoolean();
45
46     private static final Logger log = Logger.getLogger("java.awt.ContainerOrderFocusTraversalPolicy");
47
48     /*
49      * JDK 1.4 serialVersionUID
50      */
51     private static final long serialVersionUID = 486933713763926351L;
52
53     private boolean implicitDownCycleTraversal = true;
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 policy provider.
58      * <p>
59      * By default, ContainerOrderFocusTraversalPolicy implicitly transfers
60      * focus down-cycle. That is, during normal forward focus traversal, the
61      * Component traversed after a focus cycle root will be the focus-cycle-
62      * root's default Component to focus. This behavior can be disabled using
63      * the <code>setImplicitDownCycleTraversal</code> method.
64      * <p>
65      * If aContainer is <a HREF="doc-files/FocusSpec.html#FocusTraversalPolicyProviders">focus
66      * traversal policy provider</a>, the focus is always transferred down-cycle.
67      *
68      * @param aContainer a focus cycle root of aComponent or a focus traversal policy provider
69      * @param aComponent a (possibly indirect) child of aContainer, or
70      * aContainer itself
71      * @return the Component that should receive the focus after aComponent, or
72      * null if no suitable Component can be found
73      * @throws IllegalArgumentException if aContainer is not a focus cycle
74      * root of aComponent or focus traversal policy provider, or if either aContainer or
75      * aComponent is null
76      */
77     public Component getComponentAfter(Container aContainer,
78                                        Component aComponent) {
79         if (log.isLoggable(Level.FINE)) log.fine("Looking for next component in " + aContainer + " for " + aComponent);
80         if (aContainer == null || aComponent == null) {
81             throw new IllegalArgumentException ("aContainer and aComponent cannot be null");
82         }
83         if (!aContainer.isFocusTraversalPolicyProvider() && !aContainer.isFocusCycleRoot()) {
84             throw new IllegalArgumentException ("aContainer should be focus cycle root or focus traversal policy provider");
85         } else if (aContainer.isFocusCycleRoot() && !aComponent.isFocusCycleRoot(aContainer)) {
86             throw new IllegalArgumentException ("aContainer is not a focus cycle root of aComponent");
87         }
88
89         synchronized(aContainer.getTreeLock()) {
90             found.value = false;
91             Component retval = getComponentAfter(aContainer, aComponent,
92                                                  found);
93             if (retval != null) {
94                 if (log.isLoggable(Level.FINE)) log.fine("After component is " + retval);
95                 return retval;
96             } else if (found.value) {
97                 if (log.isLoggable(Level.FINE)) log.fine("Didn't find next component in " + aContainer + " - falling back to the first ");
98                 return getFirstComponent(aContainer);
99             } else {
100                 if (log.isLoggable(Level.FINE)) log.fine("After component is null");
101                 return null;
102             }
103         }
104     }
105
106     private Component getComponentAfter(Container aContainer,
107                                         Component aComponent,
108                                         MutableBoolean found) {
109         if (!(aContainer.isVisible() && aContainer.isDisplayable())) {
110         return null;
111     }
112
113         if (found.value) {
114             if (accept(aContainer)) {
115                 return aContainer;
116             }
117         } else if (aContainer == aComponent) {
118             found.value = true;
119         }
120
121         for (int i = 0; i < aContainer.ncomponents; i++) {
122             Component comp = aContainer.component[i];
123             if ((comp instanceof Container ) &&
124                 !((Container )comp).isFocusCycleRoot()) {
125                 Component retval = null;
126                 if (((Container )comp).isFocusTraversalPolicyProvider()) {
127                     if (log.isLoggable(Level.FINE)) log.fine("Entering FTP " + comp);
128                     Container cont = (Container ) comp;
129                     FocusTraversalPolicy policy = cont.getFocusTraversalPolicy();
130                     if (log.isLoggable(Level.FINE)) log.fine("FTP contains " + aComponent + ": " + cont.isAncestorOf(aComponent));
131                     if (found.value) {
132                         retval = policy.getDefaultComponent(cont);
133                         if (log.isLoggable(Level.FINE)) log.fine("Used FTP for getting default component: " + retval);
134                     } else {
135                         found.value = cont.isAncestorOf(aComponent);
136                         if (found.value) {
137                             if (aComponent == policy.getLastComponent(cont)) {
138                             // Reached last component, going to wrap - should switch to next provider
139 retval = null;
140                             } else {
141                                 retval = policy.getComponentAfter(cont, aComponent);
142                                 if (log.isLoggable(Level.FINE)) log.fine("FTP found next for the component : " + retval);
143                             }
144                         }
145                     }
146                 } else {
147                     retval = getComponentAfter((Container )comp,
148                                                      aComponent,
149                                                      found);
150                 }
151                 if (retval != null) {
152                     return retval;
153                 }
154             } else if (found.value) {
155                 if (accept(comp)) {
156                     return comp;
157                 }
158             } else if (comp == aComponent) {
159                 found.value = true;
160             }
161
162         if (found.value &&
163         getImplicitDownCycleTraversal() &&
164         (comp instanceof Container ) &&
165         ((Container )comp).isFocusCycleRoot())
166         {
167         Container cont = (Container )comp;
168         Component retval = cont.getFocusTraversalPolicy().
169             getDefaultComponent(cont);
170         if (retval != null) {
171             return retval;
172         }
173         }
174         }
175
176         return null;
177     }
178
179     /**
180      * Returns the Component that should receive the focus before aComponent.
181      * aContainer must be a focus cycle root of aComponent or a <a
182      * HREF="doc-files/FocusSpec.html#FocusTraversalPolicyProviders">focus traversal policy
183      * provider</a>.
184      *
185      * @param aContainer a focus cycle root of aComponent or focus traversal policy provider
186      * @param aComponent a (possibly indirect) child of aContainer, or
187      * aContainer itself
188      * @return the Component that should receive the focus before aComponent,
189      * or null if no suitable Component can be found
190      * @throws IllegalArgumentException if aContainer is not a focus cycle
191      * root of aComponent or focus traversal policy provider, or if either aContainer or
192      * aComponent is null
193      */
194     public Component getComponentBefore(Container aContainer,
195                                         Component aComponent) {
196         if (aContainer == null || aComponent == null) {
197             throw new IllegalArgumentException ("aContainer and aComponent cannot be null");
198         }
199         if (!aContainer.isFocusTraversalPolicyProvider() && !aContainer.isFocusCycleRoot()) {
200             throw new IllegalArgumentException ("aContainer should be focus cycle root or focus traversal policy provider");
201         } else if (aContainer.isFocusCycleRoot() && !aComponent.isFocusCycleRoot(aContainer)) {
202             throw new IllegalArgumentException ("aContainer is not a focus cycle root of aComponent");
203         }
204         synchronized(aContainer.getTreeLock()) {
205             found.value = false;
206             Component retval = getComponentBefore(aContainer, aComponent,
207                                                   found);
208             if (retval != null) {
209                 if (log.isLoggable(Level.FINE)) log.fine("Before component is " + retval);
210                 return retval;
211             } else if (found.value) {
212                 if (log.isLoggable(Level.FINE)) log.fine("Didn't find before component in " + aContainer + " - falling back to the first ");
213                 return getLastComponent(aContainer);
214             } else {
215                 if (log.isLoggable(Level.FINE)) log.fine("Before component is null");
216                 return null;
217             }
218         }
219     }
220
221     private Component getComponentBefore(Container aContainer,
222                                          Component aComponent,
223                                          MutableBoolean found) {
224         if (!(aContainer.isVisible() && aContainer.isDisplayable())) {
225         return null;
226     }
227
228         for (int i = aContainer.ncomponents - 1; i >= 0; i--) {
229             Component comp = aContainer.component[i];
230         if (comp == aComponent) {
231         found.value = true;
232         } else if ((comp instanceof Container ) &&
233                 !((Container )comp).isFocusCycleRoot()) {
234                 Component retval = null;
235                 if (((Container )comp).isFocusTraversalPolicyProvider()) {
236                     if (log.isLoggable(Level.FINE)) log.fine("Entering FTP " + comp);
237                     Container cont = (Container ) comp;
238                     FocusTraversalPolicy policy = cont.getFocusTraversalPolicy();
239                     if (log.isLoggable(Level.FINE)) log.fine("FTP contains " + aComponent + ": " + cont.isAncestorOf(aComponent));
240                     if (found.value) {
241                         retval = policy.getLastComponent(cont);
242                         if (log.isLoggable(Level.FINE)) log.fine("Used FTP for getting last component: " + retval);
243                     } else {
244                         found.value = cont.isAncestorOf(aComponent);
245                         if (found.value) {
246                             if (aComponent == policy.getFirstComponent(cont)) {
247                                 retval = null;
248                             } else {
249                                 retval = policy.getComponentBefore(cont, aComponent);
250                                 if (log.isLoggable(Level.FINE)) log.fine("FTP found previous for the component : " + retval);
251                             }
252                         }
253                     }
254                 } else {
255                     retval = getComponentBefore((Container )comp,
256                                                       aComponent,
257                                                       found);
258                 }
259                 if (retval != null) {
260                     return retval;
261                 }
262             } else if (found.value) {
263                 if (accept(comp)) {
264                     return comp;
265                 }
266             }
267         }
268
269         if (found.value) {
270             if (accept(aContainer)) {
271                 return aContainer;
272             }
273         } else if (aContainer == aComponent) {
274             found.value = true;
275         }
276
277         return null;
278     }
279
280     /**
281      * Returns the first Component in the traversal cycle. This method is used
282      * to determine the next Component to focus when traversal wraps in the
283      * forward direction.
284      *
285      * @param aContainer the focus cycle root or focus traversal policy provider whose first
286      * Component is to be returned
287      * @return the first Component in the traversal cycle of aContainer,
288      * or null if no suitable Component can be found
289      * @throws IllegalArgumentException if aContainer is null
290      */
291     public Component getFirstComponent(Container aContainer) {
292         if (aContainer == null) {
293             throw new IllegalArgumentException ("aContainer cannot be null");
294         }
295
296         synchronized(aContainer.getTreeLock()) {
297             if (!(aContainer.isVisible() &&
298                   aContainer.isDisplayable()))
299         {
300                 return null;
301             }
302
303             if (accept(aContainer)) {
304                 return aContainer;
305             }
306
307             for (int i = 0; i < aContainer.ncomponents; i++) {
308                 Component comp = aContainer.component[i];
309         if (comp instanceof Container &&
310             !((Container )comp).isFocusCycleRoot())
311         {
312                     Component retval = null;
313                     Container cont = (Container )comp;
314                     if (cont.isFocusTraversalPolicyProvider()) {
315                         FocusTraversalPolicy policy = cont.getFocusTraversalPolicy();
316                         retval = policy.getDefaultComponent(cont);
317                     } else {
318                         retval = getFirstComponent((Container )comp);
319                     }
320             if (retval != null) {
321                 return retval;
322             }
323         } else if (accept(comp)) {
324             return comp;
325         }
326             }
327         }
328
329         return null;
330     }
331
332     /**
333      * Returns the last Component in the traversal cycle. This method is used
334      * to determine the next Component to focus when traversal wraps in the
335      * reverse direction.
336      *
337      * @param aContainer the focus cycle root or focus traversal policy provider whose last
338      * Component is to be returned
339      * @return the last Component in the traversal cycle of aContainer,
340      * or null if no suitable Component can be found
341      * @throws IllegalArgumentException if aContainer is null
342      */
343     public Component getLastComponent(Container aContainer) {
344         if (aContainer == null) {
345             throw new IllegalArgumentException ("aContainer cannot be null");
346         }
347         if (log.isLoggable(Level.FINE)) log.fine("Looking for the last component in " + aContainer);
348
349         synchronized(aContainer.getTreeLock()) {
350             if (!(aContainer.isVisible() &&
351                   aContainer.isDisplayable()))
352         {
353                 return null;
354             }
355
356             for (int i = aContainer.ncomponents - 1; i >= 0; i--) {
357                 Component comp = aContainer.component[i];
358         if (comp instanceof Container &&
359             !((Container )comp).isFocusCycleRoot())
360         {
361                     Component retval = null;
362                     Container cont = (Container )comp;
363                     if (cont.isFocusTraversalPolicyProvider()) {
364                         if (log.isLoggable(Level.FINE)) log.fine("\tEntering FTP " + cont);
365                         FocusTraversalPolicy policy = cont.getFocusTraversalPolicy();
366                         retval = policy.getLastComponent(cont);
367                     } else {
368                         if (log.isLoggable(Level.FINE)) log.fine("\tEntering sub-container");
369                         retval = getLastComponent((Container )comp);
370                     }
371             if (retval != null) {
372                         if (log.isLoggable(Level.FINE)) log.fine("\tFound last component : " + retval);
373                 return retval;
374             }
375         } else if (accept(comp)) {
376             return comp;
377         }
378             }
379
380             if (accept(aContainer)) {
381                 return aContainer;
382             }
383         }
384
385         return null;
386     }
387
388     /**
389      * Returns the default Component to focus. This Component will be the first
390      * to receive focus when traversing down into a new focus traversal cycle
391      * rooted at aContainer. The default implementation of this method
392      * returns the same Component as <code>getFirstComponent</code>.
393      *
394      * @param aContainer the focus cycle root or focus traversal policy provider whose default
395      * Component is to be returned
396      * @return the default Component in the traversal cycle of aContainer,
397      * or null if no suitable Component can be found
398      * @see #getFirstComponent
399      * @throws IllegalArgumentException if aContainer is null
400      */
401     public Component getDefaultComponent(Container aContainer) {
402         return getFirstComponent(aContainer);
403     }
404
405     /**
406      * Sets whether this ContainerOrderFocusTraversalPolicy transfers focus
407      * down-cycle implicitly. If <code>true</code>, during normal forward focus
408      * traversal, the Component traversed after a focus cycle root will be the
409      * focus-cycle-root's default Component to focus. If <code>false</code>,
410      * the next Component in the focus traversal cycle rooted at the specified
411      * focus cycle root will be traversed instead. The default value for this
412      * property is <code>true</code>.
413      *
414      * @param implicitDownCycleTraversal whether this
415      * ContainerOrderFocusTraversalPolicy transfers focus down-cycle
416      * implicitly
417      * @see #getImplicitDownCycleTraversal
418      * @see #getFirstComponent
419      */
420     public void setImplicitDownCycleTraversal(boolean
421                           implicitDownCycleTraversal) {
422     this.implicitDownCycleTraversal = implicitDownCycleTraversal;
423     }
424
425     /**
426      * Returns whether this ContainerOrderFocusTraversalPolicy transfers focus
427      * down-cycle implicitly. If <code>true</code>, during normal forward focus
428      * traversal, the Component traversed after a focus cycle root will be the
429      * focus-cycle-root's default Component to focus. If <code>false</code>,
430      * the next Component in the focus traversal cycle rooted at the specified
431      * focus cycle root will be traversed instead.
432      *
433      * @return whether this ContainerOrderFocusTraversalPolicy transfers focus
434      * down-cycle implicitly
435      * @see #setImplicitDownCycleTraversal
436      * @see #getFirstComponent
437      */
438     public boolean getImplicitDownCycleTraversal() {
439     return implicitDownCycleTraversal;
440     }
441
442     /**
443      * Determines whether a Component is an acceptable choice as the new
444      * focus owner. By default, this method will accept a Component if and
445      * only if it is visible, displayable, enabled, and focusable.
446      *
447      * @param aComponent the Component whose fitness as a focus owner is to
448      * be tested
449      * @return <code>true</code> if aComponent is visible, displayable,
450      * enabled, and focusable; <code>false</code> otherwise
451      */
452     protected boolean accept(Component aComponent) {
453     if (!(aComponent.isVisible() && aComponent.isDisplayable() &&
454           aComponent.isFocusable() && aComponent.isEnabled())) {
455         return false;
456     }
457
458     // Verify that the Component is recursively enabled. Disabling a
459 // heavyweight Container disables its children, whereas disabling
460 // a lightweight Container does not.
461 if (!(aComponent instanceof Window )) {
462         for (Container enableTest = aComponent.getParent();
463          enableTest != null;
464          enableTest = enableTest.getParent())
465         {
466         if (!(enableTest.isEnabled() || enableTest.isLightweight())) {
467             return false;
468         }
469         if (enableTest instanceof Window ) {
470             break;
471         }
472         }
473     }
474
475     return true;
476     }
477
478 }
479
480
481 class MutableBoolean {
482     boolean value = false;
483 }
484

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags