001/* KeyboardFocusManager.java -- manage component focusing via the keyboard
002   Copyright (C) 2002, 2004, 2005 Free Software Foundation
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 java.awt;
040
041import java.applet.Applet;
042import java.awt.FocusTraversalPolicy;
043import java.awt.event.FocusEvent;
044import java.awt.event.KeyEvent;
045import java.awt.event.WindowEvent;
046import java.beans.PropertyChangeListener;
047import java.beans.PropertyChangeSupport;
048import java.beans.PropertyVetoException;
049import java.beans.VetoableChangeListener;
050import java.beans.VetoableChangeSupport;
051import java.util.ArrayList;
052import java.util.Collection;
053import java.util.Collections;
054import java.util.HashMap;
055import java.util.HashSet;
056import java.util.Iterator;
057import java.util.List;
058import java.util.Map;
059import java.util.Set;
060
061/**
062 * The <code>KeyboardFocusManager</code> handles the focusing of
063 * windows for receiving keyboard events.  The manager handles
064 * the dispatch of all <code>FocusEvent</code>s and
065 * <code>KeyEvent</code>s, along with <code>WindowEvent</code>s
066 * relating to the focused window.  Users can use the manager
067 * to ascertain the current focus owner and fire events.
068 * <br />
069 * <br />
070 * The focus owner is the <code>Component</code> that receives
071 * key events.  The focus owner is either the currently focused
072 * window or a component within this window.
073 * <br />
074 * <br />
075 * The underlying native windowing system may denote the active
076 * window or its children with special decorations (e.g. a highlighted
077 * title bar).  The active window is always either a <code>Frame</code>
078 * or <code>Dialog</code>, and is either the currently focused
079 * window or its owner.
080 * <br />
081 * <br />
082 * Applets may be partitioned into different applet contexts, according
083 * to their code base.  In this case, each context has its own
084 * <code>KeyboardFocusManager</code>, as opposed to the global
085 * manager maintained by applets which share the same context.
086 * Each context is insulated from the others, and they don't interact.
087 * The resulting behaviour, as with context division, depends on the browser
088 * supporting the applets.  Regardless, there can only ever be
089 * one focused window, one active window and one focus owner
090 * per <code>ClassLoader</code>.
091 * <br />
092 * <br />
093 * To support this separation of focus managers, the manager instances
094 * and the internal state information is grouped by the
095 * <code>ThreadGroup</code> to which it pertains.  With respect to
096 * applets, each code base has its own <code>ThreadGroup</code>, so the
097 * isolation of each context is enforced within the manager.
098 * <br />
099 * <br />
100 * By default, the manager defines TAB and Ctrl+TAB as the
101 * forward focus traversal keys and Shift+TAB and Ctrl+Shift+TAB
102 * as the backward focus traversal keys.  No up or down cycle
103 * traversal keys are defined by default.  Traversal takes effect
104 * on the firing of a relevant <code>KEY_PRESSED</code> event.
105 * However, all other key events related to the use of the
106 * defined focus traversal key sequence are consumed and not
107 * dispatched.
108 * <br />
109 * <br />
110 * These default traversal keys come into effect on all windows
111 * for which no alternative set of keys is defined.  This also
112 * applies recursively to any child components of such a window,
113 * which define no traversal keys of their own.
114 *
115 * @author Eric Blake (ebb9@email.byu.edu)
116 * @author Thomas Fitzsimmons (fitzsim@redhat.com)
117 * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
118 * @since 1.4
119 */
120public abstract class KeyboardFocusManager
121  implements KeyEventDispatcher, KeyEventPostProcessor
122{
123  /** Identifies {@link AWTKeyStroke}s that move the focus forward in
124      the focus cycle. */
125  public static final int FORWARD_TRAVERSAL_KEYS = 0;
126
127  /** Identifies {@link AWTKeyStroke}s that move the focus backward in
128      the focus cycle. */
129  public static final int BACKWARD_TRAVERSAL_KEYS = 1;
130
131  /** Identifies {@link AWTKeyStroke}s that move the focus up to the
132      parent focus cycle root. */
133  public static final int UP_CYCLE_TRAVERSAL_KEYS = 2;
134
135  /** Identifies {@link AWTKeyStroke}s that move the focus down to the
136      child focus cycle root. */
137  public static final int DOWN_CYCLE_TRAVERSAL_KEYS = 3;
138
139  /** The set of {@link AWTKeyStroke}s that cause focus to be moved to
140      the next focusable Component in the focus cycle. */
141  private static final Set DEFAULT_FORWARD_KEYS;
142
143  /** The set of {@link AWTKeyStroke}s that cause focus to be moved to
144      the previous focusable Component in the focus cycle. */
145  private static final Set DEFAULT_BACKWARD_KEYS;
146
147  /** Populate the DEFAULT_FORWARD_KEYS and DEFAULT_BACKWARD_KEYS
148      {@link java.util.Set}s. */
149  static
150  {
151    Set s = new HashSet();
152    s.add(AWTKeyStroke.getAWTKeyStroke(KeyEvent.VK_TAB, 0));
153    s.add(AWTKeyStroke.getAWTKeyStroke(KeyEvent.VK_TAB,
154                                       KeyEvent.CTRL_DOWN_MASK));
155    DEFAULT_FORWARD_KEYS = Collections.unmodifiableSet(s);
156    s = new HashSet();
157    s.add(AWTKeyStroke.getAWTKeyStroke(KeyEvent.VK_TAB,
158                                       KeyEvent.SHIFT_DOWN_MASK));
159    s.add(AWTKeyStroke.getAWTKeyStroke(KeyEvent.VK_TAB,
160                                       KeyEvent.SHIFT_DOWN_MASK
161                                       | KeyEvent.CTRL_DOWN_MASK));
162    DEFAULT_BACKWARD_KEYS = Collections.unmodifiableSet(s);
163  }
164
165  /** The global object {@link java.util.Map}s. */
166
167  /** For security reasons, {@link java.applet.Applet}s in different
168      codebases must be insulated from one another.  Since {@link
169      KeyboardFocusManager}s have the ability to return {@link
170      Component}s from a given {@link java.applet.Applet}, each
171      codebase must have an independent {@link KeyboardFocusManager}.
172      Since each codebase has its own {@link ThreadGroup} in which its
173      {@link Applet}s run, it makes sense to partition {@link
174      KeyboardFocusManager}s according to {@link
175      java.lang.ThreadGroup}.  Thus, currentKeyboardFocusManagers is a
176      {@link java.util.Map} keyed on {@link java.lang.ThreadGroup}. */
177  private static Map currentKeyboardFocusManagers = new HashMap ();
178
179  /** {@link java.applet.Applet}s in one codebase must not be allowed
180      to access {@link Component}s in {@link java.applet.Applet}s in
181      other codebases.  To enforce this restriction, we key the
182      following {@link java.util.Map}s on {@link java.lang.ThreadGroup}s (which
183      are per-codebase).  For example, if {@link
184      java.lang.ThreadGroup} A calls {@link #setGlobalFocusOwner},
185      passing {@link Component} C, currentFocusOwners[A] is assigned
186      C, and all other currentFocusOwners values are nullified.  Then
187      if {@link java.lang.ThreadGroup} A subsequently calls {@link
188      #getGlobalFocusOwner}, it will return currentFocusOwners[A],
189      that is, {@link Component} C.  If another {@link
190      java.lang.ThreadGroup} K calls {@link #getGlobalFocusOwner}, it
191      will return currentFocusOwners[K], that is, null.
192
193      Since this is a static field, we ensure that there is only one
194      focused {@link Component} per class loader. */
195  private static Map currentFocusOwners = new HashMap ();
196
197  /** A {@link java.util.Map} keyed on {@link java.lang.ThreadGroup}s
198      that stores the {@link Component} that owns the permanent
199      keyboard focus. @see currentFocusOwners */
200  private static Map currentPermanentFocusOwners = new HashMap ();
201
202  /** A {@link java.util.Map} keyed on {@link java.lang.ThreadGroup}s
203      that stores the focused {@link Window}. @see
204      currentFocusOwners */
205  private static Map currentFocusedWindows = new HashMap ();
206
207  /** A {@link java.util.Map} keyed on {@link java.lang.ThreadGroup}s
208      that stores the active {@link Window}. @see
209      currentFocusOwners */
210  private static Map currentActiveWindows = new HashMap ();
211
212  /** A {@link java.util.Map} keyed on {@link java.lang.ThreadGroup}s
213      that stores the focus cycle root {@link Container}. @see
214      currentFocusOwners */
215  private static Map currentFocusCycleRoots = new HashMap ();
216
217  /** The default {@link FocusTraversalPolicy} that focus-managing
218      {@link Container}s will use to define their initial focus
219      traversal policy. */
220  private FocusTraversalPolicy defaultPolicy;
221
222  /** An array that stores the {@link #FORWARD_TRAVERSAL_KEYS}, {@link
223      #BACKWARD_TRAVERSAL_KEYS}, {@link #UP_CYCLE_TRAVERSAL_KEYS} and
224      {@link #DOWN_CYCLE_TRAVERSAL_KEYS} {@link AWTKeyStroke}s {@link
225      java.util.Set}s. */
226  private Set[] defaultFocusKeys = new Set[]
227  {
228    DEFAULT_FORWARD_KEYS, DEFAULT_BACKWARD_KEYS,
229    Collections.EMPTY_SET, Collections.EMPTY_SET
230  };
231
232  /**
233   * A utility class to support the handling of events relating to property changes.
234   */
235  private final PropertyChangeSupport propertyChangeSupport = new PropertyChangeSupport (this);
236
237  /**
238   * A utility class to support the handling of events relating to vetoable changes.
239   */
240  private final VetoableChangeSupport vetoableChangeSupport = new VetoableChangeSupport (this);
241
242  /** A list of {@link KeyEventDispatcher}s that process {@link
243      KeyEvent}s before they are processed the default keyboard focus
244      manager. */
245  private final ArrayList keyEventDispatchers = new ArrayList();
246
247  /** A list of {@link KeyEventPostProcessor}s that process unconsumed
248      {@link KeyEvent}s. */
249  private final ArrayList keyEventPostProcessors = new ArrayList();
250
251  /**
252   * Construct a KeyboardFocusManager.
253   */
254  public KeyboardFocusManager ()
255  {
256  }
257
258  /**
259   * Retrieve the keyboard focus manager associated with the {@link
260   * java.lang.ThreadGroup} to which the calling thread belongs.
261   *
262   * @return the keyboard focus manager associated with the current
263   * thread group
264   */
265  public static KeyboardFocusManager getCurrentKeyboardFocusManager ()
266  {
267    ThreadGroup currentGroup = Thread.currentThread ().getThreadGroup ();
268
269    if (currentKeyboardFocusManagers.get (currentGroup) == null)
270      setCurrentKeyboardFocusManager (null);
271
272    return (KeyboardFocusManager) currentKeyboardFocusManagers.get (currentGroup);
273  }
274
275  /**
276   * Set the keyboard focus manager associated with the {@link
277   * java.lang.ThreadGroup} to which the calling thread belongs.
278   *
279   * @param m the keyboard focus manager for the current thread group
280   */
281  public static void setCurrentKeyboardFocusManager (KeyboardFocusManager m)
282  {
283    SecurityManager sm = System.getSecurityManager ();
284    if (sm != null)
285      sm.checkPermission (new AWTPermission ("replaceKeyboardFocusManager"));
286
287    ThreadGroup currentGroup = Thread.currentThread ().getThreadGroup ();
288    KeyboardFocusManager manager;
289
290    if (m == null)
291      manager = new DefaultKeyboardFocusManager();
292    else
293      manager = m;
294
295    currentKeyboardFocusManagers.put (currentGroup, manager);
296  }
297
298  /**
299   * Retrieve the {@link Component} that has the keyboard focus, or
300   * null if the focus owner was not set by a thread in the current
301   * {@link java.lang.ThreadGroup}.
302   *
303   * @return the keyboard focus owner or null
304   */
305  public Component getFocusOwner ()
306  {
307    return (Component) getObject (currentFocusOwners);
308  }
309
310  /**
311   * Retrieve the {@link Component} that has the keyboard focus,
312   * regardless of whether or not it was set by a thread in the
313   * current {@link java.lang.ThreadGroup}.  If there is no temporary
314   * focus owner in effect then this method will return the same value
315   * as {@link #getGlobalPermanentFocusOwner}.
316   *
317   * @return the keyboard focus owner
318   * @throws SecurityException if this is not the keyboard focus
319   * manager associated with the current {@link java.lang.ThreadGroup}
320   */
321  protected Component getGlobalFocusOwner ()
322  {
323    return (Component) getGlobalObject(currentFocusOwners, true);
324  }
325
326  /**
327   * Set the {@link Component} that will be returned by {@link
328   * #getFocusOwner} (when it is called from the current {@link
329   * java.lang.ThreadGroup}) and {@link #getGlobalFocusOwner}.  This
330   * method does not actually transfer the keyboard focus.
331   *
332   * @param owner the Component to return from getFocusOwner and
333   * getGlobalFocusOwner
334   *
335   * @see Component#requestFocus()
336   * @see Component#requestFocusInWindow()
337   */
338  protected void setGlobalFocusOwner (Component owner)
339  {
340    if (owner == null || owner.focusable)
341      setGlobalObject (currentFocusOwners, owner, "focusOwner");
342  }
343
344  /**
345   * Clear the global focus owner and deliver a FOCUS_LOST event to
346   * the previously-focused {@link Component}.  Until another {@link
347   * Component} becomes the keyboard focus owner, key events will be
348   * discarded by top-level windows.
349   */
350  public void clearGlobalFocusOwner ()
351  {
352    synchronized (currentFocusOwners)
353      {
354        Component focusOwner = getGlobalFocusOwner ();
355        Component permanentFocusOwner = getGlobalPermanentFocusOwner ();
356
357        setGlobalFocusOwner (null);
358        setGlobalPermanentFocusOwner (null);
359
360        // Inform the old focus owner that it has lost permanent
361        // focus.
362        if (focusOwner != null)
363          {
364            // We can't cache the event queue, because of
365            // bootstrapping issues.  We need to set the default
366            // KeyboardFocusManager in EventQueue before the event
367            // queue is started.
368            EventQueue q = Toolkit.getDefaultToolkit ().getSystemEventQueue ();
369            if (focusOwner != permanentFocusOwner)
370              q.postEvent (new FocusEvent (focusOwner, FocusEvent.FOCUS_LOST, true));
371            else
372              q.postEvent (new FocusEvent (focusOwner, FocusEvent.FOCUS_LOST, false));
373          }
374
375        if (focusOwner != permanentFocusOwner)
376          {
377            EventQueue q = Toolkit.getDefaultToolkit ().getSystemEventQueue ();
378            q.postEvent (new FocusEvent (permanentFocusOwner, FocusEvent.FOCUS_LOST, false));
379          }
380      }
381  }
382
383  /**
384   * Retrieve the {@link Component} that has the permanent keyboard
385   * focus, or null if the focus owner was not set by a thread in the
386   * current {@link java.lang.ThreadGroup}.
387   *
388   * @return the keyboard focus owner or null
389   */
390  public Component getPermanentFocusOwner ()
391  {
392    return (Component) getObject (currentPermanentFocusOwners);
393  }
394
395  /**
396   * Retrieve the {@link Component} that has the permanent keyboard
397   * focus, regardless of whether or not it was set by a thread in the
398   * current {@link java.lang.ThreadGroup}.
399   *
400   * @return the keyboard focus owner
401   * @throws SecurityException if this is not the keyboard focus
402   * manager associated with the current {@link java.lang.ThreadGroup}
403   */
404  protected Component getGlobalPermanentFocusOwner ()
405  {
406    return (Component) getGlobalObject (currentPermanentFocusOwners, true);
407  }
408
409  /**
410   * Set the {@link Component} that will be returned by {@link
411   * #getPermanentFocusOwner} (when it is called from the current
412   * {@link java.lang.ThreadGroup}) and {@link
413   * #getGlobalPermanentFocusOwner}.  This method does not actually
414   * transfer the keyboard focus.
415   *
416   * @param focusOwner the Component to return from
417   * getPermanentFocusOwner and getGlobalPermanentFocusOwner
418   *
419   * @see Component#requestFocus()
420   * @see Component#requestFocusInWindow()
421   */
422  protected void setGlobalPermanentFocusOwner (Component focusOwner)
423  {
424    if (focusOwner == null || focusOwner.focusable)
425      setGlobalObject (currentPermanentFocusOwners, focusOwner,
426                       "permanentFocusOwner");
427  }
428
429  /**
430   * Retrieve the {@link Window} that is or contains the keyboard
431   * focus owner, or null if the focused window was not set by a
432   * thread in the current {@link java.lang.ThreadGroup}.
433   *
434   * @return the focused window or null
435   */
436  public Window getFocusedWindow ()
437  {
438    return (Window) getObject (currentFocusedWindows);
439  }
440
441  /**
442   * Retrieve the {@link Window} that is or contains the focus owner,
443   * regardless of whether or not the {@link Window} was set focused
444   * by a thread in the current {@link java.lang.ThreadGroup}.
445   *
446   * @return the focused window
447   * @throws SecurityException if this is not the keyboard focus
448   * manager associated with the current {@link java.lang.ThreadGroup}
449   */
450  protected Window getGlobalFocusedWindow ()
451  {
452    return (Window) getGlobalObject (currentFocusedWindows, true);
453  }
454
455  /**
456   * Set the {@link Window} that will be returned by {@link
457   * #getFocusedWindow} (when it is called from the current {@link
458   * java.lang.ThreadGroup}) and {@link #getGlobalFocusedWindow}.
459   * This method does not actually cause <code>window</code> to become
460   * the focused {@link Window}.
461   *
462   * @param window the Window to return from getFocusedWindow and
463   * getGlobalFocusedWindow
464   */
465  protected void setGlobalFocusedWindow (Window window)
466  {
467    if (window == null || window.focusable)
468      setGlobalObject (currentFocusedWindows, window, "focusedWindow");
469  }
470
471  /**
472   * Retrieve the active {@link Window}, or null if the active window
473   * was not set by a thread in the current {@link
474   * java.lang.ThreadGroup}.
475   *
476   * @return the active window or null
477   */
478  public Window getActiveWindow()
479  {
480    return (Window) getObject (currentActiveWindows);
481  }
482
483  /**
484   * Retrieve the active {@link Window}, regardless of whether or not
485   * the {@link Window} was made active by a thread in the current
486   * {@link java.lang.ThreadGroup}.
487   *
488   * @return the active window
489   * @throws SecurityException if this is not the keyboard focus
490   * manager associated with the current {@link java.lang.ThreadGroup}
491   */
492  protected Window getGlobalActiveWindow()
493  {
494    return (Window) getGlobalObject (currentActiveWindows, true);
495  }
496
497  /**
498   * Set the {@link Window} that will be returned by {@link
499   * #getActiveWindow} (when it is called from the current {@link
500   * java.lang.ThreadGroup}) and {@link #getGlobalActiveWindow}.  This
501   * method does not actually cause <code>window</code> to be made
502   * active.
503   *
504   * @param window the Window to return from getActiveWindow and
505   * getGlobalActiveWindow
506   */
507  protected void setGlobalActiveWindow(Window window)
508  {
509    setGlobalObject (currentActiveWindows, window, "activeWindow");
510  }
511
512  /**
513   * Retrieve the default {@link FocusTraversalPolicy}.
514   * Focus-managing {@link Container}s use the returned object to
515   * define their initial focus traversal policy.
516   *
517   * @return a non-null default FocusTraversalPolicy object
518   */
519  public FocusTraversalPolicy getDefaultFocusTraversalPolicy ()
520  {
521    if (defaultPolicy == null)
522      defaultPolicy = new DefaultFocusTraversalPolicy ();
523    return defaultPolicy;
524  }
525
526  /**
527   * Set the {@link FocusTraversalPolicy} returned by {@link
528   * #getDefaultFocusTraversalPolicy}.  Focus-managing {@link
529   * Container}s created after this call will use policy as their
530   * initial focus traversal policy.  Existing {@link Container}s'
531   * focus traversal policies will not be affected by calls to this
532   * method.
533   *
534   * @param policy the FocusTraversalPolicy that will be returned by
535   * subsequent calls to getDefaultFocusTraversalPolicy
536   * @throws IllegalArgumentException if policy is null
537   */
538  public void setDefaultFocusTraversalPolicy (FocusTraversalPolicy policy)
539  {
540    if (policy == null)
541      throw new IllegalArgumentException ();
542    firePropertyChange ("defaultFocusTraversalPolicy", defaultPolicy, policy);
543    defaultPolicy = policy;
544  }
545
546  /**
547   * Set the default {@link java.util.Set} of focus traversal keys for
548   * one of the focus traversal directions.
549   *
550   * @param id focus traversal direction identifier
551   * @param keystrokes set of AWTKeyStrokes
552   *
553   * @see #FORWARD_TRAVERSAL_KEYS
554   * @see #BACKWARD_TRAVERSAL_KEYS
555   * @see #UP_CYCLE_TRAVERSAL_KEYS
556   * @see #DOWN_CYCLE_TRAVERSAL_KEYS
557   */
558  public void setDefaultFocusTraversalKeys (int id,
559                                            Set<? extends AWTKeyStroke>
560                                            keystrokes)
561  {
562    if (id != KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS &&
563        id != KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS &&
564        id != KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS &&
565        id != KeyboardFocusManager.DOWN_CYCLE_TRAVERSAL_KEYS)
566      throw new IllegalArgumentException ();
567
568    if (keystrokes == null)
569      throw new IllegalArgumentException ();
570
571    Set sa;
572    Set sb;
573    Set sc;
574    String type;
575    switch (id)
576      {
577      case FORWARD_TRAVERSAL_KEYS:
578        sa = defaultFocusKeys[BACKWARD_TRAVERSAL_KEYS];
579        sb = defaultFocusKeys[UP_CYCLE_TRAVERSAL_KEYS];
580        sc = defaultFocusKeys[DOWN_CYCLE_TRAVERSAL_KEYS];
581        type = "forwardDefaultFocusTraversalKeys";
582        break;
583      case BACKWARD_TRAVERSAL_KEYS:
584        sa = defaultFocusKeys[FORWARD_TRAVERSAL_KEYS];
585        sb = defaultFocusKeys[UP_CYCLE_TRAVERSAL_KEYS];
586        sc = defaultFocusKeys[DOWN_CYCLE_TRAVERSAL_KEYS];
587        type = "backwardDefaultFocusTraversalKeys";
588        break;
589      case UP_CYCLE_TRAVERSAL_KEYS:
590        sa = defaultFocusKeys[FORWARD_TRAVERSAL_KEYS];
591        sb = defaultFocusKeys[BACKWARD_TRAVERSAL_KEYS];
592        sc = defaultFocusKeys[DOWN_CYCLE_TRAVERSAL_KEYS];
593        type = "upCycleDefaultFocusTraversalKeys";
594        break;
595      case DOWN_CYCLE_TRAVERSAL_KEYS:
596        sa = defaultFocusKeys[FORWARD_TRAVERSAL_KEYS];
597        sb = defaultFocusKeys[BACKWARD_TRAVERSAL_KEYS];
598        sc = defaultFocusKeys[UP_CYCLE_TRAVERSAL_KEYS];
599        type = "downCycleDefaultFocusTraversalKeys";
600        break;
601      default:
602        throw new IllegalArgumentException ();
603      }
604    int i = keystrokes.size ();
605    Iterator iter = keystrokes.iterator ();
606    while (--i >= 0)
607      {
608        Object o = iter.next ();
609        if (!(o instanceof AWTKeyStroke)
610            || sa.contains (o) || sb.contains (o) || sc.contains (o)
611            || ((AWTKeyStroke) o).keyCode == KeyEvent.VK_UNDEFINED)
612          throw new IllegalArgumentException ();
613      }
614    keystrokes = Collections.unmodifiableSet (new HashSet (keystrokes));
615    firePropertyChange (type, defaultFocusKeys[id], keystrokes);
616    defaultFocusKeys[id] = keystrokes;
617  }
618
619  /**
620   * Retrieve the default {@link java.util.Set} of focus traversal
621   * keys for one of the focus traversal directions.
622   *
623   * @param id focus traversal direction identifier
624   *
625   * @return the default set of AWTKeyStrokes
626   *
627   * @see #FORWARD_TRAVERSAL_KEYS
628   * @see #BACKWARD_TRAVERSAL_KEYS
629   * @see #UP_CYCLE_TRAVERSAL_KEYS
630   * @see #DOWN_CYCLE_TRAVERSAL_KEYS
631   */
632  public Set<AWTKeyStroke> getDefaultFocusTraversalKeys (int id)
633  {
634    if (id < FORWARD_TRAVERSAL_KEYS || id > DOWN_CYCLE_TRAVERSAL_KEYS)
635      throw new IllegalArgumentException ();
636    return defaultFocusKeys[id];
637  }
638
639  /**
640   * Retrieve the current focus cycle root, or null if the focus owner
641   * was not set by a thread in the current {@link
642   * java.lang.ThreadGroup}.
643   *
644   * @return the current focus cycle root or null
645   */
646  public Container getCurrentFocusCycleRoot ()
647  {
648    return (Container) getObject (currentFocusCycleRoots);
649  }
650
651  /**
652   * Retrieve the current focus cycle root, regardless of whether or
653   * not it was made set by a thread in the current {@link
654   * java.lang.ThreadGroup}.
655   *
656   * @return the current focus cycle root
657   * @throws SecurityException if this is not the keyboard focus
658   * manager associated with the current {@link java.lang.ThreadGroup}
659   */
660  protected Container getGlobalCurrentFocusCycleRoot ()
661  {
662    return (Container) getGlobalObject (currentFocusCycleRoots, true);
663  }
664
665  /**
666   * Set the {@link Container} that will be returned by {@link
667   * #getCurrentFocusCycleRoot} (when it is called from the current
668   * {@link java.lang.ThreadGroup}) and {@link
669   * #getGlobalCurrentFocusCycleRoot}.  This method does not actually
670   * make <code>cycleRoot</code> the current focus cycle root.
671   *
672   * @param cycleRoot the focus cycle root to return from
673   * getCurrentFocusCycleRoot and getGlobalCurrentFocusCycleRoot
674   */
675  public void setGlobalCurrentFocusCycleRoot (Container cycleRoot)
676  {
677    setGlobalObject (currentFocusCycleRoots, cycleRoot, "currentFocusCycleRoot");
678  }
679
680  /**
681   * Registers the supplied property change listener for receiving
682   * events caused by the following property changes:
683   *
684   * <ul>
685   * <li>the current focus owner ("focusOwner")</li>
686   * <li>the permanent focus owner ("permanentFocusOwner")</li>
687   * <li>the focused window ("focusedWindow")</li>
688   * <li>the active window ("activeWindow")</li>
689   * <li>the default focus traversal policy ("defaultFocusTraversalPolicy")</li>
690   * <li>the default set of forward traversal keys ("forwardDefaultFocusTraversalKeys")</li>
691   * <li>the default set of backward traversal keys ("backwardDefaultFocusTraversalKeys")</li>
692   * <li>the default set of up cycle traversal keys ("upCycleDefaultFocusTraversalKeys")</li>
693   * <li>the default set of down cycle traversal keys ("downCycleDefaultFocusTraversalKeys")</li>
694   * <li>the current focus cycle root ("currentFocusCycleRoot")</li>
695   * </ul>
696   *
697   * If the supplied listener is null, nothing occurs.
698   *
699   * @param l the new listener to register.
700   * @see KeyboardFocusManager#addPropertyChangeListener(String, java.beans.PropertyChangeListener)
701   */
702  public void addPropertyChangeListener(PropertyChangeListener l)
703  {
704    if (l != null)
705      propertyChangeSupport.addPropertyChangeListener(l);
706  }
707
708  /**
709   * Removes the supplied property change listener from the list
710   * of registered listeners.  If the supplied listener is null,
711   * nothing occurs.
712   *
713   * @param l the listener to remove.
714   */
715  public void removePropertyChangeListener(PropertyChangeListener l)
716  {
717    if (l != null)
718      propertyChangeSupport.removePropertyChangeListener(l);
719  }
720
721  /**
722   * Returns the currently registered property change listeners
723   * in array form.  The returned array is empty if no listeners are
724   * currently registered.
725   *
726   * @return an array of registered property change listeners.
727   */
728  public PropertyChangeListener[] getPropertyChangeListeners()
729  {
730    return propertyChangeSupport.getPropertyChangeListeners();
731  }
732
733  /**
734   * Registers a property change listener for receiving events relating
735   * to a change to a specified property.  The supplied property name can be
736   * either user-defined or one from the following list of properties
737   * relevant to this class:
738   *
739   * <ul>
740   * <li>the current focus owner ("focusOwner")</li>
741   * <li>the permanent focus owner ("permanentFocusOwner")</li>
742   * <li>the focused window ("focusedWindow")</li>
743   * <li>the active window ("activeWindow")</li>
744   * <li>the default focus traversal policy ("defaultFocusTraversalPolicy")</li>
745   * <li>the default set of forward traversal keys ("forwardDefaultFocusTraversalKeys")</li>
746   * <li>the default set of backward traversal keys ("backwardDefaultFocusTraversalKeys")</li>
747   * <li>the default set of up cycle traversal keys ("upCycleDefaultFocusTraversalKeys")</li>
748   * <li>the default set of down cycle traversal keys ("downCycleDefaultFocusTraversalKeys")</li>
749   * <li>the current focus cycle root ("currentFocusCycleRoot")</li>
750   * </ul>
751   *
752   * Nothing occurs if a null listener is supplied.  null is regarded as a valid property name.
753   *
754   * @param name the name of the property to handle change events for.
755   * @param l the listener to register for changes to the specified property.
756   * @see KeyboardFocusManager#addPropertyChangeListener(java.beans.PropertyChangeListener)
757   */
758  public void addPropertyChangeListener(String name, PropertyChangeListener l)
759  {
760    if (l != null)
761      propertyChangeSupport.addPropertyChangeListener(name, l);
762  }
763
764  /**
765   * Removes the supplied property change listener registered for the
766   * specified property from the list of registered listeners.  If the
767   * supplied listener is null, nothing occurs.
768   *
769   * @param name the name of the property the listener is
770   *        monitoring changes to.
771   * @param l the listener to remove.
772   */
773  public void removePropertyChangeListener(String name,
774                                           PropertyChangeListener l)
775  {
776    if (l != null)
777      propertyChangeSupport.removePropertyChangeListener(name, l);
778  }
779
780  /**
781   * Returns the currently registered property change listeners
782   * in array form, which listen for changes to the supplied property.
783   * The returned array is empty, if no listeners are currently registered
784   * for events pertaining to the supplied property.
785   *
786   * @param name The property the returned listeners monitor for changes.
787   * @return an array of registered property change listeners which
788   *         listen for changes to the supplied property.
789   */
790  public PropertyChangeListener[] getPropertyChangeListeners(String name)
791  {
792    return propertyChangeSupport.getPropertyChangeListeners(name);
793  }
794
795  /**
796   * Fires a property change event as a response to a change to
797   * to the specified property.  The event is only fired if a
798   * change has actually occurred (i.e. o and n are different).
799   *
800   * @param name The name of the property to which a change occurred.
801   * @param o The old value of the property.
802   * @param n The new value of the property.
803   */
804  protected void firePropertyChange(String name, Object o, Object n)
805  {
806    propertyChangeSupport.firePropertyChange(name, o, n);
807  }
808
809  /**
810   * Registers a vetoable property change listener for receiving events
811   * relating to the following properties:
812   *
813   * <ul>
814   * <li>the current focus owner ("focusOwner")</li>
815   * <li>the permanent focus owner ("permanentFocusOwner")</li>
816   * <li>the focused window ("focusedWindow")</li>
817   * <li>the active window ("activeWindow")</li>
818   * </ul>
819   *
820   * Nothing occurs if a null listener is supplied.
821   *
822   * @param l the listener to register.
823   * @see KeyboardFocusManager#addVetoableChangeListener(String, java.beans.VetoableChangeListener)
824   */
825  public void addVetoableChangeListener(VetoableChangeListener l)
826  {
827    if (l != null)
828      vetoableChangeSupport.addVetoableChangeListener(l);
829  }
830
831  /**
832   * Removes the supplied vetoable property change listener from
833   * the list of registered listeners.  If the supplied listener
834   * is null, nothing occurs.
835   *
836   * @param l the listener to remove.
837   */
838  public void removeVetoableChangeListener(VetoableChangeListener l)
839  {
840    if (l != null)
841      vetoableChangeSupport.removeVetoableChangeListener(l);
842  }
843
844  /**
845   * Returns the currently registered vetoable property change listeners
846   * in array form.  The returned array is empty if no listeners are
847   * currently registered.
848   *
849   * @return an array of registered vetoable property change listeners.
850   * @since 1.4
851   */
852  public VetoableChangeListener[] getVetoableChangeListeners()
853  {
854    return vetoableChangeSupport.getVetoableChangeListeners();
855  }
856
857  /**
858   * Registers a vetoable property change listener for receiving events relating
859   * to a vetoable change to a specified property.  The supplied property name can be
860   * either user-defined or one from the following list of properties
861   * relevant to this class:
862   *
863   * <ul>
864   * <li>the current focus owner ("focusOwner")</li>
865   * <li>the permanent focus owner ("permanentFocusOwner")</li>
866   * <li>the focused window ("focusedWindow")</li>
867   * <li>the active window ("activeWindow")</li>
868   * </ul>
869   *
870   * Nothing occurs if a null listener is supplied.  null is regarded as a valid property name.
871   *
872   * @param name the name of the property to handle change events for.
873   * @param l the listener to register for changes to the specified property.
874   * @see KeyboardFocusManager#addVetoableChangeListener(java.beans.VetoableChangeListener)
875   */
876  public void addVetoableChangeListener(String name, VetoableChangeListener l)
877  {
878    if (l != null)
879      vetoableChangeSupport.addVetoableChangeListener(name, l);
880  }
881
882  /**
883   * Removes the supplied vetoable property change listener registered
884   * for the specified property from the list of registered listeners.
885   * If the supplied listener is null, nothing occurs.
886   *
887   * @param name the name of the vetoable property the listener is
888   *        monitoring changes to.
889   * @param l the listener to remove.
890   */
891  public void removeVetoableChangeListener(String name,
892                                           VetoableChangeListener l)
893  {
894    if (l != null)
895      vetoableChangeSupport.removeVetoableChangeListener(name, l);
896  }
897
898  /**
899   * Returns the currently registered vetoable property change listeners
900   * in array form, which listen for changes to the supplied property.
901   * The returned array is empty, if no listeners are currently registered
902   * for events pertaining to the supplied property.
903   *
904   * @param name The property the returned listeners monitor for changes.
905   * @return an array of registered property change listeners which
906   *         listen for changes to the supplied property.
907   * @since 1.4
908   */
909  public VetoableChangeListener[] getVetoableChangeListeners(String name)
910  {
911    return vetoableChangeSupport.getVetoableChangeListeners(name);
912  }
913
914  /**
915   * Fires a property change event as a response to a vetoable change to
916   * to the specified property.  The event is only fired if a
917   * change has actually occurred (i.e. o and n are different).
918   * In the event that the property change is vetoed, the following
919   * occurs:
920   *
921   * <ol>
922   * <li>
923   * This method throws a <code>PropertyVetoException</code> to
924   * the proposed change.
925   * </li>
926   * <li>
927   * A new event is fired to reverse the previous change.
928   * </li>
929   * <li>
930   * This method again throws a <code>PropertyVetoException</code>
931   * in response to the reversion.
932   * </li>
933   * </ol>
934   *
935   * @param name The name of the property to which a change occurred.
936   * @param o The old value of the property.
937   * @param n The new value of the property.
938   * @throws PropertyVetoException if one of the listeners vetos
939   *         the change by throwing this exception.
940   */
941  protected void fireVetoableChange(String name, Object o, Object n)
942    throws PropertyVetoException
943  {
944    vetoableChangeSupport.fireVetoableChange(name, o, n);
945  }
946
947  /**
948   * Adds a key event dispatcher to the list of registered dispatchers.
949   * When a key event is fired, each dispatcher's <code>dispatchKeyEvent</code>
950   * method is called in the order that they were added, prior to the manager
951   * dispatching the event itself.  Notifications halt when one of the
952   * dispatchers returns true.
953   * <br />
954   * <br />
955   * The same dispatcher can exist multiple times within the list
956   * of registered dispatchers, and there is no limit on the length
957   * of this list.  A null dispatcher is simply ignored.
958   *
959   * @param dispatcher The dispatcher to register.
960   */
961  public void addKeyEventDispatcher(KeyEventDispatcher dispatcher)
962  {
963    if (dispatcher != null)
964      keyEventDispatchers.add(dispatcher);
965  }
966
967  /**
968   * Removes the specified key event dispatcher from the list of
969   * registered dispatchers.  The manager always dispatches events,
970   * regardless of its existence within the list.  The manager
971   * can be added and removed from the list, as with any other
972   * dispatcher, but this does not affect its ability to dispatch
973   * key events.  Non-existent and null dispatchers are simply ignored
974   * by this method.
975   *
976   * @param dispatcher The dispatcher to remove.
977   */
978  public void removeKeyEventDispatcher(KeyEventDispatcher dispatcher)
979  {
980    keyEventDispatchers.remove(dispatcher);
981  }
982
983  /**
984   * Returns the currently registered key event dispatchers in <code>List</code>
985   * form.  At present, this only includes dispatchers explicitly registered
986   * via the <code>addKeyEventDispatcher()</code> method, but this behaviour
987   * is subject to change and should not be depended on.  The manager itself
988   * may be a member of the list, but only if explicitly registered.  If no
989   * dispatchers have been registered, the list will be empty.
990   *
991   * @return A list of explicitly registered key event dispatchers.
992   * @see KeyboardFocusManager#addKeyEventDispatcher(java.awt.KeyEventDispatcher)
993   */
994  protected List<KeyEventDispatcher> getKeyEventDispatchers ()
995  {
996    return (List<KeyEventDispatcher>) keyEventDispatchers.clone ();
997  }
998
999  /**
1000   * Adds a key event post processor to the list of registered post processors.
1001   * Post processors work in the same way as key event dispatchers, except
1002   * that they are invoked after the manager has dispatched the key event,
1003   * and not prior to this.  Each post processor's <code>postProcessKeyEvent</code>
1004   * method is called to see if any post processing needs to be performed.  THe
1005   * processors are called in the order in which they were added to the list,
1006   * and notifications continue until one returns true.  As with key event
1007   * dispatchers, the manager is implicitly called following this process,
1008   * regardless of whether or not it is present within the list.
1009   * <br />
1010   * <br />
1011   * The same post processor can exist multiple times within the list
1012   * of registered post processors, and there is no limit on the length
1013   * of this list.  A null post processor is simply ignored.
1014   *
1015   * @param postProcessor the post processor to register.
1016   * @see KeyboardFocusManager#addKeyEventDispatcher(java.awt.KeyEventDispatcher)
1017   */
1018  public void addKeyEventPostProcessor (KeyEventPostProcessor postProcessor)
1019  {
1020    if (postProcessor != null)
1021      keyEventPostProcessors.add (postProcessor);
1022  }
1023
1024  /**
1025   * Removes the specified key event post processor from the list of
1026   * registered post processors.  The manager always post processes events,
1027   * regardless of its existence within the list.  The manager
1028   * can be added and removed from the list, as with any other
1029   * post processor, but this does not affect its ability to post process
1030   * key events.  Non-existent and null post processors are simply ignored
1031   * by this method.
1032   *
1033   * @param postProcessor the post processor to remove.
1034   */
1035  public void removeKeyEventPostProcessor (KeyEventPostProcessor postProcessor)
1036  {
1037    keyEventPostProcessors.remove (postProcessor);
1038  }
1039
1040  /**
1041   * Returns the currently registered key event post processors in <code>List</code>
1042   * form.  At present, this only includes post processors explicitly registered
1043   * via the <code>addKeyEventPostProcessor()</code> method, but this behaviour
1044   * is subject to change and should not be depended on.  The manager itself
1045   * may be a member of the list, but only if explicitly registered.  If no
1046   * post processors have been registered, the list will be empty.
1047   *
1048   * @return A list of explicitly registered key event post processors.
1049   * @see KeyboardFocusManager#addKeyEventPostProcessor(java.awt.KeyEventPostProcessor)
1050   */
1051  protected List<KeyEventPostProcessor> getKeyEventPostProcessors ()
1052  {
1053    return (List<KeyEventPostProcessor>) keyEventPostProcessors.clone ();
1054  }
1055
1056  /**
1057   * The AWT event dispatcher uses this method to request that the manager
1058   * handle a particular event.  If the manager fails or refuses to
1059   * dispatch the supplied event (this method returns false), the
1060   * AWT event dispatcher will try to dispatch the event itself.
1061   * <br />
1062   * <br />
1063   * The manager is expected to handle all <code>FocusEvent</code>s
1064   * and <code>KeyEvent</code>s, and <code>WindowEvent</code>s
1065   * relating to the focus.  Dispatch is done with regard to the
1066   * the focus owner and the currently focused and active windows.
1067   * In handling the event, the source of the event may be overridden.
1068   * <br />
1069   * <br />
1070   * The actual dispatching is performed by calling
1071   * <code>redispatchEvent()</code>.  This avoids the infinite recursion
1072   * of dispatch requests which may occur if this method is called on
1073   * the target component.
1074   *
1075   * @param e the event to dispatch.
1076   * @return true if the event was dispatched.
1077   * @see KeyboardFocusManager#redispatchEvent(java.awt.Component, java.awt.AWTEvent)
1078   * @see KeyEvent
1079   * @see FocusEvent
1080   * @see WindowEvent
1081   */
1082  public abstract boolean dispatchEvent (AWTEvent e);
1083
1084  /**
1085   * Handles redispatching of an event so that recursion of
1086   * dispatch requests does not occur.  Event dispatch methods
1087   * within this manager (<code>dispatchEvent()</code>) and
1088   * the key event dispatchers should use this method to handle
1089   * dispatching rather than the dispatch method of the target
1090   * component.
1091   * <br />
1092   * <br />
1093   * <strong>
1094   * This method is not intended for general consumption, and is
1095   * only for the use of the aforementioned classes.
1096   * </strong>
1097   *
1098   * @param target the target component to which the event is
1099   *        dispatched.
1100   * @param e the event to dispatch.
1101   */
1102  public final void redispatchEvent (Component target, AWTEvent e)
1103  {
1104    e.isFocusManagerEvent = true;
1105    target.dispatchEvent (e);
1106    e.isFocusManagerEvent = false;
1107  }
1108
1109  /**
1110   * Attempts to dispatch key events for which no key event dispatcher
1111   * has so far succeeded.  This method is usually called by
1112   * <code>dispatchEvent()</code> following the sending of the key
1113   * event to any registered key event dispatchers.  If the key
1114   * event reaches this stage, none of the dispatchers returned
1115   * true.  This is, of course, always the case if there are no
1116   * registered dispatchers.
1117   * <br />
1118   * <br />
1119   * If this method also fails to handle the key event, then
1120   * false is returned to the caller.  In the case of
1121   * <code>dispatchEvent()</code>, the calling method may try
1122   * to handle the event itself or simply forward on the
1123   * false result to its caller.  When the event is dispatched
1124   * by this method, a true result is propogated through the
1125   * calling methods.
1126   *
1127   * @param e the key event to dispatch.
1128   * @return true if the event was dispatched successfully.
1129   */
1130  public abstract boolean dispatchKeyEvent (KeyEvent e);
1131
1132  /**
1133   * Handles the post processing of key events.  By default,
1134   * this method will map unhandled key events to appropriate
1135   * <code>MenuShortcut</code>s.  The event is consumed
1136   * in the process and the shortcut is activated.  This
1137   * method is usually called by <code>dispatchKeyEvent</code>.
1138   *
1139   * @param e the key event to post process.
1140   * @return true by default, as the event was handled.
1141   */
1142  public abstract boolean postProcessKeyEvent (KeyEvent e);
1143
1144  /**
1145   * Handles focus traversal operations for key events which
1146   * represent focus traversal keys in relation to the supplied
1147   * component.  The supplied component is assumed to have the
1148   * focus, whether it does so or not, and the operation is
1149   * carried out as appropriate, with this in mind.
1150   *
1151   * @param focused the component on which to perform focus traversal,
1152   *        on the assumption that this component has the focus.
1153   * @param e the possible focus traversal key event.
1154   */
1155  public abstract void processKeyEvent (Component focused, KeyEvent e);
1156
1157  /**
1158   * Delays all key events following the specified timestamp until the
1159   * supplied component has focus.  The AWT calls this method when it is
1160   * determined that a focus change may occur within the native windowing
1161   * system.  Any key events which occur following the time specified by
1162   * after are delayed until a <code>FOCUS_GAINED</code> event is received
1163   * for the untilFocused component.  The manager is responsible for ensuring
1164   * this takes place.
1165   *
1166   * @param after the timestamp beyond which all key events are delayed until
1167   *        the supplied component gains focus.
1168   * @param untilFocused the component to wait on gaining focus.
1169   */
1170  protected abstract void enqueueKeyEvents (long after, Component untilFocused);
1171
1172  /**
1173   * Removes the key event block specified by the supplied timestamp and component.
1174   * All delayed key events are released for normal dispatching following its
1175   * removal and subsequent key events that would have been blocked are now
1176   * immediately dispatched.  If the specified timestamp is below 0, then
1177   * the request with the oldest timestamp is removed.
1178   *
1179   * @param after the timestamp of the key event block to be removed, or a
1180   *        value smaller than 0 if the oldest is to be removed.
1181   * @param untilFocused the component of the key event block to be removed.
1182   */
1183  protected abstract void dequeueKeyEvents (long after, Component untilFocused);
1184
1185  /**
1186   * Discards all key event blocks relating to focus requirements for
1187   * the supplied component, regardless of timestamp.
1188   *
1189   * @param comp the component of the key event block(s) to be removed.
1190   */
1191  protected abstract void discardKeyEvents (Component comp);
1192
1193  /**
1194   * Moves the current focus to the next component following
1195   * comp, based on the current focus traversal policy.  By
1196   * default, only visible, displayable, accepted components
1197   * can receive focus.  <code>Canvas</code>es, <code>Panel</code>s,
1198   * <code>Label</code>s, <code>ScrollPane</code>s, <code>Scrollbar</code>s,
1199   * <code>Window</code>s and lightweight components are judged
1200   * to be unacceptable by default.  See the
1201   * <code>DefaultFocusTraversalPolicy</code> for more details.
1202   *
1203   * @param comp the component prior to the one which will
1204   *        become the focus, following execution of this method.
1205   * @see DefaultFocusTraversalPolicy
1206   */
1207  public abstract void focusNextComponent(Component comp);
1208
1209  /**
1210   * Moves the current focus to the previous component, prior to
1211   * comp, based on the current focus traversal policy.  By
1212   * default, only visible, displayable, accepted components
1213   * can receive focus.  <code>Canvas</code>es, <code>Panel</code>s,
1214   * <code>Label</code>s, <code>ScrollPane</code>s, <code>Scrollbar</code>s,
1215   * <code>Window</code>s and lightweight components are judged
1216   * to be unacceptable by default.  See the
1217   * <code>DefaultFocusTraversalPolicy</code> for more details.
1218   *
1219   * @param comp the component following the one which will
1220   *        become the focus, following execution of this method.
1221   * @see DefaultFocusTraversalPolicy
1222   */
1223  public abstract void focusPreviousComponent(Component comp);
1224
1225  /**
1226   * Moves the current focus upwards by one focus cycle.
1227   * Both the current focus owner and current focus cycle root
1228   * become the focus cycle root of the supplied component.
1229   * However, in the case of a <code>Window</code>, the default
1230   * focus component becomes the focus owner and the focus cycle
1231   * root is not changed.
1232   *
1233   * @param comp the component used as part of the focus traversal.
1234   */
1235  public abstract void upFocusCycle(Component comp);
1236
1237  /**
1238   * Moves the current focus downwards by one focus cycle.
1239   * If the supplied container is a focus cycle root, then this
1240   * becomes the current focus cycle root and the focus goes
1241   * to the default component of the specified container.
1242   * Nothing happens for non-focus cycle root containers.
1243   *
1244   * @param cont the container used as part of the focus traversal.
1245   */
1246  public abstract void downFocusCycle(Container cont);
1247
1248  /**
1249   * Moves the current focus to the next component, based on the
1250   * current focus traversal policy.  By default, only visible,
1251   * displayable, accepted component can receive focus.
1252   * <code>Canvas</code>es, <code>Panel</code>s,
1253   * <code>Label</code>s, <code>ScrollPane</code>s, <code>Scrollbar</code>s,
1254   * <code>Window</code>s and lightweight components are judged
1255   * to be unacceptable by default.  See the
1256   * <code>DefaultFocusTraversalPolicy</code> for more details.
1257   *
1258   * @see DefaultFocusTraversalPolicy
1259   */
1260  public final void focusNextComponent()
1261  {
1262    focusNextComponent (null);
1263  }
1264
1265  /**
1266   * Moves the current focus to the previous component, based on the
1267   * current focus traversal policy.  By default, only visible,
1268   * displayable, accepted component can receive focus.
1269   * <code>Canvas</code>es, <code>Panel</code>s,
1270   * <code>Label</code>s, <code>ScrollPane</code>s, <code>Scrollbar</code>s,
1271   * <code>Window</code>s and lightweight components are judged
1272   * to be unacceptable by default.  See the
1273   * <code>DefaultFocusTraversalPolicy</code> for more details.
1274   *
1275   * @see DefaultFocusTraversalPolicy
1276   */
1277  public final void focusPreviousComponent()
1278  {
1279    focusPreviousComponent (null);
1280  }
1281
1282  /**
1283   * Moves the current focus upwards by one focus cycle,
1284   * so that the new focus owner is the focus cycle root
1285   * of the current owner.  The current focus cycle root then
1286   * becomes the focus cycle root of the new focus owner.
1287   * However, in the case of the focus cycle root of the
1288   * current focus owner being a <code>Window</code>, the default
1289   * component of this window becomes the focus owner and the
1290   * focus cycle root is not changed.
1291   */
1292  public final void upFocusCycle()
1293  {
1294    upFocusCycle (null);
1295  }
1296
1297  /**
1298   * Moves the current focus downwards by one focus cycle,
1299   * iff the current focus cycle root is a <code>Container</code>.
1300   * Usually, the new focus owner is set to the default component
1301   * of the container and the current focus cycle root is set
1302   * to the current focus owner.  Nothing occurs if the current
1303   * focus cycle root is not a container.
1304   */
1305  public final void downFocusCycle()
1306  {
1307    Component focusOwner = getGlobalFocusOwner ();
1308    if (focusOwner instanceof Container
1309        && ((Container) focusOwner).isFocusCycleRoot ())
1310      downFocusCycle ((Container) focusOwner);
1311  }
1312
1313  /**
1314   * Retrieve an object from one of the global object {@link
1315   * java.util.Map}s, if the object was set by the a thread in the
1316   * current {@link java.lang.ThreadGroup}.  Otherwise, return null.
1317   *
1318   * @param globalMap one of the global object Maps
1319   *
1320   * @return a global object set by the current ThreadGroup, or null
1321   *
1322   * @see #getFocusOwner()
1323   * @see #getPermanentFocusOwner()
1324   * @see #getFocusedWindow()
1325   * @see #getActiveWindow()
1326   * @see #getCurrentFocusCycleRoot()
1327   */
1328  private Object getObject (Map globalMap)
1329  {
1330    ThreadGroup currentGroup = Thread.currentThread ().getThreadGroup ();
1331    return globalMap.get (currentGroup);
1332  }
1333
1334  /**
1335   * Retrieve an object from one of the global object {@link
1336   * java.util.Map}s, regardless of whether or not the object was set
1337   * by a thread in the current {@link java.lang.ThreadGroup}.
1338   *
1339   * @param globalMap one of the global object Maps
1340   *
1341   * @return a global object set by the current ThreadGroup, or null
1342   *
1343   * @throws SecurityException if this is not the keyboard focus
1344   * manager associated with the current {@link java.lang.ThreadGroup}
1345   *
1346   * @see #getGlobalFocusOwner()
1347   * @see #getGlobalPermanentFocusOwner()
1348   * @see #getGlobalFocusedWindow()
1349   * @see #getGlobalActiveWindow()
1350   * @see #getGlobalCurrentFocusCycleRoot()
1351   */
1352  private Object getGlobalObject (Map globalMap, boolean checkThread)
1353  {
1354    if (checkThread)
1355      {
1356        ThreadGroup currentGroup = Thread.currentThread ().getThreadGroup ();
1357        KeyboardFocusManager managerForCallingThread =
1358         (KeyboardFocusManager) currentKeyboardFocusManagers.get(currentGroup);
1359
1360        if (this != managerForCallingThread)
1361          throw new SecurityException ("Attempted to retrieve an object from a "
1362                                       + "keyboard focus manager that isn't "
1363                                + "associated with the current thread group.");
1364      }
1365    synchronized (globalMap)
1366      {
1367        Collection globalObjects = globalMap.values ();
1368        Iterator i = globalObjects.iterator ();
1369        Component globalObject;
1370
1371        while (i.hasNext ())
1372          {
1373            globalObject = (Component) i.next ();
1374            if (globalObject != null)
1375              return globalObject;
1376          }
1377      }
1378
1379    // No Object was found.
1380    return null;
1381  }
1382
1383  /**
1384   * Set an object in one of the global object {@link java.util.Map}s,
1385   * that will be returned by subsequent calls to getGlobalObject on
1386   * the same {@link java.util.Map}.
1387   *
1388   * @param globalMap one of the global object Maps
1389   * @param newObject the object to set
1390   * @param property the property that will change
1391   *
1392   * @see #setGlobalFocusOwner(Component)
1393   * @see #setGlobalPermanentFocusOwner(Component)
1394   * @see #setGlobalFocusedWindow(Window)
1395   * @see #setGlobalActiveWindow(Window)
1396   * @see #setGlobalCurrentFocusCycleRoot(Container)
1397   */
1398  private void setGlobalObject (Map globalMap,
1399                                Object newObject,
1400                                String property)
1401  {
1402    synchronized (globalMap)
1403      {
1404        // Save old object.
1405        Object oldObject = getGlobalObject(globalMap, false);
1406
1407        // Nullify old object.
1408        Collection threadGroups = globalMap.keySet ();
1409        Iterator i = threadGroups.iterator ();
1410        while (i.hasNext ())
1411          {
1412            ThreadGroup oldThreadGroup = (ThreadGroup) i.next ();
1413            if (globalMap.get (oldThreadGroup) != null)
1414              {
1415                globalMap.put (oldThreadGroup, null);
1416                // There should only be one object set at a time, so
1417                // we can short circuit.
1418                break;
1419              }
1420          }
1421
1422        ThreadGroup currentGroup = Thread.currentThread ().getThreadGroup ();
1423        firePropertyChange (property, oldObject, newObject);
1424        try
1425          {
1426            fireVetoableChange (property, oldObject, newObject);
1427            // Set new object.
1428            globalMap.put (currentGroup, newObject);
1429          }
1430        catch (PropertyVetoException e)
1431          {
1432          }
1433      }
1434  }
1435
1436
1437  /**
1438   * Maps focus requests from heavyweight to lightweight components.
1439   */
1440  private static HashMap focusRequests = new HashMap();
1441
1442  /**
1443   * Retargets focus events that come from the peer (which only know about
1444   * heavyweight components) to go to the correct lightweight component
1445   * if appropriate.
1446   *
1447   * @param ev the event to check
1448   *
1449   * @return the retargetted event
1450   */
1451  static AWTEvent retargetFocusEvent(AWTEvent ev)
1452  {
1453    if (ev instanceof FocusEvent)
1454      {
1455        FocusEvent fe = (FocusEvent) ev;
1456        Component target = fe.getComponent();
1457        if (focusRequests.containsKey(target))
1458          {
1459            Component lightweight = (Component) focusRequests.get(target);
1460            ev = new FocusEvent(lightweight, fe.id, fe.isTemporary());
1461            focusRequests.remove(target);
1462          }
1463      }
1464    return ev;
1465  }
1466
1467  /**
1468   * Adds a lightweight focus request for a heavyweight component.
1469   *
1470   * @param heavyweight the heavyweight from which we will receive a focus
1471   *        event soon
1472   * @param lightweight the lightweight that ultimately receives the request
1473   */
1474  static void addLightweightFocusRequest(Component heavyweight,
1475                                         Component lightweight)
1476  {
1477    focusRequests.put(heavyweight, lightweight);
1478  }
1479}