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 }