Source for java.awt.KeyboardFocusManager

 1:  /* KeyboardFocusManager.java -- manage component focusing via the keyboard
 2:  Copyright (C) 2002, 2004, 2005 Free Software Foundation
 3: 
 4: This file is part of GNU Classpath.
 5: 
 6: GNU Classpath is free software; you can redistribute it and/or modify
 7: it under the terms of the GNU General Public License as published by
 8: the Free Software Foundation; either version 2, or (at your option)
 9: any later version.
 10: 
 11: GNU Classpath is distributed in the hope that it will be useful, but
 12: WITHOUT ANY WARRANTY; without even the implied warranty of
 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 14: General Public License for more details.
 15: 
 16: You should have received a copy of the GNU General Public License
 17: along with GNU Classpath; see the file COPYING. If not, write to the
 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 19: 02110-1301 USA.
 20: 
 21: Linking this library statically or dynamically with other modules is
 22: making a combined work based on this library. Thus, the terms and
 23: conditions of the GNU General Public License cover the whole
 24: combination.
 25: 
 26: As a special exception, the copyright holders of this library give you
 27: permission to link this library with independent modules to produce an
 28: executable, regardless of the license terms of these independent
 29: modules, and to copy and distribute the resulting executable under
 30: terms of your choice, provided that you also meet, for each linked
 31: independent module, the terms and conditions of the license of that
 32: module. An independent module is a module which is not derived from
 33: or based on this library. If you modify this library, you may extend
 34: this exception to your version of the library, but you are not
 35: obligated to do so. If you do not wish to do so, delete this
 36: exception statement from your version. */
 37: 
 38: 
 39:  package java.awt;
 40: 
 41:  import java.applet.Applet;
 42:  import java.awt.FocusTraversalPolicy;
 43:  import java.awt.event.FocusEvent;
 44:  import java.awt.event.KeyEvent;
 45:  import java.awt.event.WindowEvent;
 46:  import java.beans.PropertyChangeListener;
 47:  import java.beans.PropertyChangeSupport;
 48:  import java.beans.PropertyVetoException;
 49:  import java.beans.VetoableChangeListener;
 50:  import java.beans.VetoableChangeSupport;
 51:  import java.util.ArrayList;
 52:  import java.util.Collection;
 53:  import java.util.Collections;
 54:  import java.util.HashMap;
 55:  import java.util.HashSet;
 56:  import java.util.Iterator;
 57:  import java.util.List;
 58:  import java.util.Map;
 59:  import java.util.Set;
 60: 
 61:  /**
 62:  * The <code>KeyboardFocusManager</code> handles the focusing of
 63:  * windows for receiving keyboard events. The manager handles
 64:  * the dispatch of all <code>FocusEvent</code>s and
 65:  * <code>KeyEvent</code>s, along with <code>WindowEvent</code>s
 66:  * relating to the focused window. Users can use the manager
 67:  * to ascertain the current focus owner and fire events.
 68:  * <br />
 69:  * <br />
 70:  * The focus owner is the <code>Component</code> that receives
 71:  * key events. The focus owner is either the currently focused
 72:  * window or a component within this window.
 73:  * <br />
 74:  * <br />
 75:  * The underlying native windowing system may denote the active
 76:  * window or its children with special decorations (e.g. a highlighted
 77:  * title bar). The active window is always either a <code>Frame</code>
 78:  * or <code>Dialog</code>, and is either the currently focused
 79:  * window or its owner.
 80:  * <br />
 81:  * <br />
 82:  * Applets may be partitioned into different applet contexts, according
 83:  * to their code base. In this case, each context has its own
 84:  * <code>KeyboardFocusManager</code>, as opposed to the global
 85:  * manager maintained by applets which share the same context.
 86:  * Each context is insulated from the others, and they don't interact.
 87:  * The resulting behaviour, as with context division, depends on the browser
 88:  * supporting the applets. Regardless, there can only ever be
 89:  * one focused window, one active window and one focus owner
 90:  * per <code>ClassLoader</code>.
 91:  * <br />
 92:  * <br />
 93:  * To support this separation of focus managers, the manager instances
 94:  * and the internal state information is grouped by the
 95:  * <code>ThreadGroup</code> to which it pertains. With respect to
 96:  * applets, each code base has its own <code>ThreadGroup</code>, so the
 97:  * isolation of each context is enforced within the manager.
 98:  * <br />
 99:  * <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: }