1. /*
  2. * @(#)FocusTraversalPolicy.java 1.4 03/01/23
  3. *
  4. * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package java.awt;
  8. /**
  9. * A FocusTraversalPolicy defines the order in which Components with a
  10. * particular focus cycle root are traversed. Instances can apply the policy to
  11. * arbitrary focus cycle roots, allowing themselves to be shared across
  12. * Containers. They do not need to be reinitialized when the focus cycle roots
  13. * of a Component hierarchy change.
  14. * <p>
  15. * The core responsibility of a FocusTraversalPolicy is to provide algorithms
  16. * determining the next and previous Components to focus when traversing
  17. * forward or backward in a UI. Each FocusTraversalPolicy must also provide
  18. * algorithms for determining the first, last, and default Components in a
  19. * traversal cycle. First and last Components are used when normal forward and
  20. * backward traversal, respectively, wraps. The default Component is the first
  21. * to receive focus when traversing down into a new focus traversal cycle.
  22. * A FocusTraversalPolicy can optionally provide an algorithm for determining
  23. * a Window's initial Component. The initial Component is the first to receive
  24. * focus when a Window is first made visible.
  25. *
  26. * @author David Mendenhall
  27. * @version 1.4, 01/23/03
  28. *
  29. * @see Container#setFocusTraversalPolicy
  30. * @see Container#getFocusTraversalPolicy
  31. * @see KeyboardFocusManager#setDefaultFocusTraversalPolicy
  32. * @see KeyboardFocusManager#getDefaultFocusTraversalPolicy
  33. * @since 1.4
  34. */
  35. public abstract class FocusTraversalPolicy {
  36. /**
  37. * Returns the Component that should receive the focus after aComponent.
  38. * focusCycleRoot must be a focus cycle root of aComponent.
  39. *
  40. * @param focusCycleRoot a focus cycle root of aComponent
  41. * @param aComponent a (possibly indirect) child of focusCycleRoot, or
  42. * focusCycleRoot itself
  43. * @return the Component that should receive the focus after aComponent, or
  44. * null if no suitable Component can be found
  45. * @throws IllegalArgumentException if focusCycleRoot is not a focus cycle
  46. * root of aComponent, or if either focusCycleRoot or aComponent is
  47. * null
  48. */
  49. public abstract Component getComponentAfter(Container focusCycleRoot,
  50. Component aComponent);
  51. /**
  52. * Returns the Component that should receive the focus before aComponent.
  53. * focusCycleRoot must be a focus cycle root of aComponent.
  54. *
  55. * @param focusCycleRoot a focus cycle root of aComponent
  56. * @param aComponent a (possibly indirect) child of focusCycleRoot, or
  57. * focusCycleRoot itself
  58. * @return the Component that should receive the focus before aComponent,
  59. * or null if no suitable Component can be found
  60. * @throws IllegalArgumentException if focusCycleRoot is not a focus cycle
  61. * root of aComponent, or if either focusCycleRoot or aComponent is
  62. * null
  63. */
  64. public abstract Component getComponentBefore(Container focusCycleRoot,
  65. Component aComponent);
  66. /**
  67. * Returns the first Component in the traversal cycle. This method is used
  68. * to determine the next Component to focus when traversal wraps in the
  69. * forward direction.
  70. *
  71. * @param focusCycleRoot the focus cycle root whose first Component is to
  72. * be returned
  73. * @return the first Component in the traversal cycle when focusCycleRoot
  74. * is the focus cycle root, or null if no suitable Component can be
  75. * found
  76. * @throws IllegalArgumentException if focusCycleRoot is null
  77. */
  78. public abstract Component getFirstComponent(Container focusCycleRoot);
  79. /**
  80. * Returns the last Component in the traversal cycle. This method is used
  81. * to determine the next Component to focus when traversal wraps in the
  82. * reverse direction.
  83. *
  84. * @param focusCycleRoot the focus cycle root whose last Component is to be
  85. * returned
  86. * @return the last Component in the traversal cycle when focusCycleRoot is
  87. * the focus cycle root, or null if no suitable Component can be
  88. * found
  89. * @throws IllegalArgumentException if focusCycleRoot is null
  90. */
  91. public abstract Component getLastComponent(Container focusCycleRoot);
  92. /**
  93. * Returns the default Component to focus. This Component will be the first
  94. * to receive focus when traversing down into a new focus traversal cycle
  95. * rooted at focusCycleRoot.
  96. *
  97. * @param focusCycleRoot the focus cycle root whose default Component is to
  98. * be returned
  99. * @return the default Component in the traversal cycle when focusCycleRoot
  100. * is the focus cycle root, or null if no suitable Component can
  101. * be found
  102. * @throws IllegalArgumentException if focusCycleRoot is null
  103. */
  104. public abstract Component getDefaultComponent(Container focusCycleRoot);
  105. /**
  106. * Returns the Component that should receive the focus when a Window is
  107. * made visible for the first time. Once the Window has been made visible
  108. * by a call to <code>show()</code> or <code>setVisible(true)</code>, the
  109. * initial Component will not be used again. Instead, if the Window loses
  110. * and subsequently regains focus, or is made invisible or undisplayable
  111. * and subsequently made visible and displayable, the Window's most
  112. * recently focused Component will become the focus owner. The default
  113. * implementation of this method returns the default Component.
  114. *
  115. * @param window the Window whose initial Component is to be returned
  116. * @return the Component that should receive the focus when window is made
  117. * visible for the first time, or null if no suitable Component can
  118. * be found
  119. * @see #getDefaultComponent
  120. * @see Window#getMostRecentFocusOwner
  121. * @throws IllegalArgumentException if window is null
  122. */
  123. public Component getInitialComponent(Window window) {
  124. Component def = getDefaultComponent(window);
  125. if (def == null && window.isFocusableWindow()) {
  126. def = window;
  127. }
  128. return def;
  129. }
  130. }