1 /*
2 * Copyright (c) 2000, 2003, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25 package java.awt;
26
27 import java.util.List;
28 import java.util.ArrayList;
29 import sun.util.logging.PlatformLogger;
30
31 /**
32 * A FocusTraversalPolicy that determines traversal order based on the order
33 * of child Components in a Container. From a particular focus cycle root, the
34 * policy makes a pre-order traversal of the Component hierarchy, and traverses
35 * a Container's children according to the ordering of the array returned by
36 * <code>Container.getComponents()</code>. Portions of the hierarchy that are
37 * not visible and displayable will not be searched.
38 * <p>
39 * By default, ContainerOrderFocusTraversalPolicy implicitly transfers focus
40 * down-cycle. That is, during normal forward focus traversal, the Component
41 * traversed after a focus cycle root will be the focus-cycle-root's default
42 * Component to focus. This behavior can be disabled using the
43 * <code>setImplicitDownCycleTraversal</code> method.
44 * <p>
45 * By default, methods of this class will return a Component only if it is
46 * visible, displayable, enabled, and focusable. Subclasses can modify this
47 * behavior by overriding the <code>accept</code> method.
48 * <p>
49 * This policy takes into account <a
50 * href="doc-files/FocusSpec.html#FocusTraversalPolicyProviders">focus traversal
51 * policy providers</a>. When searching for first/last/next/previous Component,
52 * if a focus traversal policy provider is encountered, its focus traversal
53 * policy is used to perform the search operation.
54 *
55 * @author David Mendenhall
56 *
57 * @see Container#getComponents
58 * @since 1.4
59 */
60 public class ContainerOrderFocusTraversalPolicy extends FocusTraversalPolicy
61 implements java.io.Serializable
62 {
63 private static final PlatformLogger log = PlatformLogger.getLogger("java.awt.ContainerOrderFocusTraversalPolicy");
64
65 final private int FORWARD_TRAVERSAL = 0;
66 final private int BACKWARD_TRAVERSAL = 1;
67
68 /*
69 * JDK 1.4 serialVersionUID
70 */
71 private static final long serialVersionUID = 486933713763926351L;
72
73 private boolean implicitDownCycleTraversal = true;
74
75 /**
76 * Used by getComponentAfter and getComponentBefore for efficiency. In
77 * order to maintain compliance with the specification of
78 * FocusTraversalPolicy, if traversal wraps, we should invoke
79 * getFirstComponent or getLastComponent. These methods may be overriden in
80 * subclasses to behave in a non-generic way. However, in the generic case,
81 * these methods will simply return the first or last Components of the
82 * sorted list, respectively. Since getComponentAfter and
83 * getComponentBefore have already built the list before determining
84 * that they need to invoke getFirstComponent or getLastComponent, the
85 * list should be reused if possible.
86 */
87 transient private Container cachedRoot;
88 transient private List<Component> cachedCycle;
89
90 /*
91 * We suppose to use getFocusTraversalCycle & getComponentIndex methods in order
92 * to divide the policy into two parts:
93 * 1) Making the focus traversal cycle.
94 * 2) Traversing the cycle.
95 * The 1st point assumes producing a list of components representing the focus
96 * traversal cycle. The two methods mentioned above should implement this logic.
97 * The 2nd point assumes implementing the common concepts of operating on the
98 * cycle: traversing back and forth, retrieving the initial/default/first/last
99 * component. These concepts are described in the AWT Focus Spec and they are
100 * applied to the FocusTraversalPolicy in general.
101 * Thus, a descendant of this policy may wish to not reimplement the logic of
102 * the 2nd point but just override the implementation of the 1st one.
103 * A striking example of such a descendant is the javax.swing.SortingFocusTraversalPolicy.
104 */
105 /*protected*/ private List<Component> getFocusTraversalCycle(Container aContainer) {
106 List<Component> cycle = new ArrayList<Component>();
107 enumerateCycle(aContainer, cycle);
108 return cycle;
109 }
110 /*protected*/ private int getComponentIndex(List<Component> cycle, Component aComponent) {
111 return cycle.indexOf(aComponent);
112 }
113
114 private void enumerateCycle(Container container, List<Component> cycle) {
115 if (!(container.isVisible() && container.isDisplayable())) {
116 return;
117 }
118
119 cycle.add(container);
120
121 Component[] components = container.getComponents();
122 for (int i = 0; i < components.length; i++) {
123 Component comp = components[i];
124 if (comp instanceof Container) {
125 Container cont = (Container)comp;
126
127 if (!cont.isFocusCycleRoot() && !cont.isFocusTraversalPolicyProvider()) {
128 enumerateCycle(cont, cycle);
129 continue;
130 }
131 }
132 cycle.add(comp);
133 }
134 }
135
136 private Container getTopmostProvider(Container focusCycleRoot, Component aComponent) {
137 Container aCont = aComponent.getParent();
138 Container ftp = null;
139 while (aCont != focusCycleRoot && aCont != null) {
140 if (aCont.isFocusTraversalPolicyProvider()) {
141 ftp = aCont;
142 }
143 aCont = aCont.getParent();
144 }
145 if (aCont == null) {
146 return null;
147 }
148 return ftp;
149 }
150
151 /*
152 * Checks if a new focus cycle takes place and returns a Component to traverse focus to.
153 * @param comp a possible focus cycle root or policy provider
154 * @param traversalDirection the direction of the traversal
155 * @return a Component to traverse focus to if {@code comp} is a root or provider
156 * and implicit down-cycle is set, otherwise {@code null}
157 */
158 private Component getComponentDownCycle(Component comp, int traversalDirection) {
159 Component retComp = null;
160
161 if (comp instanceof Container) {
162 Container cont = (Container)comp;
163
164 if (cont.isFocusCycleRoot()) {
165 if (getImplicitDownCycleTraversal()) {
166 retComp = cont.getFocusTraversalPolicy().getDefaultComponent(cont);
167
168 if (retComp != null && log.isLoggable(PlatformLogger.Level.FINE)) {
169 log.fine("### Transfered focus down-cycle to " + retComp +
170 " in the focus cycle root " + cont);
171 }
172 } else {
173 return null;
174 }
175 } else if (cont.isFocusTraversalPolicyProvider()) {
176 retComp = (traversalDirection == FORWARD_TRAVERSAL ?
177 cont.getFocusTraversalPolicy().getDefaultComponent(cont) :
178 cont.getFocusTraversalPolicy().getLastComponent(cont));
179
180 if (retComp != null && log.isLoggable(PlatformLogger.Level.FINE)) {
181 log.fine("### Transfered focus to " + retComp + " in the FTP provider " + cont);
182 }
183 }
184 }
185 return retComp;
186 }
187
188 /**
189 * Returns the Component that should receive the focus after aComponent.
190 * aContainer must be a focus cycle root of aComponent or a focus traversal policy provider.
191 * <p>
192 * By default, ContainerOrderFocusTraversalPolicy implicitly transfers
193 * focus down-cycle. That is, during normal forward focus traversal, the
194 * Component traversed after a focus cycle root will be the focus-cycle-
195 * root's default Component to focus. This behavior can be disabled using
196 * the <code>setImplicitDownCycleTraversal</code> method.
197 * <p>
198 * If aContainer is <a href="doc-files/FocusSpec.html#FocusTraversalPolicyProviders">focus
199 * traversal policy provider</a>, the focus is always transferred down-cycle.
200 *
201 * @param aContainer a focus cycle root of aComponent or a focus traversal policy provider
202 * @param aComponent a (possibly indirect) child of aContainer, or
203 * aContainer itself
204 * @return the Component that should receive the focus after aComponent, or
205 * null if no suitable Component can be found
206 * @throws IllegalArgumentException if aContainer is not a focus cycle
207 * root of aComponent or focus traversal policy provider, or if either aContainer or
208 * aComponent is null
209 */
210 public Component getComponentAfter(Container aContainer, Component aComponent) {
211 if (log.isLoggable(PlatformLogger.Level.FINE)) {
212 log.fine("### Searching in " + aContainer + " for component after " + aComponent);
213 }
214
215 if (aContainer == null || aComponent == null) {
216 throw new IllegalArgumentException("aContainer and aComponent cannot be null");
217 }
218 if (!aContainer.isFocusTraversalPolicyProvider() && !aContainer.isFocusCycleRoot()) {
219 throw new IllegalArgumentException("aContainer should be focus cycle root or focus traversal policy provider");
220
221 } else if (aContainer.isFocusCycleRoot() && !aComponent.isFocusCycleRoot(aContainer)) {
222 throw new IllegalArgumentException("aContainer is not a focus cycle root of aComponent");
223 }
224
225 synchronized(aContainer.getTreeLock()) {
226
227 if (!(aContainer.isVisible() && aContainer.isDisplayable())) {
228 return null;
229 }
230
231 // Before all the ckecks below we first see if it's an FTP provider or a focus cycle root.
232 // If it's the case just go down cycle (if it's set to "implicit").
233 Component comp = getComponentDownCycle(aComponent, FORWARD_TRAVERSAL);
234 if (comp != null) {
235 return comp;
236 }
237
238 // See if the component is inside of policy provider.
239 Container provider = getTopmostProvider(aContainer, aComponent);
240 if (provider != null) {
241 if (log.isLoggable(PlatformLogger.Level.FINE)) {
242 log.fine("### Asking FTP " + provider + " for component after " + aComponent);
243 }
244
245 // FTP knows how to find component after the given. We don't.
246 FocusTraversalPolicy policy = provider.getFocusTraversalPolicy();
247 Component afterComp = policy.getComponentAfter(provider, aComponent);
248
249 // Null result means that we overstepped the limit of the FTP's cycle.
250 // In that case we must quit the cycle, otherwise return the component found.
251 if (afterComp != null) {
252 if (log.isLoggable(PlatformLogger.Level.FINE)) {
253 log.fine("### FTP returned " + afterComp);
254 }
255 return afterComp;
256 }
257 aComponent = provider;
258 }
259
260 List<Component> cycle = getFocusTraversalCycle(aContainer);
261
262 if (log.isLoggable(PlatformLogger.Level.FINE)) {
263 log.fine("### Cycle is " + cycle + ", component is " + aComponent);
264 }
265
266 int index = getComponentIndex(cycle, aComponent);
267
268 if (index < 0) {
269 if (log.isLoggable(PlatformLogger.Level.FINE)) {
270 log.fine("### Didn't find component " + aComponent + " in a cycle " + aContainer);
271 }
272 return getFirstComponent(aContainer);
273 }
274
275 for (index++; index < cycle.size(); index++) {
276 comp = cycle.get(index);
277 if (accept(comp)) {
278 return comp;
279 } else if ((comp = getComponentDownCycle(comp, FORWARD_TRAVERSAL)) != null) {
280 return comp;
281 }
282 }
283
284 if (aContainer.isFocusCycleRoot()) {
285 this.cachedRoot = aContainer;
286 this.cachedCycle = cycle;
287
288 comp = getFirstComponent(aContainer);
289
290 this.cachedRoot = null;
291 this.cachedCycle = null;
292
293 return comp;
294 }
295 }
296 return null;
297 }
298
299 /**
300 * Returns the Component that should receive the focus before aComponent.
301 * aContainer must be a focus cycle root of aComponent or a <a
302 * href="doc-files/FocusSpec.html#FocusTraversalPolicyProviders">focus traversal policy
303 * provider</a>.
304 *
305 * @param aContainer a focus cycle root of aComponent or focus traversal policy provider
306 * @param aComponent a (possibly indirect) child of aContainer, or
307 * aContainer itself
308 * @return the Component that should receive the focus before aComponent,
309 * or null if no suitable Component can be found
310 * @throws IllegalArgumentException if aContainer is not a focus cycle
311 * root of aComponent or focus traversal policy provider, or if either aContainer or
312 * aComponent is null
313 */
314 public Component getComponentBefore(Container aContainer, Component aComponent) {
315 if (aContainer == null || aComponent == null) {
316 throw new IllegalArgumentException("aContainer and aComponent cannot be null");
317 }
318 if (!aContainer.isFocusTraversalPolicyProvider() && !aContainer.isFocusCycleRoot()) {
319 throw new IllegalArgumentException("aContainer should be focus cycle root or focus traversal policy provider");
320
321 } else if (aContainer.isFocusCycleRoot() && !aComponent.isFocusCycleRoot(aContainer)) {
322 throw new IllegalArgumentException("aContainer is not a focus cycle root of aComponent");
323 }
324
325 synchronized(aContainer.getTreeLock()) {
326
327 if (!(aContainer.isVisible() && aContainer.isDisplayable())) {
328 return null;
329 }
330
331 // See if the component is inside of policy provider.
332 Container provider = getTopmostProvider(aContainer, aComponent);
333 if (provider != null) {
334 if (log.isLoggable(PlatformLogger.Level.FINE)) {
335 log.fine("### Asking FTP " + provider + " for component after " + aComponent);
336 }
337
338 // FTP knows how to find component after the given. We don't.
339 FocusTraversalPolicy policy = provider.getFocusTraversalPolicy();
340 Component beforeComp = policy.getComponentBefore(provider, aComponent);
341
342 // Null result means that we overstepped the limit of the FTP's cycle.
343 // In that case we must quit the cycle, otherwise return the component found.
344 if (beforeComp != null) {
345 if (log.isLoggable(PlatformLogger.Level.FINE)) {
346 log.fine("### FTP returned " + beforeComp);
347 }
348 return beforeComp;
349 }
350 aComponent = provider;
351
352 // If the provider is traversable it's returned.
353 if (accept(aComponent)) {
354 return aComponent;
355 }
356 }
357
358 List<Component> cycle = getFocusTraversalCycle(aContainer);
359
360 if (log.isLoggable(PlatformLogger.Level.FINE)) {
361 log.fine("### Cycle is " + cycle + ", component is " + aComponent);
362 }
363
364 int index = getComponentIndex(cycle, aComponent);
365
366 if (index < 0) {
367 if (log.isLoggable(PlatformLogger.Level.FINE)) {
368 log.fine("### Didn't find component " + aComponent + " in a cycle " + aContainer);
369 }
370 return getLastComponent(aContainer);
371 }
372
373 Component comp = null;
374 Component tryComp = null;
375
376 for (index--; index>=0; index--) {
377 comp = cycle.get(index);
378 if (comp != aContainer && (tryComp = getComponentDownCycle(comp, BACKWARD_TRAVERSAL)) != null) {
379 return tryComp;
380 } else if (accept(comp)) {
381 return comp;
382 }
383 }
384
385 if (aContainer.isFocusCycleRoot()) {
386 this.cachedRoot = aContainer;
387 this.cachedCycle = cycle;
388
389 comp = getLastComponent(aContainer);
390
391 this.cachedRoot = null;
392 this.cachedCycle = null;
393
394 return comp;
395 }
396 }
397 return null;
398 }
399
400 /**
401 * Returns the first Component in the traversal cycle. This method is used
402 * to determine the next Component to focus when traversal wraps in the
403 * forward direction.
404 *
405 * @param aContainer the focus cycle root or focus traversal policy provider whose first
406 * Component is to be returned
407 * @return the first Component in the traversal cycle of aContainer,
408 * or null if no suitable Component can be found
409 * @throws IllegalArgumentException if aContainer is null
410 */
411 public Component getFirstComponent(Container aContainer) {
412 List<Component> cycle;
413
414 if (log.isLoggable(PlatformLogger.Level.FINE)) {
415 log.fine("### Getting first component in " + aContainer);
416 }
417 if (aContainer == null) {
418 throw new IllegalArgumentException("aContainer cannot be null");
419
420 }
421
422 synchronized(aContainer.getTreeLock()) {
423
424 if (!(aContainer.isVisible() && aContainer.isDisplayable())) {
425 return null;
426 }
427
428 if (this.cachedRoot == aContainer) {
429 cycle = this.cachedCycle;
430 } else {
431 cycle = getFocusTraversalCycle(aContainer);
432 }
433
434 if (cycle.size() == 0) {
435 if (log.isLoggable(PlatformLogger.Level.FINE)) {
436 log.fine("### Cycle is empty");
437 }
438 return null;
439 }
440 if (log.isLoggable(PlatformLogger.Level.FINE)) {
441 log.fine("### Cycle is " + cycle);
442 }
443
444 for (Component comp : cycle) {
445 if (accept(comp)) {
446 return comp;
447 } else if (comp != aContainer &&
448 (comp = getComponentDownCycle(comp, FORWARD_TRAVERSAL)) != null)
449 {
450 return comp;
451 }
452 }
453 }
454 return null;
455 }
456
457 /**
458 * Returns the last Component in the traversal cycle. This method is used
459 * to determine the next Component to focus when traversal wraps in the
460 * reverse direction.
461 *
462 * @param aContainer the focus cycle root or focus traversal policy provider whose last
463 * Component is to be returned
464 * @return the last Component in the traversal cycle of aContainer,
465 * or null if no suitable Component can be found
466 * @throws IllegalArgumentException if aContainer is null
467 */
468 public Component getLastComponent(Container aContainer) {
469 List<Component> cycle;
470 if (log.isLoggable(PlatformLogger.Level.FINE)) {
471 log.fine("### Getting last component in " + aContainer);
472 }
473
474 if (aContainer == null) {
475 throw new IllegalArgumentException("aContainer cannot be null");
476 }
477
478 synchronized(aContainer.getTreeLock()) {
479
480 if (!(aContainer.isVisible() && aContainer.isDisplayable())) {
481 return null;
482 }
483
484 if (this.cachedRoot == aContainer) {
485 cycle = this.cachedCycle;
486 } else {
487 cycle = getFocusTraversalCycle(aContainer);
488 }
489
490 if (cycle.size() == 0) {
491 if (log.isLoggable(PlatformLogger.Level.FINE)) {
492 log.fine("### Cycle is empty");
493 }
494 return null;
495 }
496 if (log.isLoggable(PlatformLogger.Level.FINE)) {
497 log.fine("### Cycle is " + cycle);
498 }
499
500 for (int i= cycle.size() - 1; i >= 0; i--) {
501 Component comp = cycle.get(i);
502 if (accept(comp)) {
503 return comp;
504 } else if (comp instanceof Container && comp != aContainer) {
505 Container cont = (Container)comp;
506 if (cont.isFocusTraversalPolicyProvider()) {
507 return cont.getFocusTraversalPolicy().getLastComponent(cont);
508 }
509 }
510 }
511 }
512 return null;
513 }
514
515 /**
516 * Returns the default Component to focus. This Component will be the first
517 * to receive focus when traversing down into a new focus traversal cycle
518 * rooted at aContainer. The default implementation of this method
519 * returns the same Component as <code>getFirstComponent</code>.
520 *
521 * @param aContainer the focus cycle root or focus traversal policy provider whose default
522 * Component is to be returned
523 * @return the default Component in the traversal cycle of aContainer,
524 * or null if no suitable Component can be found
525 * @see #getFirstComponent
526 * @throws IllegalArgumentException if aContainer is null
527 */
528 public Component getDefaultComponent(Container aContainer) {
529 return getFirstComponent(aContainer);
530 }
531
532 /**
533 * Sets whether this ContainerOrderFocusTraversalPolicy transfers focus
534 * down-cycle implicitly. If <code>true</code>, during normal forward focus
535 * traversal, the Component traversed after a focus cycle root will be the
536 * focus-cycle-root's default Component to focus. If <code>false</code>,
537 * the next Component in the focus traversal cycle rooted at the specified
538 * focus cycle root will be traversed instead. The default value for this
539 * property is <code>true</code>.
540 *
541 * @param implicitDownCycleTraversal whether this
542 * ContainerOrderFocusTraversalPolicy transfers focus down-cycle
543 * implicitly
544 * @see #getImplicitDownCycleTraversal
545 * @see #getFirstComponent
546 */
547 public void setImplicitDownCycleTraversal(boolean implicitDownCycleTraversal) {
548 this.implicitDownCycleTraversal = implicitDownCycleTraversal;
549 }
550
551 /**
552 * Returns whether this ContainerOrderFocusTraversalPolicy transfers focus
553 * down-cycle implicitly. If <code>true</code>, during normal forward focus
554 * traversal, the Component traversed after a focus cycle root will be the
555 * focus-cycle-root's default Component to focus. If <code>false</code>,
556 * the next Component in the focus traversal cycle rooted at the specified
557 * focus cycle root will be traversed instead.
558 *
559 * @return whether this ContainerOrderFocusTraversalPolicy transfers focus
560 * down-cycle implicitly
561 * @see #setImplicitDownCycleTraversal
562 * @see #getFirstComponent
563 */
564 public boolean getImplicitDownCycleTraversal() {
565 return implicitDownCycleTraversal;
566 }
567
568 /**
569 * Determines whether a Component is an acceptable choice as the new
570 * focus owner. By default, this method will accept a Component if and
571 * only if it is visible, displayable, enabled, and focusable.
572 *
573 * @param aComponent the Component whose fitness as a focus owner is to
574 * be tested
575 * @return <code>true</code> if aComponent is visible, displayable,
576 * enabled, and focusable; <code>false</code> otherwise
577 */
578 protected boolean accept(Component aComponent) {
579 if (!aComponent.canBeFocusOwner()) {
580 return false;
581 }
582
583 // Verify that the Component is recursively enabled. Disabling a
584 // heavyweight Container disables its children, whereas disabling
585 // a lightweight Container does not.
586 if (!(aComponent instanceof Window)) {
587 for (Container enableTest = aComponent.getParent();
588 enableTest != null;
589 enableTest = enableTest.getParent())
590 {
591 if (!(enableTest.isEnabled() || enableTest.isLightweight())) {
592 return false;
593 }
594 if (enableTest instanceof Window) {
595 break;
596 }
597 }
598 }
599
600 return true;
601 }
602 }
--- EOF ---