1: /* ContainerOrderFocusTraversalPolicy.java -- 2: Copyright (C) 2002, 2005 Free Software Foundation, Inc. 3: 4: This file is part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2, or (at your option) 9: any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; see the file COPYING. If not, write to the 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 USA. 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: 39: package java.awt; 40: 41: import java.io.Serializable; 42: 43: /** 44: * ContainerOrderFocusTraversalPolicy defines a focus traversal order 45: * based on the order in which Components were packed in a Container. 46: * This policy performs a pre-order traversal of the Component 47: * hierarchy starting from a given focus cycle root. Portions of the 48: * hierarchy that are not visible and displayable are skipped. 49: * 50: * By default, this policy transfers focus down-cycle implicitly. 51: * That is, if a forward traversal is requested on a focus cycle root 52: * and the focus cycle root has focusable children, the focus will 53: * automatically be transfered down to the lower focus cycle. 54: * 55: * The default implementation of accept accepts only Components that 56: * are visible, displayable, enabled and focusable. Derived classes 57: * can override these acceptance criteria by overriding accept. 58: * 59: * @author Michael Koch 60: * @author Thomas Fitzsimmons (fitzsim@redhat.com) 61: * @since 1.4 62: */ 63: public class ContainerOrderFocusTraversalPolicy extends FocusTraversalPolicy 64: implements Serializable 65: { 66: /** 67: * Compatible to JDK 1.4+ 68: */ 69: static final long serialVersionUID = 486933713763926351L; 70: 71: /** 72: * True if implicit down cycling is enabled. 73: */ 74: private boolean implicitDownCycleTraversal = true; 75: 76: /** 77: * Creates the <code>ContainerOrderFocusTraversalPolicy</code> object. 78: */ 79: public ContainerOrderFocusTraversalPolicy () 80: { 81: // Nothing to do here 82: } 83: 84: /** 85: * Returns the Component that should receive the focus after current. 86: * root must be a focus cycle root of current. 87: * 88: * @param root a focus cycle root of current 89: * @param current a (possibly indirect) child of root, or root itself 90: * 91: * @return the next Component in the focus traversal order for root, 92: * or null if no acceptable Component exists. 93: * 94: * @exception IllegalArgumentException If root is not a focus cycle 95: * root of current, or if either root or current is null. 96: */ 97: public Component getComponentAfter (Container root, Component current) 98: { 99: if (root == null) 100: throw new IllegalArgumentException ("focus cycle root is null"); 101: if (current == null) 102: throw new IllegalArgumentException ("current component is null"); 103: 104: if (!root.isFocusCycleRoot ()) 105: throw new IllegalArgumentException ("root is not a focus cycle root"); 106: 107: Container ancestor = current.getFocusCycleRootAncestor (); 108: Container prevAncestor = ancestor; 109: while (ancestor != root) 110: { 111: ancestor = current.getFocusCycleRootAncestor (); 112: if (ancestor == prevAncestor) 113: { 114: // We've reached the top focus cycle root ancestor. Check 115: // if it is root. 116: if (ancestor == null) 117: ancestor = root; 118: else if (ancestor != root) 119: throw new IllegalArgumentException ("the given container is not" 120: + " a focus cycle root of the" 121: + " current component"); 122: else 123: break; 124: } 125: prevAncestor = ancestor; 126: } 127: 128: // FIXME: is this the right thing to do here? It moves the context 129: // for traversal up one focus traversal cycle. We'll need a test 130: // for this. 131: if ((Component) root == current) 132: root = current.getFocusCycleRootAncestor (); 133: 134: // Check if we've reached the top of the component hierarchy. If 135: // so then we want to loop around to the first component in the 136: // focus traversal cycle. 137: if (current instanceof Window) 138: return getFirstComponent ((Container) current); 139: 140: Container parent = current.getParent (); 141: synchronized (parent.getTreeLock ()) 142: { 143: Component[] components = parent.getComponents (); 144: int componentIndex = 0; 145: int numComponents = parent.getComponentCount (); 146: 147: // Find component's index. 148: for (int i = 0; i < numComponents; i++) 149: { 150: if (components[i].equals(current)) 151: componentIndex = i; 152: } 153: 154: // Search forward for the next acceptable component. 155: // Search through all components at least one time 156: // i.e. start at componentIndex + 1 --> nComponents -1 --> 0 ---> componentIndex 157: int i = componentIndex + 1; 158: int end = numComponents - 1; 159: Component next = getNextAvailableComponent(components, i, end); 160: if (next != null) 161: return next; 162: 163: // Now check remainder of components from 0 to componentIndex 164: i = 0; 165: end = componentIndex; 166: next = getNextAvailableComponent(components, i, end); 167: if (next != null) 168: return next; 169: 170: // No focusable components after current in its Container. So go 171: // to the next Component after current's Container (parent). 172: Component result = getComponentAfter (root, parent); 173: return result; 174: } 175: } 176: 177: /** 178: * Gets the next available component in the array between the given range. 179: * 180: * @param components - the array of components. 181: * @param start - where to start 182: * @param end - where to end 183: * @return next component if found 184: */ 185: private Component getNextAvailableComponent(Component[] components, int start, int end) 186: { 187: while (start <= end) 188: { 189: Component c = components[start]; 190: 191: if (c.visible && c.isDisplayable() && c.enabled && c.focusable) 192: return c; 193: 194: if (c instanceof Container) 195: { 196: Component result = getFirstComponent((Container) c); 197: 198: if (result != null && implicitDownCycleTraversal && result.visible 199: && result.isDisplayable() && result.enabled && result.focusable) 200: return result; 201: } 202: start++; 203: } 204: 205: return null; 206: } 207: 208: /** 209: * Gets the previous available component in the array between the given range. 210: * 211: * @param components - the array of components. 212: * @param start - where to start 213: * @param end - where to end 214: * @return previous component if found 215: */ 216: Component getPrevAvailableComponent(Component[] components, int start, int end) 217: { 218: while (start >= end) 219: { 220: Component c = components[start]; 221: if (c.visible && c.isDisplayable() && c.enabled && c.focusable) 222: return c; 223: 224: if (c instanceof Container) 225: { 226: Component result = getLastComponent((Container) c); 227: 228: if (result != null 229: && (result.visible && result.isDisplayable() && result.enabled && result.focusable)) 230: return result; 231: } 232: start--; 233: } 234: return null; 235: } 236: 237: /** 238: * Returns the Component that should receive the focus before 239: * <code>current</code>. <code>root</code> must be a focus cycle root of 240: * current. 241: * 242: * @param root a focus cycle root of current 243: * @param current a (possibly indirect) child of root, or root itself 244: * @return the previous Component in the focus traversal order for root, or 245: * null if no acceptable Component exists. 246: * @exception IllegalArgumentException If root is not a focus cycle root of 247: * current, or if either root or current is null. 248: */ 249: public Component getComponentBefore (Container root, Component current) 250: { 251: if (root == null) 252: throw new IllegalArgumentException ("focus cycle root is null"); 253: if (current == null) 254: throw new IllegalArgumentException ("current component is null"); 255: 256: if (!root.isFocusCycleRoot ()) 257: throw new IllegalArgumentException ("root is not a focus cycle root"); 258: 259: Container ancestor = current.getFocusCycleRootAncestor (); 260: Container prevAncestor = ancestor; 261: while (ancestor != root) 262: { 263: ancestor = current.getFocusCycleRootAncestor (); 264: if (ancestor == prevAncestor) 265: { 266: // We've reached the top focus cycle root ancestor. Check 267: // if it is root. 268: if (ancestor == null) 269: ancestor = root; 270: else if (ancestor != root) 271: throw new IllegalArgumentException ("the given container is not" 272: + " a focus cycle root of the" 273: + " current component"); 274: else 275: break; 276: } 277: prevAncestor = ancestor; 278: } 279: 280: // FIXME: is this the right thing to do here? It moves the context 281: // for traversal up one focus traversal cycle. We'll need a test 282: // for this. 283: if ((Component) root == current) 284: root = current.getFocusCycleRootAncestor (); 285: 286: // Check if we've reached the top of the component hierarchy. If 287: // so then we want to loop around to the last component in the 288: // focus traversal cycle. 289: if (current instanceof Window) 290: return getLastComponent ((Container) current); 291: 292: Container parent = current.getParent (); 293: 294: synchronized (parent.getTreeLock ()) 295: { 296: Component[] components = parent.getComponents (); 297: int componentIndex = 0; 298: int numComponents = parent.getComponentCount (); 299: 300: // Find component's index. 301: for (int i = 0; i < numComponents; i++) 302: { 303: if (components[i] == current) 304: componentIndex = i; 305: } 306: 307: // Search through all components at least one time 308: // i.e. start at componentIndex - 1 --> 0 --> numComponents -1 ---> componentIndex 309: int i = componentIndex - 1; 310: int end = 0; 311: Component prev = getPrevAvailableComponent(components, i, end); 312: if (prev != null) 313: return prev; 314: 315: // Now check remainder of components 316: i = numComponents -1; 317: end = componentIndex; 318: prev = getPrevAvailableComponent(components, i, end); 319: if (prev != null) 320: return prev; 321: 322: // No focusable components before current in its Container. So go 323: // to the previous Component before current's Container (parent). 324: Component result = getComponentBefore (root, parent); 325: 326: return result; 327: } 328: } 329: 330: /** 331: * Returns the first Component of root that should receive the focus. 332: * 333: * @param root a focus cycle root 334: * 335: * @return the first Component in the focus traversal order for 336: * root, or null if no acceptable Component exists. 337: * 338: * @exception IllegalArgumentException If root is null. 339: */ 340: public Component getFirstComponent(Container root) 341: { 342: if (root == null) 343: throw new IllegalArgumentException (); 344: 345: if (!root.isVisible () 346: || !root.isDisplayable ()) 347: return null; 348: 349: if (accept(root)) 350: return root; 351: 352: int ncomponents = root.getComponentCount(); 353: for (int i = 0; i < ncomponents; i++) 354: { 355: Component component = root.getComponent(i); 356: if (component instanceof Container 357: && !((Container) component).isFocusCycleRoot()) 358: { 359: Component first = null; 360: Container cont = (Container) component; 361: if (cont.isFocusTraversalPolicyProvider()) 362: { 363: FocusTraversalPolicy childPol = cont.getFocusTraversalPolicy(); 364: first = childPol.getFirstComponent(cont); 365: } 366: else 367: first = getFirstComponent(cont); 368: if (first != null) 369: return first; 370: } 371: else if (accept(component)) 372: return component; 373: } 374: 375: return null; 376: } 377: 378: /** 379: * Returns the last Component of root that should receive the focus. 380: * 381: * @param root a focus cycle root 382: * 383: * @return the last Component in the focus traversal order for 384: * root, or null if no acceptable Component exists. 385: * 386: * @exception IllegalArgumentException If root is null. 387: */ 388: public Component getLastComponent (Container root) 389: { 390: if (root == null) 391: throw new IllegalArgumentException (); 392: 393: if (!root.isVisible () 394: || !root.isDisplayable ()) 395: return null; 396: 397: if (root.visible && root.isDisplayable() && root.enabled 398: && root.focusable) 399: return root; 400: 401: Component[] componentArray = root.getComponents (); 402: 403: for (int i = componentArray.length - 1; i >= 0; i--) 404: { 405: Component component = componentArray [i]; 406: 407: if (component.visible && component.isDisplayable() && component.enabled 408: && component.focusable) 409: return component; 410: 411: if (component instanceof Container) 412: { 413: Component result = getLastComponent ((Container) component); 414: 415: if (result != null && 416: result.visible && result.isDisplayable() && result.enabled 417: && result.focusable) 418: return result; 419: } 420: } 421: 422: return null; 423: } 424: 425: /** 426: * Returns the default Component of root that should receive the focus. 427: * 428: * @param root a focus cycle root 429: * 430: * @return the default Component in the focus traversal order for 431: * root, or null if no acceptable Component exists. 432: * 433: * @exception IllegalArgumentException If root is null. 434: */ 435: public Component getDefaultComponent (Container root) 436: { 437: return getFirstComponent (root); 438: } 439: 440: /** 441: * Set whether or not implicit down cycling is enabled. If it is, 442: * then initiating a forward focus traversal operation onto a focus 443: * cycle root, the focus will be implicitly transferred into the 444: * root container's focus cycle. 445: * 446: * @param value the setting for implicit down cycling 447: */ 448: public void setImplicitDownCycleTraversal (boolean value) 449: { 450: implicitDownCycleTraversal = value; 451: } 452: 453: /** 454: * Check whether or not implicit down cycling is enabled. If it is, 455: * then initiating a forward focus traversal operation onto a focus 456: * cycle root, the focus will be implicitly transferred into the 457: * root container's focus cycle. 458: * 459: * @return true if the focus will be transferred down-cycle 460: * implicitly 461: */ 462: public boolean getImplicitDownCycleTraversal () 463: { 464: return implicitDownCycleTraversal; 465: } 466: 467: /** 468: * Check whether the given Component is an acceptable target for the 469: * keyboard input focus. 470: * 471: * @param current the Component to check 472: * 473: * @return true if current is acceptable, false otherwise 474: */ 475: protected boolean accept (Component current) 476: { 477: return (current.visible 478: && current.isDisplayable () 479: && current.enabled 480: && current.focusable); 481: } 482: }