001/* SortingFocusTraversalPolicy.java --
002   Copyright (C) 2005  Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package javax.swing;
040
041import java.awt.Component;
042import java.awt.Container;
043import java.util.Comparator;
044import java.util.Iterator;
045import java.util.TreeSet;
046
047/**
048 * @author Graydon Hoare
049 * @author Michael Koch
050 *
051 * @since 1.4
052 */
053public class SortingFocusTraversalPolicy
054  extends InternalFrameFocusTraversalPolicy
055{
056  /**
057   * The comparator used to sort elements in the focus traversal cycle
058   * managed by this class.
059   */
060  Comparator comparator;
061
062  /**
063   * <p>Whether or not to perform an "implicit DownCycle" when selecting
064   * successor components within a focus cycle.</p>
065   *
066   * <p>When this is true, requesting the "next" component following a
067   * component which is a focus cycle root (and, necessarily, a container)
068   * will enter the focus cycle root of that container, and return its
069   * default focus.</p>
070   *
071   * <p>When this property is false, requesting the "next" component will
072   * simply advance within the containing focus cycle, subject to the
073   * {@link #comparator} order and the {@link #accept} judgment.</p>
074   *
075   * @see #getImplicitDownCycleTraversal()
076   */
077  boolean implicitDownCycleTraversal = true;
078
079  /**
080   * Creates a new <code>SortingFocusTraversalPolicy</code> with no
081   * comparator set.
082   */
083  protected SortingFocusTraversalPolicy()
084  {
085    // Do nothing here.
086  }
087
088  /**
089   * Creates a new <code>SortingFocusTraversalPolicy</code> with the given
090   * comparator set.
091   *
092   * @param comparator the comparator to set
093   */
094  public SortingFocusTraversalPolicy(Comparator<? super Component> comparator)
095  {
096    this.comparator = comparator;
097  }
098
099  /**
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<? super Component> 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<? super Component> 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}