Whether or not to perform an "implicit DownCycle" when selecting + * successor components within a focus cycle.
+ * + *When this is true, requesting the "next" component following a + * component which is a focus cycle root (and, necessarily, a container) + * will enter the focus cycle root of that container, and return its + * default focus.
+ * + *When this property is false, requesting the "next" component will + * simply advance within the containing focus cycle, subject to the + * address@hidden #comparator} order and the address@hidden #accept} judgment.
+ * + * @see #getNextFocusableComponent + */ + boolean implicitDownCycleTraversal = true; + + /** + * Creates a newSortingFocusTraversalPolicy with no
+ * comparator set.
+ */
+ protected SortingFocusTraversalPolicy()
+ {
+ // Do nothing here.
+ }
+
+ /**
+ * Creates a new SortingFocusTraversalPolicy with the given
+ * comparator set.
+ *
+ * @param the comparator to set
+ */
+ public SortingFocusTraversalPolicy(Comparator comparator)
+ {
+ this.comparator = comparator;
+ }
+
+ /**
+ * Decide whether a component is an acceptable focus owner.
+ *
+ * @param comp The component which is a candidate for focus ownership.
+ *
+ * @return true if the component is focusable, displayable, visible, and
+ * enabled; otherwise false
+ */
+ protected boolean accept(Component comp)
+ {
+ return (comp.isVisible()
+ && comp.isDisplayable()
+ && comp.isEnabled()
+ && comp.isFocusable());
+ }
+
+ /**
+ * Get the current value of the address@hidden #comparator} property.
+ *
+ * @return the current value of the property
+ *
+ * @see #setComparator
+ */
+ protected Comparator getComparator()
+ {
+ return comparator;
+ }
+
+ /**
+ * Set the current value of the address@hidden #comparator} property.
+ *
+ * @param comparator the new value of the property
+ *
+ * @see #getComparator
+ */
+ protected void setComparator(Comparator comparator)
+ {
+ this.comparator = comparator;
+ }
+
+ private TreeSet getSortedCycle(Container root, TreeSet set)
+ {
+ if (set == null)
+ set = (getComparator() == null
+ ? new TreeSet(getComparator())
+ : new TreeSet());
+
+ if (root != null)
+ {
+ Component[] comps = root.getComponents();
+ for (int i = 0; i < comps.length; ++i)
+ {
+ Component c = comps[i];
+ if (accept(c))
+ set.add(c);
+ if (c instanceof Container)
+ getSortedCycle((Container) c, set);
+ }
+ }
+ return set;
+ }
+
+ /**
+ * Return the component which follows the specified component in this
+ * focus cycle, relative to the order imposed by address@hidden
+ * #comparator}. Candidate components are only considered if they are
+ * accepted by the address@hidden #accept} method.
+ *
+ * If address@hidden #getImplicitDownCycleTraversal} is true and the
+ * comp is a focus cycle root, an "implicit DownCycle"
+ * occurs and the method returns the
+ * getDefaultComponent(comp).
+ *
+ * @param root the focus cycle root to search for a successor within
+ * @param comp the component to search for the successor of
+ *
+ * @return the component following the specified component under
+ * the specified root, or null if no such component is found
+ *
+ * @throws IllegalArgumentException if either argument is null, or
+ * if the root is not a focus cycle root of the component
+ */
+ public Component getComponentAfter(Container root,
+ Component comp)
+ {
+ if (comp == null || root == null || !comp.isFocusCycleRoot(root))
+ throw new IllegalArgumentException();
+
+ if (getImplicitDownCycleTraversal()
+ && comp instanceof Container
+ && ((Container)comp).isFocusCycleRoot())
+ {
+ return getDefaultComponent((Container) comp);
+ }
+
+ TreeSet set = getSortedCycle(root, null);
+ Iterator i = set.iterator();
+ while (i.hasNext())
+ {
+ Component c = (Component) i.next();
+ if (c != null && c.equals(comp))
+ {
+ if (i.hasNext())
+ return (Component) i.next();
+ break;
+ }
+ }
+ return null;
+ }
+
+
+ /**
+ * Return the component which precedes the specified component in this
+ * focus cycle, relative to the order imposed by address@hidden
+ * #comparator}. Candidate components are only considered if they are
+ * accepted by the address@hidden #accept} method.
+ *
+ * @param root the focus cycle root to search for a predecessor within
+ * @param comp the component to search for the predecessor of
+ *
+ * @return the component preceding the specified component under the
+ * specified root, or null if no such component is found
+ *
+ * @throws IllegalArgumentException if either argument is null, or
+ * if the root is not a focus cycle root of the component
+ */
+ public Component getComponentBefore(Container root,
+ Component comp)
+ {
+ if (comp == null || root == null || !comp.isFocusCycleRoot(root))
+ throw new IllegalArgumentException();
+ TreeSet set = getSortedCycle(root, null);
+ Iterator i = set.iterator();
+ Component prev = null;
+ while (i.hasNext())
+ {
+ Component c = (Component) i.next();
+ if (c != null && c.equals(comp))
+ break;
+ prev = c;
+ }
+ return prev;
+ }
+
+ /**
+ * Return the default component of root, which is by default
+ * the same as the first component, returned by address@hidden
+ * #getFirstComponent}.
+ *
+ * @param root the focus cycle root to return the default component of
+ *
+ * @return the default focus component for root
+ *
+ * @throws IllegalArgumentException if root is null
+ */
+ public Component getDefaultComponent(Container root)
+ {
+ return getFirstComponent(root);
+ }
+
+ /**
+ * Return the first focusable component of the focus cycle root
+ * comp under the ordering imposed by the address@hidden
+ * #comparator} property. Candidate components are only considered if
+ * they are accepted by the address@hidden #accept} method.
+ *
+ * @param root the focus cycle root to search for the first component of
+ *
+ * @return the first component under root, or null if
+ * no components are found.
+ *
+ * @throws IllegalArgumentException if root is null
+ */
+ public Component getFirstComponent(Container root)
+ {
+ if (root == null)
+ throw new IllegalArgumentException();
+ TreeSet set = getSortedCycle(root, null);
+ Iterator i = set.iterator();
+ if (i.hasNext())
+ return (Component) i.next();
+ return null;
+ }
+
+ /**
+ * Return the last focusable component of the focus cycle root
+ * comp under the ordering imposed by the address@hidden
+ * #comparator} property. Candidate components are only considered if
+ * they are accepted by the address@hidden #accept} method.
+ *
+ * @param root the focus cycle root to search for the last component of
+ *
+ * @return the last component under root, or null if
+ * no components are found.
+ *
+ * @throws IllegalArgumentException if root is null
+ */
+ public Component getLastComponent(Container root)
+ {
+ if (root == null)
+ throw new IllegalArgumentException();
+ TreeSet set = getSortedCycle(root, null);
+ Iterator i = set.iterator();
+ Component last = null;
+ while (i.hasNext())
+ last = (Component) i.next();
+ return last;
+ }
+
+ /**
+ * Return the current value of the address@hidden implicitDownCycleTraversal}
+ * property.
+ *
+ * @return the current value of the property
+ *
+ * @see setImplicitDownCycleTraversal
+ */
+ public boolean getImplicitDownCycleTraversal()
+ {
+ return implicitDownCycleTraversal;
+ }
+
+ /**
+ * Set the current value of the address@hidden implicitDownCycleTraversal}
+ * property.
+ *
+ * @param down the new value of the property
+ *
+ * @see getImplicitDownCycleTraversal
+ */
+ public void setImplicitDownCycleTraversal(boolean down)
+ {
+ implicitDownCycleTraversal = down;
+ }
+}