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. * 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. * <p>
  26. * FocusTraversalPolicy takes into account <a
  27. * href="doc-files/FocusSpec.html#FocusTraversalPolicyProviders">focus traversal
  28. * policy providers</a>. When searching for first/last/next/previous Component,
  29. * if a focus traversal policy provider is encountered, its focus traversal
  30. * policy is used to perform the search operation.
  31. * <p>
  32. * Please see
  33. * <a href="http://java.sun.com/docs/books/tutorial/uiswing/misc/focus.html">
  34. * How to Use the Focus Subsystem</a>,
  35. * a section in <em>The Java Tutorial</em>, and the
  36. * <a href="../../java/awt/doc-files/FocusSpec.html">Focus Specification</a>
  37. * for more information.
  38. *
  39. * @author David Mendenhall
  40. * @version 1.7, 12/19/03
  41. *
  42. * @see Container#setFocusTraversalPolicy
  43. * @see Container#getFocusTraversalPolicy
  44. * @see Container#setFocusCycleRoot
  45. * @see Container#isFocusCycleRoot
  46. * @see Container#setFocusTraversalPolicyProvider
  47. * @see Container#isFocusTraversalPolicyProvider
  48. * @see KeyboardFocusManager#setDefaultFocusTraversalPolicy
  49. * @see KeyboardFocusManager#getDefaultFocusTraversalPolicy
  50. * @since 1.4
  51. */
  52. public abstract class FocusTraversalPolicy {
  53. /**
  54. * Returns the Component that should receive the focus after aComponent.
  55. * aContainer must be a focus cycle root of aComponent or a focus traversal
  56. * policy provider.
  57. *
  58. * @param aContainer a focus cycle root of aComponent or focus traversal
  59. * policy provider
  60. * @param aComponent a (possibly indirect) child of aContainer, or
  61. * aContainer itself
  62. * @return the Component that should receive the focus after aComponent, or
  63. * null if no suitable Component can be found
  64. * @throws IllegalArgumentException if aContainer is not a focus cycle
  65. * root of aComponent or a focus traversal policy provider, or if
  66. * either aContainer or aComponent is null
  67. */
  68. public abstract Component getComponentAfter(Container aContainer,
  69. Component aComponent);
  70. /**
  71. * Returns the Component that should receive the focus before aComponent.
  72. * aContainer must be a focus cycle root of aComponent or a focus traversal
  73. * policy provider.
  74. *
  75. * @param aContainer a focus cycle root of aComponent or focus traversal
  76. * policy provider
  77. * @param aComponent a (possibly indirect) child of aContainer, or
  78. * aContainer itself
  79. * @return the Component that should receive the focus before aComponent,
  80. * or null if no suitable Component can be found
  81. * @throws IllegalArgumentException if aContainer is not a focus cycle
  82. * root of aComponent or a focus traversal policy provider, or if
  83. * either aContainer or aComponent is null
  84. */
  85. public abstract Component getComponentBefore(Container aContainer,
  86. Component aComponent);
  87. /**
  88. * Returns the first Component in the traversal cycle. This method is used
  89. * to determine the next Component to focus when traversal wraps in the
  90. * forward direction.
  91. *
  92. * @param aContainer the focus cycle root or focus traversal policy provider
  93. * whose first Component is to be returned
  94. * @return the first Component in the traversal cycle of aContainer,
  95. * or null if no suitable Component can be found
  96. * @throws IllegalArgumentException if aContainer is null
  97. */
  98. public abstract Component getFirstComponent(Container aContainer);
  99. /**
  100. * Returns the last Component in the traversal cycle. This method is used
  101. * to determine the next Component to focus when traversal wraps in the
  102. * reverse direction.
  103. *
  104. * @param aContainer the focus cycle root or focus traversal policy
  105. * provider whose last Component is to be returned
  106. * @return the last Component in the traversal cycle of aContainer,
  107. * or null if no suitable Component can be found
  108. * @throws IllegalArgumentException if aContainer is null
  109. */
  110. public abstract Component getLastComponent(Container aContainer);
  111. /**
  112. * Returns the default Component to focus. This Component will be the first
  113. * to receive focus when traversing down into a new focus traversal cycle
  114. * rooted at aContainer.
  115. *
  116. * @param aContainer the focus cycle root or focus traversal policy
  117. * provider whose default Component is to be returned
  118. * @return the default Component in the traversal cycle of aContainer,
  119. * or null if no suitable Component can be found
  120. * @throws IllegalArgumentException if aContainer is null
  121. */
  122. public abstract Component getDefaultComponent(Container aContainer);
  123. /**
  124. * Returns the Component that should receive the focus when a Window is
  125. * made visible for the first time. Once the Window has been made visible
  126. * by a call to <code>show()</code> or <code>setVisible(true)</code>, the
  127. * initial Component will not be used again. Instead, if the Window loses
  128. * and subsequently regains focus, or is made invisible or undisplayable
  129. * and subsequently made visible and displayable, the Window's most
  130. * recently focused Component will become the focus owner. The default
  131. * implementation of this method returns the default Component.
  132. *
  133. * @param window the Window whose initial Component is to be returned
  134. * @return the Component that should receive the focus when window is made
  135. * visible for the first time, or null if no suitable Component can
  136. * be found
  137. * @see #getDefaultComponent
  138. * @see Window#getMostRecentFocusOwner
  139. * @throws IllegalArgumentException if window is null
  140. */
  141. public Component getInitialComponent(Window window) {
  142. Component def = getDefaultComponent(window);
  143. if (def == null && window.isFocusableWindow()) {
  144. def = window;
  145. }
  146. return def;
  147. }
  148. }