001    /* KeyboardFocusManager.java -- manage component focusing via the keyboard
002       Copyright (C) 2002, 2004, 2005 Free Software Foundation
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package java.awt;
040    
041    import java.applet.Applet;
042    import java.awt.FocusTraversalPolicy;
043    import java.awt.event.FocusEvent;
044    import java.awt.event.KeyEvent;
045    import java.awt.event.WindowEvent;
046    import java.beans.PropertyChangeListener;
047    import java.beans.PropertyChangeSupport;
048    import java.beans.PropertyVetoException;
049    import java.beans.VetoableChangeListener;
050    import java.beans.VetoableChangeSupport;
051    import java.util.ArrayList;
052    import java.util.Collection;
053    import java.util.Collections;
054    import java.util.HashMap;
055    import java.util.HashSet;
056    import java.util.Iterator;
057    import java.util.List;
058    import java.util.Map;
059    import 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     */
120    public 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    }