libjava/javax/swing/SortingFocusTraversalPolicy.java

   1 /* SortingFocusTraversalPolicy.java --
   2    Copyright (C) 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., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 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 javax.swing;
  40
  41 import java.awt.Component;
  42 import java.awt.Container;
  43 import java.util.Comparator;
  44 import java.util.Iterator;
  45 import java.util.TreeSet;
  46
  47 /**
  48  * @author Graydon Hoare
  49  * @author Michael Koch
  50  *
  51  * @since 1.4
  52  */
  53 public class SortingFocusTraversalPolicy
  54   extends InternalFrameFocusTraversalPolicy
  55 {
  56   /**
  57    * The comparator used to sort elements in the focus traversal cycle
  58    * managed by this class.
  59    */
  60   Comparator comparator;
  61
  62   /**
  63    * <p>Whether or not to perform an "implicit DownCycle" when selecting
  64    * successor components within a focus cycle.</p>
  65    *
  66    * <p>When this is true, requesting the "next" component following a
  67    * component which is a focus cycle root (and, necessarily, a container)
  68    * will enter the focus cycle root of that container, and return its
  69    * default focus.</p>
  70    *
  71    * <p>When this property is false, requesting the "next" component will
  72    * simply advance within the containing focus cycle, subject to the
  73    * {@link #comparator} order and the {@link #accept} judgment.</p>
  74    *
  75    * @see #getNextFocusableComponent
  76    */
  77   boolean implicitDownCycleTraversal = true;
  78
  79   /**
  80    * Creates a new <code>SortingFocusTraversalPolicy</code> with no
  81    * comparator set.
  82    */
  83   protected SortingFocusTraversalPolicy()
  84   {
  85     // Do nothing here.
  86   }
  87
  88   /**
  89    * Creates a new <code>SortingFocusTraversalPolicy</code> with the given
  90    * comparator set.
  91    *
  92    * @param the comparator to set
  93    */
  94   public SortingFocusTraversalPolicy(Comparator comparator)
  95   {
  96     this.comparator = comparator;
  97   }
  98
  99   /**
 100    * Decide whether a component is an acceptable focus owner.
 101    *
 102    * @param comp The component which is a candidate for focus ownership.
 103    *
 104    * @return true if the component is focusable, displayable, visible, and
 105    * enabled; otherwise false
 106    */
 107   protected boolean accept(Component comp)
 108   {
 109     return (comp.isVisible()
 110             && comp.isDisplayable()
 111             && comp.isEnabled()
 112             && comp.isFocusable());
 113   }
 114
 115   /**
 116    * Get the current value of the {@link #comparator} property.
 117    *
 118    * @return the current value of the property
 119    *
 120    * @see #setComparator
 121    */
 122   protected Comparator getComparator()
 123   {
 124     return comparator;
 125   }
 126
 127   /**
 128    * Set the current value of the {@link #comparator} property.
 129    *
 130    * @param comparator the new value of the property
 131    *
 132    * @see #getComparator
 133    */
 134   protected void setComparator(Comparator comparator)
 135   {
 136     this.comparator = comparator;
 137   }
 138
 139   private TreeSet getSortedCycle(Container root, TreeSet set)
 140   {
 141     if (set == null)
 142       set = (getComparator() == null
 143              ? new TreeSet()
 144              : new TreeSet(getComparator()));
 145
 146     if (root != null)
 147       {
 148         Component[] comps = root.getComponents();
 149         for (int i = 0; i < comps.length; ++i)
 150           {
 151             Component c = comps[i];
 152             if (accept(c))
 153               set.add(c);
 154             if (c instanceof Container)
 155               getSortedCycle((Container) c, set);
 156           }
 157       }
 158     return set;
 159   }
 160
 161   /**
 162    * Return the component which follows the specified component in this
 163    * focus cycle, relative to the order imposed by {@link
 164    * #comparator}. Candidate components are only considered if they are
 165    * accepted by the {@link #accept} method.
 166    *
 167    * If {@link #getImplicitDownCycleTraversal} is <code>true</code> and the
 168    * <code>comp</code> is a focus cycle root, an "implicit DownCycle"
 169    * occurs and the method returns the
 170    * <code>getDefaultComponent(comp)</code>.
 171    *
 172    * @param root the focus cycle root to search for a successor within
 173    * @param comp the component to search for the successor of
 174    *
 175    * @return the component following the specified component under
 176    * the specified root, or null if no such component is found
 177    *
 178    * @throws IllegalArgumentException if either argument is null, or
 179    * if the root is not a focus cycle root of the component
 180    */
 181   public Component getComponentAfter(Container root,
 182                                      Component comp)
 183   {
 184     if (comp == null || root == null || !comp.isFocusCycleRoot(root))
 185       throw new IllegalArgumentException();
 186
 187     if (getImplicitDownCycleTraversal()
 188         && comp instanceof Container
 189         && ((Container)comp).isFocusCycleRoot())
 190       {
 191         return getDefaultComponent((Container) comp);
 192       }
 193
 194     TreeSet set = getSortedCycle(root, null);
 195     Iterator i = set.iterator();
 196     while (i.hasNext())
 197       {
 198         Component c = (Component) i.next();
 199         if (c != null && c.equals(comp))
 200           {
 201             if (i.hasNext())
 202               return (Component) i.next();
 203             break;
 204           }
 205       }
 206     return null;
 207   }
 208
 209
 210   /**
 211    * Return the component which precedes the specified component in this
 212    * focus cycle, relative to the order imposed by {@link
 213    * #comparator}. Candidate components are only considered if they are
 214    * accepted by the {@link #accept} method.
 215    *
 216    * @param root the focus cycle root to search for a predecessor within
 217    * @param comp the component to search for the predecessor of
 218    *
 219    * @return the component preceding the specified component under the
 220    * specified root, or null if no such component is found
 221    *
 222    * @throws IllegalArgumentException if either argument is null, or
 223    * if the root is not a focus cycle root of the component
 224    */
 225   public Component getComponentBefore(Container root,
 226                                       Component comp)
 227   {
 228     if (comp == null || root == null || !comp.isFocusCycleRoot(root))
 229       throw new IllegalArgumentException();
 230     TreeSet set = getSortedCycle(root, null);
 231     Iterator i = set.iterator();
 232     Component prev = null;
 233     while (i.hasNext())
 234       {
 235         Component c = (Component) i.next();
 236         if (c != null && c.equals(comp))
 237           break;
 238         prev = c;
 239       }
 240     return prev;
 241   }
 242
 243   /**
 244    * Return the default component of <code>root</code>, which is by default
 245    * the same as the first component, returned by {@link
 246    * #getFirstComponent}.
 247    *
 248    * @param root the focus cycle root to return the default component of
 249    *
 250    * @return the default focus component for <code>root</code>
 251    *
 252    * @throws IllegalArgumentException if root is null
 253    */
 254   public Component getDefaultComponent(Container root)
 255   {
 256     return getFirstComponent(root);
 257   }
 258
 259   /**
 260    * Return the first focusable component of the focus cycle root
 261    * <code>comp</code> under the ordering imposed by the {@link
 262    * #comparator} property. Candidate components are only considered if
 263    * they are accepted by the {@link #accept} method.
 264    *
 265    * @param root the focus cycle root to search for the first component of
 266    *
 267    * @return the first component under <code>root</code>, or null if
 268    * no components are found.
 269    *
 270    * @throws IllegalArgumentException if root is null
 271    */
 272   public Component getFirstComponent(Container root)
 273   {
 274     if (root == null)
 275       throw new IllegalArgumentException();
 276     TreeSet set = getSortedCycle(root, null);
 277     Iterator i = set.iterator();
 278     if (i.hasNext())
 279       return (Component) i.next();
 280     return null;
 281   }
 282
 283   /**
 284    * Return the last focusable component of the focus cycle root
 285    * <code>comp</code> under the ordering imposed by the {@link
 286    * #comparator} property. Candidate components are only considered if
 287    * they are accepted by the {@link #accept} method.
 288    *
 289    * @param root the focus cycle root to search for the last component of
 290    *
 291    * @return the last component under <code>root</code>, or null if
 292    * no components are found.
 293    *
 294    * @throws IllegalArgumentException if root is null
 295    */
 296   public Component getLastComponent(Container root)
 297   {
 298     if (root == null)
 299       throw new IllegalArgumentException();
 300     TreeSet set = getSortedCycle(root, null);
 301     Iterator i = set.iterator();
 302     Component last = null;
 303     while (i.hasNext())
 304       last = (Component) i.next();
 305     return last;
 306   }
 307
 308   /**
 309    * Return the current value of the {@link implicitDownCycleTraversal}
 310    * property.
 311    *
 312    * @return the current value of the property
 313    *
 314    * @see setImplicitDownCycleTraversal
 315    */
 316   public boolean getImplicitDownCycleTraversal()
 317   {
 318     return implicitDownCycleTraversal;
 319   }
 320
 321   /**
 322    * Set the current value of the {@link implicitDownCycleTraversal}
 323    * property.
 324    *
 325    * @param down the new value of the property
 326    *
 327    * @see getImplicitDownCycleTraversal
 328    */
 329   public void setImplicitDownCycleTraversal(boolean down)
 330   {
 331     implicitDownCycleTraversal = down;
 332   }
 333 }