< prev index next >

src/java.desktop/share/classes/java/awt/KeyboardFocusManager.java

Print this page




 356      * root, then it may be ambiguous as to which Components represent the next
 357      * and previous Components to focus during normal focus traversal. In that
 358      * case, the current focus cycle root is used to differentiate among the
 359      * possibilities.
 360      */
 361     private static Container currentFocusCycleRoot;
 362 
 363     /**
 364      * A description of any VetoableChangeListeners which have been registered.
 365      */
 366     private VetoableChangeSupport vetoableSupport;
 367 
 368     /**
 369      * A description of any PropertyChangeListeners which have been registered.
 370      */
 371     private PropertyChangeSupport changeSupport;
 372 
 373     /**
 374      * This KeyboardFocusManager's KeyEventDispatcher chain. The List does not
 375      * include this KeyboardFocusManager unless it was explicitly re-registered
 376      * via a call to <code>addKeyEventDispatcher</code>. If no other
 377      * KeyEventDispatchers are registered, this field may be null or refer to
 378      * a List of length 0.
 379      */
 380     private java.util.LinkedList<KeyEventDispatcher> keyEventDispatchers;
 381 
 382     /**
 383      * This KeyboardFocusManager's KeyEventPostProcessor chain. The List does
 384      * not include this KeyboardFocusManager unless it was explicitly
 385      * re-registered via a call to <code>addKeyEventPostProcessor</code>.
 386      * If no other KeyEventPostProcessors are registered, this field may be
 387      * null or refer to a List of length 0.
 388      */
 389     private java.util.LinkedList<KeyEventPostProcessor> keyEventPostProcessors;
 390 
 391     /**
 392      * Maps Windows to those Windows' most recent focus owners.
 393      */
 394     private static java.util.Map<Window, WeakReference<Component>> mostRecentFocusOwners = new WeakHashMap<>();
 395 
 396     /**
 397      * We cache the permission used to verify that the calling thread is
 398      * permitted to access the global focus state.
 399      */
 400     private static AWTPermission replaceKeyboardFocusManagerPermission;
 401 
 402     /*
 403      * SequencedEvent which is currently dispatched in AppContext.
 404      */
 405     transient SequencedEvent currentSequencedEvent = null;


 497      *         permission
 498      */
 499     protected Component getGlobalFocusOwner() throws SecurityException {
 500         synchronized (KeyboardFocusManager.class) {
 501             checkKFMSecurity();
 502             return focusOwner;
 503         }
 504     }
 505 
 506     /**
 507      * Sets the focus owner. The operation will be cancelled if the Component
 508      * is not focusable. The focus owner is defined as the Component in an
 509      * application that will typically receive all KeyEvents generated by the
 510      * user. KeyEvents which map to the focus owner's focus traversal keys will
 511      * not be delivered if focus traversal keys are enabled for the focus
 512      * owner. In addition, KeyEventDispatchers may retarget or consume
 513      * KeyEvents before they reach the focus owner.
 514      * <p>
 515      * This method does not actually set the focus to the specified Component.
 516      * It merely stores the value to be subsequently returned by
 517      * <code>getFocusOwner()</code>. Use <code>Component.requestFocus()</code>
 518      * or <code>Component.requestFocusInWindow()</code> to change the focus
 519      * owner, subject to platform limitations.
 520      *
 521      * @param focusOwner the focus owner
 522      * @see #getFocusOwner
 523      * @see #getGlobalFocusOwner
 524      * @see Component#requestFocus()
 525      * @see Component#requestFocusInWindow()
 526      * @see Component#isFocusable
 527      * @throws SecurityException if this KeyboardFocusManager is not the
 528      *         current KeyboardFocusManager for the calling thread's context
 529      *         and if the calling thread does not have "replaceKeyboardFocusManager"
 530      *         permission
 531      * @beaninfo
 532      *       bound: true
 533      */
 534     protected void setGlobalFocusOwner(Component focusOwner)
 535         throws SecurityException
 536     {
 537         Component oldFocusOwner = null;
 538         boolean shouldFire = false;


 588      * receive focus, or a Component is given focus explicitly via a call to
 589      * {@code requestFocus()}. This operation does not change the focused or
 590      * active Windows.
 591      *
 592      * @see Component#requestFocus()
 593      * @see java.awt.event.FocusEvent#FOCUS_LOST
 594      * @since 1.8
 595      */
 596     public void clearFocusOwner() {
 597         if (getFocusOwner() != null) {
 598             clearGlobalFocusOwner();
 599         }
 600     }
 601 
 602     /**
 603      * Clears the global focus owner at both the Java and native levels. If
 604      * there exists a focus owner, that Component will receive a permanent
 605      * FOCUS_LOST event. After this operation completes, the native windowing
 606      * system will discard all user-generated KeyEvents until the user selects
 607      * a new Component to receive focus, or a Component is given focus
 608      * explicitly via a call to <code>requestFocus()</code>. This operation
 609      * does not change the focused or active Windows.
 610      * <p>
 611      * If a SecurityManager is installed, the calling thread must be granted
 612      * the "replaceKeyboardFocusManager" AWTPermission. If this permission is
 613      * not granted, this method will throw a SecurityException, and the current
 614      * focus owner will not be cleared.
 615      * <p>
 616      * This method is intended to be used only by KeyboardFocusManager set as
 617      * current KeyboardFocusManager for the calling thread's context. It is not
 618      * for general client use.
 619      *
 620      * @see KeyboardFocusManager#clearFocusOwner
 621      * @see Component#requestFocus()
 622      * @see java.awt.event.FocusEvent#FOCUS_LOST
 623      * @throws SecurityException if the calling thread does not have
 624      *         "replaceKeyboardFocusManager" permission
 625      */
 626     public void clearGlobalFocusOwner()
 627         throws SecurityException
 628     {


 712     protected Component getGlobalPermanentFocusOwner()
 713         throws SecurityException
 714     {
 715         synchronized (KeyboardFocusManager.class) {
 716             checkKFMSecurity();
 717             return permanentFocusOwner;
 718         }
 719     }
 720 
 721     /**
 722      * Sets the permanent focus owner. The operation will be cancelled if the
 723      * Component is not focusable. The permanent focus owner is defined as the
 724      * last Component in an application to receive a permanent FOCUS_GAINED
 725      * event. The focus owner and permanent focus owner are equivalent unless
 726      * a temporary focus change is currently in effect. In such a situation,
 727      * the permanent focus owner will again be the focus owner when the
 728      * temporary focus change ends.
 729      * <p>
 730      * This method does not actually set the focus to the specified Component.
 731      * It merely stores the value to be subsequently returned by
 732      * <code>getPermanentFocusOwner()</code>. Use
 733      * <code>Component.requestFocus()</code> or
 734      * <code>Component.requestFocusInWindow()</code> to change the focus owner,
 735      * subject to platform limitations.
 736      *
 737      * @param permanentFocusOwner the permanent focus owner
 738      * @see #getPermanentFocusOwner
 739      * @see #getGlobalPermanentFocusOwner
 740      * @see Component#requestFocus()
 741      * @see Component#requestFocusInWindow()
 742      * @see Component#isFocusable
 743      * @throws SecurityException if this KeyboardFocusManager is not the
 744      *         current KeyboardFocusManager for the calling thread's context
 745      *         and if the calling thread does not have "replaceKeyboardFocusManager"
 746      *         permission
 747      * @beaninfo
 748      *       bound: true
 749      */
 750     protected void setGlobalPermanentFocusOwner(Component permanentFocusOwner)
 751         throws SecurityException
 752     {
 753         Component oldPermanentFocusOwner = null;
 754         boolean shouldFire = false;


 815      * @see #setGlobalFocusedWindow
 816      * @throws SecurityException if this KeyboardFocusManager is not the
 817      *         current KeyboardFocusManager for the calling thread's context
 818      *         and if the calling thread does not have "replaceKeyboardFocusManager"
 819      *         permission
 820      */
 821     protected Window getGlobalFocusedWindow() throws SecurityException {
 822         synchronized (KeyboardFocusManager.class) {
 823             checkKFMSecurity();
 824             return focusedWindow;
 825         }
 826     }
 827 
 828     /**
 829      * Sets the focused Window. The focused Window is the Window that is or
 830      * contains the focus owner. The operation will be cancelled if the
 831      * specified Window to focus is not a focusable Window.
 832      * <p>
 833      * This method does not actually change the focused Window as far as the
 834      * native windowing system is concerned. It merely stores the value to be
 835      * subsequently returned by <code>getFocusedWindow()</code>. Use
 836      * <code>Component.requestFocus()</code> or
 837      * <code>Component.requestFocusInWindow()</code> to change the focused
 838      * Window, subject to platform limitations.
 839      *
 840      * @param focusedWindow the focused Window
 841      * @see #getFocusedWindow
 842      * @see #getGlobalFocusedWindow
 843      * @see Component#requestFocus()
 844      * @see Component#requestFocusInWindow()
 845      * @see Window#isFocusableWindow
 846      * @throws SecurityException if this KeyboardFocusManager is not the
 847      *         current KeyboardFocusManager for the calling thread's context
 848      *         and if the calling thread does not have "replaceKeyboardFocusManager"
 849      *         permission
 850      * @beaninfo
 851      *       bound: true
 852      */
 853     protected void setGlobalFocusedWindow(Window focusedWindow)
 854         throws SecurityException
 855     {
 856         Window oldFocusedWindow = null;
 857         boolean shouldFire = false;


 921      *         current KeyboardFocusManager for the calling thread's context
 922      *         and if the calling thread does not have "replaceKeyboardFocusManager"
 923      *         permission
 924      */
 925     protected Window getGlobalActiveWindow() throws SecurityException {
 926         synchronized (KeyboardFocusManager.class) {
 927             checkKFMSecurity();
 928             return activeWindow;
 929         }
 930     }
 931 
 932     /**
 933      * Sets the active Window. Only a Frame or a Dialog can be the active
 934      * Window. The native windowing system may denote the active Window or its
 935      * children with special decorations, such as a highlighted title bar. The
 936      * active Window is always either the focused Window, or the first Frame or
 937      * Dialog that is an owner of the focused Window.
 938      * <p>
 939      * This method does not actually change the active Window as far as the
 940      * native windowing system is concerned. It merely stores the value to be
 941      * subsequently returned by <code>getActiveWindow()</code>. Use
 942      * <code>Component.requestFocus()</code> or
 943      * <code>Component.requestFocusInWindow()</code>to change the active
 944      * Window, subject to platform limitations.
 945      *
 946      * @param activeWindow the active Window
 947      * @see #getActiveWindow
 948      * @see #getGlobalActiveWindow
 949      * @see Component#requestFocus()
 950      * @see Component#requestFocusInWindow()
 951      * @throws SecurityException if this KeyboardFocusManager is not the
 952      *         current KeyboardFocusManager for the calling thread's context
 953      *         and if the calling thread does not have "replaceKeyboardFocusManager"
 954      *         permission
 955      * @beaninfo
 956      *       bound: true
 957      */
 958     protected void setGlobalActiveWindow(Window activeWindow)
 959         throws SecurityException
 960     {
 961         Window oldActiveWindow;
 962         synchronized (KeyboardFocusManager.class) {
 963             checkKFMSecurity();


1151                         throw new IllegalArgumentException("focus traversal keys must be unique for a Component");
1152                     }
1153                 }
1154             }
1155 
1156             oldKeys = defaultFocusTraversalKeys[id];
1157             defaultFocusTraversalKeys[id] =
1158                 Collections.unmodifiableSet(new HashSet<>(keystrokes));
1159         }
1160 
1161         firePropertyChange(defaultFocusTraversalKeyPropertyNames[id],
1162                            oldKeys, keystrokes);
1163     }
1164 
1165     /**
1166      * Returns a Set of default focus traversal keys for a given traversal
1167      * operation. This traversal key Set will be in effect on all Windows that
1168      * have no such Set of their own explicitly defined. This Set will also be
1169      * inherited, recursively, by any child Component of those Windows that has
1170      * no such Set of its own explicitly defined. (See
1171      * <code>setDefaultFocusTraversalKeys</code> for a full description of each
1172      * operation.)
1173      *
1174      * @param id one of KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
1175      *        KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS,
1176      *        KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS, or
1177      *        KeyboardFocusManager.DOWN_CYCLE_TRAVERSAL_KEYS
1178      * @return the <code>Set</code> of <code>AWTKeyStroke</code>s
1179      *         for the specified operation; the <code>Set</code>
1180      *         will be unmodifiable, and may be empty; <code>null</code>
1181      *         will never be returned
1182      * @see #setDefaultFocusTraversalKeys
1183      * @see Component#setFocusTraversalKeys
1184      * @see Component#getFocusTraversalKeys
1185      * @throws IllegalArgumentException if id is not one of
1186      *         KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
1187      *         KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS,
1188      *         KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS, or
1189      *         KeyboardFocusManager.DOWN_CYCLE_TRAVERSAL_KEYS
1190      */
1191     public Set<AWTKeyStroke> getDefaultFocusTraversalKeys(int id) {
1192         if (id < 0 || id >= TRAVERSAL_KEY_LENGTH) {
1193             throw new IllegalArgumentException("invalid focus traversal key identifier");
1194         }
1195 
1196         // Okay to return Set directly because it is an unmodifiable view
1197         return defaultFocusTraversalKeys[id];
1198     }
1199 
1200     /**


1352      * @param listener the PropertyChangeListener to be removed
1353      * @see #addPropertyChangeListener
1354      * @see #getPropertyChangeListeners
1355      * @see #removePropertyChangeListener(java.lang.String,java.beans.PropertyChangeListener)
1356      */
1357     public void removePropertyChangeListener(PropertyChangeListener listener) {
1358         if (listener != null) {
1359             synchronized (this) {
1360                 if (changeSupport != null) {
1361                     changeSupport.removePropertyChangeListener(listener);
1362                 }
1363             }
1364         }
1365     }
1366 
1367     /**
1368      * Returns an array of all the property change listeners
1369      * registered on this keyboard focus manager.
1370      *
1371      * @return all of this keyboard focus manager's
1372      *         <code>PropertyChangeListener</code>s
1373      *         or an empty array if no property change
1374      *         listeners are currently registered
1375      *
1376      * @see #addPropertyChangeListener
1377      * @see #removePropertyChangeListener
1378      * @see #getPropertyChangeListeners(java.lang.String)
1379      * @since 1.4
1380      */
1381     public synchronized PropertyChangeListener[] getPropertyChangeListeners() {
1382         if (changeSupport == null) {
1383             changeSupport = new PropertyChangeSupport(this);
1384         }
1385         return changeSupport.getPropertyChangeListeners();
1386     }
1387 
1388     /**
1389      * Adds a PropertyChangeListener to the listener list for a specific
1390      * property. The specified property may be user-defined, or one of the
1391      * following:
1392      * <ul>


1439      *
1440      * @param propertyName a valid property name
1441      * @param listener the PropertyChangeListener to be removed
1442      * @see #addPropertyChangeListener(java.lang.String,java.beans.PropertyChangeListener)
1443      * @see #getPropertyChangeListeners(java.lang.String)
1444      * @see #removePropertyChangeListener(java.beans.PropertyChangeListener)
1445      */
1446     public void removePropertyChangeListener(String propertyName,
1447                                              PropertyChangeListener listener) {
1448         if (listener != null) {
1449             synchronized (this) {
1450                 if (changeSupport != null) {
1451                     changeSupport.removePropertyChangeListener(propertyName,
1452                                                                listener);
1453                 }
1454             }
1455         }
1456     }
1457 
1458     /**
1459      * Returns an array of all the <code>PropertyChangeListener</code>s
1460      * associated with the named property.
1461      *
1462      * @param  propertyName the property name
1463      * @return all of the <code>PropertyChangeListener</code>s associated with
1464      *         the named property or an empty array if no such listeners have
1465      *         been added.
1466      *
1467      * @see #addPropertyChangeListener(java.lang.String,java.beans.PropertyChangeListener)
1468      * @see #removePropertyChangeListener(java.lang.String,java.beans.PropertyChangeListener)
1469      * @since 1.4
1470      */
1471     public synchronized PropertyChangeListener[] getPropertyChangeListeners(String propertyName) {
1472         if (changeSupport == null) {
1473             changeSupport = new PropertyChangeSupport(this);
1474         }
1475         return changeSupport.getPropertyChangeListeners(propertyName);
1476     }
1477 
1478     /**
1479      * Fires a PropertyChangeEvent in response to a change in a bound property.
1480      * The event will be delivered to all registered PropertyChangeListeners.
1481      * No event will be delivered if oldValue and newValue are the same.
1482      *
1483      * @param propertyName the name of the property that has changed


1535      * @param listener the VetoableChangeListener to be removed
1536      * @see #addVetoableChangeListener
1537      * @see #getVetoableChangeListeners
1538      * @see #removeVetoableChangeListener(java.lang.String,java.beans.VetoableChangeListener)
1539      */
1540     public void removeVetoableChangeListener(VetoableChangeListener listener) {
1541         if (listener != null) {
1542             synchronized (this) {
1543                 if (vetoableSupport != null) {
1544                     vetoableSupport.removeVetoableChangeListener(listener);
1545                 }
1546             }
1547         }
1548     }
1549 
1550     /**
1551      * Returns an array of all the vetoable change listeners
1552      * registered on this keyboard focus manager.
1553      *
1554      * @return all of this keyboard focus manager's
1555      *         <code>VetoableChangeListener</code>s
1556      *         or an empty array if no vetoable change
1557      *         listeners are currently registered
1558      *
1559      * @see #addVetoableChangeListener
1560      * @see #removeVetoableChangeListener
1561      * @see #getVetoableChangeListeners(java.lang.String)
1562      * @since 1.4
1563      */
1564     public synchronized VetoableChangeListener[] getVetoableChangeListeners() {
1565         if (vetoableSupport == null) {
1566             vetoableSupport = new VetoableChangeSupport(this);
1567         }
1568         return vetoableSupport.getVetoableChangeListeners();
1569     }
1570 
1571     /**
1572      * Adds a VetoableChangeListener to the listener list for a specific
1573      * property. The specified property may be user-defined, or one of the
1574      * following:
1575      * <ul>


1609      *
1610      * @param propertyName a valid property name
1611      * @param listener the VetoableChangeListener to be removed
1612      * @see #addVetoableChangeListener
1613      * @see #getVetoableChangeListeners
1614      * @see #removeVetoableChangeListener(java.beans.VetoableChangeListener)
1615      */
1616     public void removeVetoableChangeListener(String propertyName,
1617                                              VetoableChangeListener listener) {
1618         if (listener != null) {
1619             synchronized (this) {
1620                 if (vetoableSupport != null) {
1621                     vetoableSupport.removeVetoableChangeListener(propertyName,
1622                                                                  listener);
1623                 }
1624             }
1625         }
1626     }
1627 
1628     /**
1629      * Returns an array of all the <code>VetoableChangeListener</code>s
1630      * associated with the named property.
1631      *
1632      * @param  propertyName the property name
1633      * @return all of the <code>VetoableChangeListener</code>s associated with
1634      *         the named property or an empty array if no such listeners have
1635      *         been added.
1636      *
1637      * @see #addVetoableChangeListener(java.lang.String,java.beans.VetoableChangeListener)
1638      * @see #removeVetoableChangeListener(java.lang.String,java.beans.VetoableChangeListener)
1639      * @see #getVetoableChangeListeners
1640      * @since 1.4
1641      */
1642     public synchronized VetoableChangeListener[] getVetoableChangeListeners(String propertyName) {
1643         if (vetoableSupport == null) {
1644             vetoableSupport = new VetoableChangeSupport(this);
1645         }
1646         return vetoableSupport.getVetoableChangeListeners(propertyName);
1647     }
1648 
1649     /**
1650      * Fires a PropertyChangeEvent in response to a change in a vetoable
1651      * property. The event will be delivered to all registered
1652      * VetoableChangeListeners. If a VetoableChangeListener throws a
1653      * PropertyVetoException, a new event is fired reverting all
1654      * VetoableChangeListeners to the old value and the exception is then
1655      * rethrown. No event will be delivered if oldValue and newValue are the
1656      * same.
1657      *
1658      * @param propertyName the name of the property that has changed
1659      * @param oldValue the property's previous value
1660      * @param newValue the property's new value
1661      * @throws java.beans.PropertyVetoException if a
1662      *         <code>VetoableChangeListener</code> threw
1663      *         <code>PropertyVetoException</code>
1664      */
1665     protected void fireVetoableChange(String propertyName, Object oldValue,
1666                                       Object newValue)
1667         throws PropertyVetoException
1668     {
1669         if (oldValue == newValue) {
1670             return;
1671         }
1672         VetoableChangeSupport vetoableSupport =
1673             this.vetoableSupport;
1674         if (vetoableSupport != null) {
1675             vetoableSupport.fireVetoableChange(propertyName, oldValue,
1676                                                newValue);
1677         }
1678     }
1679 
1680     /**
1681      * Adds a KeyEventDispatcher to this KeyboardFocusManager's dispatcher
1682      * chain. This KeyboardFocusManager will request that each
1683      * KeyEventDispatcher dispatch KeyEvents generated by the user before
1684      * finally dispatching the KeyEvent itself. KeyEventDispatchers will be
1685      * notified in the order in which they were added. Notifications will halt
1686      * as soon as one KeyEventDispatcher returns <code>true</code> from its
1687      * <code>dispatchKeyEvent</code> method. There is no limit to the total
1688      * number of KeyEventDispatchers which can be added, nor to the number of
1689      * times which a particular KeyEventDispatcher instance can be added.
1690      * <p>
1691      * If a null dispatcher is specified, no action is taken and no exception
1692      * is thrown.
1693      * <p>
1694      * In a multithreaded application, {@link KeyEventDispatcher} behaves
1695      * the same as other AWT listeners.  See
1696      * <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
1697      * >AWT Threading Issues</a> for more details.
1698      *
1699      * @param dispatcher the KeyEventDispatcher to add to the dispatcher chain
1700      * @see #removeKeyEventDispatcher
1701      */
1702     public void addKeyEventDispatcher(KeyEventDispatcher dispatcher) {
1703         if (dispatcher != null) {
1704             synchronized (this) {
1705                 if (keyEventDispatchers == null) {
1706                     keyEventDispatchers = new java.util.LinkedList<>();
1707                 }
1708                 keyEventDispatchers.add(dispatcher);
1709             }
1710         }
1711     }
1712 
1713     /**
1714      * Removes a KeyEventDispatcher which was previously added to this
1715      * KeyboardFocusManager's dispatcher chain. This KeyboardFocusManager
1716      * cannot itself be removed, unless it was explicitly re-registered via a
1717      * call to <code>addKeyEventDispatcher</code>.
1718      * <p>
1719      * If a null dispatcher is specified, if the specified dispatcher is not
1720      * in the dispatcher chain, or if this KeyboardFocusManager is specified
1721      * without having been explicitly re-registered, no action is taken and no
1722      * exception is thrown.
1723      * <p>
1724      * In a multithreaded application, {@link KeyEventDispatcher} behaves
1725      * the same as other AWT listeners.  See
1726      * <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
1727      * >AWT Threading Issues</a> for more details.
1728      *
1729      * @param dispatcher the KeyEventDispatcher to remove from the dispatcher
1730      *        chain
1731      * @see #addKeyEventDispatcher
1732      */
1733     public void removeKeyEventDispatcher(KeyEventDispatcher dispatcher) {
1734         if (dispatcher != null) {
1735             synchronized (this) {
1736                 if (keyEventDispatchers != null) {
1737                     keyEventDispatchers.remove(dispatcher);
1738                 }
1739             }
1740         }
1741     }
1742 
1743     /**
1744      * Returns this KeyboardFocusManager's KeyEventDispatcher chain as a List.
1745      * The List will not include this KeyboardFocusManager unless it was
1746      * explicitly re-registered via a call to
1747      * <code>addKeyEventDispatcher</code>. If no other KeyEventDispatchers are
1748      * registered, implementations are free to return null or a List of length
1749      * 0. Client code should not assume one behavior over another, nor should
1750      * it assume that the behavior, once established, will not change.
1751      *
1752      * @return a possibly null or empty List of KeyEventDispatchers
1753      * @see #addKeyEventDispatcher
1754      * @see #removeKeyEventDispatcher
1755      */
1756     @SuppressWarnings("unchecked") // Cast of result of clone
1757     protected synchronized java.util.List<KeyEventDispatcher>
1758         getKeyEventDispatchers()
1759     {
1760         return (keyEventDispatchers != null)
1761             ? (java.util.List<KeyEventDispatcher>)keyEventDispatchers.clone()
1762             : null;
1763     }
1764 
1765     /**
1766      * Adds a KeyEventPostProcessor to this KeyboardFocusManager's post-
1767      * processor chain. After a KeyEvent has been dispatched to and handled by
1768      * its target, KeyboardFocusManager will request that each
1769      * KeyEventPostProcessor perform any necessary post-processing as part
1770      * of the KeyEvent's final resolution. KeyEventPostProcessors
1771      * will be notified in the order in which they were added; the current
1772      * KeyboardFocusManager will be notified last. Notifications will halt
1773      * as soon as one KeyEventPostProcessor returns <code>true</code> from its
1774      * <code>postProcessKeyEvent</code> method. There is no limit to the
1775      * total number of KeyEventPostProcessors that can be added, nor to the
1776      * number of times that a particular KeyEventPostProcessor instance can be
1777      * added.
1778      * <p>
1779      * If a null post-processor is specified, no action is taken and no
1780      * exception is thrown.
1781      * <p>
1782      * In a multithreaded application, {@link KeyEventPostProcessor} behaves
1783      * the same as other AWT listeners.  See
1784      * <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
1785      * >AWT Threading Issues</a> for more details.
1786      *
1787      * @param processor the KeyEventPostProcessor to add to the post-processor
1788      *        chain
1789      * @see #removeKeyEventPostProcessor
1790      */
1791     public void addKeyEventPostProcessor(KeyEventPostProcessor processor) {
1792         if (processor != null) {
1793             synchronized (this) {
1794                 if (keyEventPostProcessors == null) {
1795                     keyEventPostProcessors = new java.util.LinkedList<>();
1796                 }
1797                 keyEventPostProcessors.add(processor);
1798             }
1799         }
1800     }
1801 
1802 
1803     /**
1804      * Removes a previously added KeyEventPostProcessor from this
1805      * KeyboardFocusManager's post-processor chain. This KeyboardFocusManager
1806      * cannot itself be entirely removed from the chain. Only additional
1807      * references added via <code>addKeyEventPostProcessor</code> can be
1808      * removed.
1809      * <p>
1810      * If a null post-processor is specified, if the specified post-processor
1811      * is not in the post-processor chain, or if this KeyboardFocusManager is
1812      * specified without having been explicitly added, no action is taken and
1813      * no exception is thrown.
1814      * <p>
1815      * In a multithreaded application, {@link KeyEventPostProcessor} behaves
1816      * the same as other AWT listeners.  See
1817      * <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
1818      * >AWT Threading Issues</a> for more details.
1819      *
1820      * @param processor the KeyEventPostProcessor to remove from the post-
1821      *        processor chain
1822      * @see #addKeyEventPostProcessor
1823      */
1824     public void removeKeyEventPostProcessor(KeyEventPostProcessor processor) {
1825         if (processor != null) {
1826             synchronized (this) {
1827                 if (keyEventPostProcessors != null) {
1828                     keyEventPostProcessors.remove(processor);
1829                 }
1830             }
1831         }
1832     }
1833 
1834 
1835     /**
1836      * Returns this KeyboardFocusManager's KeyEventPostProcessor chain as a
1837      * List. The List will not include this KeyboardFocusManager unless it was
1838      * explicitly added via a call to <code>addKeyEventPostProcessor</code>. If
1839      * no KeyEventPostProcessors are registered, implementations are free to
1840      * return null or a List of length 0. Client code should not assume one
1841      * behavior over another, nor should it assume that the behavior, once
1842      * established, will not change.
1843      *
1844      * @return a possibly null or empty List of KeyEventPostProcessors
1845      * @see #addKeyEventPostProcessor
1846      * @see #removeKeyEventPostProcessor
1847      */
1848     @SuppressWarnings("unchecked") // Cast of result of clone
1849     protected java.util.List<KeyEventPostProcessor>
1850         getKeyEventPostProcessors()
1851     {
1852         return (keyEventPostProcessors != null)
1853             ? (java.util.List<KeyEventPostProcessor>)keyEventPostProcessors.clone()
1854             : null;
1855     }
1856 
1857 
1858 


1907         }
1908     }
1909 
1910     /*
1911      * Please be careful changing this method! It is called from
1912      * javax.swing.JComponent.runInputVerifier() using reflection.
1913      */
1914     static synchronized Component getMostRecentFocusOwner(Window window) {
1915         WeakReference<Component> weakValue = mostRecentFocusOwners.get(window);
1916         return weakValue == null ? null : weakValue.get();
1917     }
1918 
1919     /**
1920      * This method is called by the AWT event dispatcher requesting that the
1921      * current KeyboardFocusManager dispatch the specified event on its behalf.
1922      * It is expected that all KeyboardFocusManagers will dispatch all
1923      * FocusEvents, all WindowEvents related to focus, and all KeyEvents.
1924      * These events should be dispatched based on the KeyboardFocusManager's
1925      * notion of the focus owner and the focused and active Windows, sometimes
1926      * overriding the source of the specified AWTEvent. Dispatching must be
1927      * done using <code>redispatchEvent</code> to prevent the AWT event
1928      * dispatcher from recursively requesting that the KeyboardFocusManager
1929      * dispatch the event again. If this method returns <code>false</code>,
1930      * then the AWT event dispatcher will attempt to dispatch the event itself.
1931      *
1932      * @param e the AWTEvent to be dispatched
1933      * @return <code>true</code> if this method dispatched the event;
1934      *         <code>false</code> otherwise
1935      * @see #redispatchEvent
1936      * @see #dispatchKeyEvent
1937      */
1938     public abstract boolean dispatchEvent(AWTEvent e);
1939 
1940     /**
1941      * Redispatches an AWTEvent in such a way that the AWT event dispatcher
1942      * will not recursively request that the KeyboardFocusManager, or any
1943      * installed KeyEventDispatchers, dispatch the event again. Client
1944      * implementations of <code>dispatchEvent</code> and client-defined
1945      * KeyEventDispatchers must call <code>redispatchEvent(target, e)</code>
1946      * instead of <code>target.dispatchEvent(e)</code> to dispatch an event.
1947      * <p>
1948      * This method is intended to be used only by KeyboardFocusManagers and
1949      * KeyEventDispatchers. It is not for general client use.
1950      *
1951      * @param target the Component to which the event should be dispatched
1952      * @param e the event to dispatch
1953      * @see #dispatchEvent
1954      * @see KeyEventDispatcher
1955      */
1956     public final void redispatchEvent(Component target, AWTEvent e) {
1957         e.focusManagerIsDispatching = true;
1958         target.dispatchEvent(e);
1959         e.focusManagerIsDispatching = false;
1960     }
1961 
1962     /**
1963      * Typically this method will be called by <code>dispatchEvent</code> if no
1964      * other KeyEventDispatcher in the dispatcher chain dispatched the
1965      * KeyEvent, or if no other KeyEventDispatchers are registered. If an
1966      * implementation of this method returns <code>false</code>,
1967      * <code>dispatchEvent</code> may try to dispatch the KeyEvent itself, or
1968      * may simply return <code>false</code>. If <code>true</code> is returned,
1969      * <code>dispatchEvent</code> should return <code>true</code> as well.
1970      *
1971      * @param e the KeyEvent which the current KeyboardFocusManager has
1972      *        requested that this KeyEventDispatcher dispatch
1973      * @return <code>true</code> if the KeyEvent was dispatched;
1974      *         <code>false</code> otherwise
1975      * @see #dispatchEvent
1976      */
1977     public abstract boolean dispatchKeyEvent(KeyEvent e);
1978 
1979     /**
1980      * This method will be called by <code>dispatchKeyEvent</code>.
1981      * By default, this method will handle any unconsumed KeyEvents that
1982      * map to an AWT <code>MenuShortcut</code> by consuming the event
1983      * and activating the shortcut.
1984      *
1985      * @param e the KeyEvent to post-process
1986      * @return <code>true</code> to indicate that no other
1987      *         KeyEventPostProcessor will be notified of the KeyEvent.
1988      * @see #dispatchKeyEvent
1989      * @see MenuShortcut
1990      */
1991     public abstract boolean postProcessKeyEvent(KeyEvent e);
1992 
1993     /**
1994      * This method initiates a focus traversal operation if and only if the
1995      * KeyEvent represents a focus traversal key for the specified
1996      * focusedComponent. It is expected that focusedComponent is the current
1997      * focus owner, although this need not be the case. If it is not,
1998      * focus traversal will nevertheless proceed as if focusedComponent
1999      * were the current focus owner.
2000      *
2001      * @param focusedComponent the Component that will be the basis for a focus
2002      *        traversal operation if the specified event represents a focus
2003      *        traversal key for the Component
2004      * @param e the event that may represent a focus traversal key
2005      */
2006     public abstract void processKeyEvent(Component focusedComponent,
2007                                          KeyEvent e);
2008 
2009     /**
2010      * Called by the AWT to notify the KeyboardFocusManager that it should
2011      * delay dispatching of KeyEvents until the specified Component becomes
2012      * the focus owner. If client code requests a focus change, and the AWT
2013      * determines that this request might be granted by the native windowing
2014      * system, then the AWT will call this method. It is the responsibility of
2015      * the KeyboardFocusManager to delay dispatching of KeyEvents with
2016      * timestamps later than the specified time stamp until the specified
2017      * Component receives a FOCUS_GAINED event, or the AWT cancels the delay
2018      * request by invoking <code>dequeueKeyEvents</code> or
2019      * <code>discardKeyEvents</code>.
2020      *
2021      * @param after timestamp of current event, or the current, system time if
2022      *        the current event has no timestamp, or the AWT cannot determine
2023      *        which event is currently being handled
2024      * @param untilFocused Component which should receive a FOCUS_GAINED event
2025      *        before any pending KeyEvents
2026      * @see #dequeueKeyEvents
2027      * @see #discardKeyEvents
2028      */
2029     protected abstract void enqueueKeyEvents(long after,
2030                                              Component untilFocused);
2031 
2032     /**
2033      * Called by the AWT to notify the KeyboardFocusManager that it should
2034      * cancel delayed dispatching of KeyEvents. All KeyEvents which were
2035      * enqueued because of a call to <code>enqueueKeyEvents</code> with the
2036      * same timestamp and Component should be released for normal dispatching
2037      * to the current focus owner. If the given timestamp is less than zero,
2038      * the outstanding enqueue request for the given Component with the <b>
2039      * oldest</b> timestamp (if any) should be cancelled.
2040      *
2041      * @param after the timestamp specified in the call to
2042      *        <code>enqueueKeyEvents</code>, or any value &lt; 0
2043      * @param untilFocused the Component specified in the call to
2044      *        <code>enqueueKeyEvents</code>
2045      * @see #enqueueKeyEvents
2046      * @see #discardKeyEvents
2047      */
2048     protected abstract void dequeueKeyEvents(long after,
2049                                              Component untilFocused);
2050 
2051     /**
2052      * Called by the AWT to notify the KeyboardFocusManager that it should
2053      * cancel delayed dispatching of KeyEvents. All KeyEvents which were
2054      * enqueued because of one or more calls to <code>enqueueKeyEvents</code>
2055      * with the same Component should be discarded.
2056      *
2057      * @param comp the Component specified in one or more calls to
2058      *        <code>enqueueKeyEvents</code>
2059      * @see #enqueueKeyEvents
2060      * @see #dequeueKeyEvents
2061      */
2062     protected abstract void discardKeyEvents(Component comp);
2063 
2064     /**
2065      * Focuses the Component after aComponent, typically based on a
2066      * FocusTraversalPolicy.
2067      *
2068      * @param aComponent the Component that is the basis for the focus
2069      *        traversal operation
2070      * @see FocusTraversalPolicy
2071      */
2072     public abstract void focusNextComponent(Component aComponent);
2073 
2074     /**
2075      * Focuses the Component before aComponent, typically based on a
2076      * FocusTraversalPolicy.
2077      *
2078      * @param aComponent the Component that is the basis for the focus




 356      * root, then it may be ambiguous as to which Components represent the next
 357      * and previous Components to focus during normal focus traversal. In that
 358      * case, the current focus cycle root is used to differentiate among the
 359      * possibilities.
 360      */
 361     private static Container currentFocusCycleRoot;
 362 
 363     /**
 364      * A description of any VetoableChangeListeners which have been registered.
 365      */
 366     private VetoableChangeSupport vetoableSupport;
 367 
 368     /**
 369      * A description of any PropertyChangeListeners which have been registered.
 370      */
 371     private PropertyChangeSupport changeSupport;
 372 
 373     /**
 374      * This KeyboardFocusManager's KeyEventDispatcher chain. The List does not
 375      * include this KeyboardFocusManager unless it was explicitly re-registered
 376      * via a call to {@code addKeyEventDispatcher}. If no other
 377      * KeyEventDispatchers are registered, this field may be null or refer to
 378      * a List of length 0.
 379      */
 380     private java.util.LinkedList<KeyEventDispatcher> keyEventDispatchers;
 381 
 382     /**
 383      * This KeyboardFocusManager's KeyEventPostProcessor chain. The List does
 384      * not include this KeyboardFocusManager unless it was explicitly
 385      * re-registered via a call to {@code addKeyEventPostProcessor}.
 386      * If no other KeyEventPostProcessors are registered, this field may be
 387      * null or refer to a List of length 0.
 388      */
 389     private java.util.LinkedList<KeyEventPostProcessor> keyEventPostProcessors;
 390 
 391     /**
 392      * Maps Windows to those Windows' most recent focus owners.
 393      */
 394     private static java.util.Map<Window, WeakReference<Component>> mostRecentFocusOwners = new WeakHashMap<>();
 395 
 396     /**
 397      * We cache the permission used to verify that the calling thread is
 398      * permitted to access the global focus state.
 399      */
 400     private static AWTPermission replaceKeyboardFocusManagerPermission;
 401 
 402     /*
 403      * SequencedEvent which is currently dispatched in AppContext.
 404      */
 405     transient SequencedEvent currentSequencedEvent = null;


 497      *         permission
 498      */
 499     protected Component getGlobalFocusOwner() throws SecurityException {
 500         synchronized (KeyboardFocusManager.class) {
 501             checkKFMSecurity();
 502             return focusOwner;
 503         }
 504     }
 505 
 506     /**
 507      * Sets the focus owner. The operation will be cancelled if the Component
 508      * is not focusable. The focus owner is defined as the Component in an
 509      * application that will typically receive all KeyEvents generated by the
 510      * user. KeyEvents which map to the focus owner's focus traversal keys will
 511      * not be delivered if focus traversal keys are enabled for the focus
 512      * owner. In addition, KeyEventDispatchers may retarget or consume
 513      * KeyEvents before they reach the focus owner.
 514      * <p>
 515      * This method does not actually set the focus to the specified Component.
 516      * It merely stores the value to be subsequently returned by
 517      * {@code getFocusOwner()}. Use {@code Component.requestFocus()}
 518      * or {@code Component.requestFocusInWindow()} to change the focus
 519      * owner, subject to platform limitations.
 520      *
 521      * @param focusOwner the focus owner
 522      * @see #getFocusOwner
 523      * @see #getGlobalFocusOwner
 524      * @see Component#requestFocus()
 525      * @see Component#requestFocusInWindow()
 526      * @see Component#isFocusable
 527      * @throws SecurityException if this KeyboardFocusManager is not the
 528      *         current KeyboardFocusManager for the calling thread's context
 529      *         and if the calling thread does not have "replaceKeyboardFocusManager"
 530      *         permission
 531      * @beaninfo
 532      *       bound: true
 533      */
 534     protected void setGlobalFocusOwner(Component focusOwner)
 535         throws SecurityException
 536     {
 537         Component oldFocusOwner = null;
 538         boolean shouldFire = false;


 588      * receive focus, or a Component is given focus explicitly via a call to
 589      * {@code requestFocus()}. This operation does not change the focused or
 590      * active Windows.
 591      *
 592      * @see Component#requestFocus()
 593      * @see java.awt.event.FocusEvent#FOCUS_LOST
 594      * @since 1.8
 595      */
 596     public void clearFocusOwner() {
 597         if (getFocusOwner() != null) {
 598             clearGlobalFocusOwner();
 599         }
 600     }
 601 
 602     /**
 603      * Clears the global focus owner at both the Java and native levels. If
 604      * there exists a focus owner, that Component will receive a permanent
 605      * FOCUS_LOST event. After this operation completes, the native windowing
 606      * system will discard all user-generated KeyEvents until the user selects
 607      * a new Component to receive focus, or a Component is given focus
 608      * explicitly via a call to {@code requestFocus()}. This operation
 609      * does not change the focused or active Windows.
 610      * <p>
 611      * If a SecurityManager is installed, the calling thread must be granted
 612      * the "replaceKeyboardFocusManager" AWTPermission. If this permission is
 613      * not granted, this method will throw a SecurityException, and the current
 614      * focus owner will not be cleared.
 615      * <p>
 616      * This method is intended to be used only by KeyboardFocusManager set as
 617      * current KeyboardFocusManager for the calling thread's context. It is not
 618      * for general client use.
 619      *
 620      * @see KeyboardFocusManager#clearFocusOwner
 621      * @see Component#requestFocus()
 622      * @see java.awt.event.FocusEvent#FOCUS_LOST
 623      * @throws SecurityException if the calling thread does not have
 624      *         "replaceKeyboardFocusManager" permission
 625      */
 626     public void clearGlobalFocusOwner()
 627         throws SecurityException
 628     {


 712     protected Component getGlobalPermanentFocusOwner()
 713         throws SecurityException
 714     {
 715         synchronized (KeyboardFocusManager.class) {
 716             checkKFMSecurity();
 717             return permanentFocusOwner;
 718         }
 719     }
 720 
 721     /**
 722      * Sets the permanent focus owner. The operation will be cancelled if the
 723      * Component is not focusable. The permanent focus owner is defined as the
 724      * last Component in an application to receive a permanent FOCUS_GAINED
 725      * event. The focus owner and permanent focus owner are equivalent unless
 726      * a temporary focus change is currently in effect. In such a situation,
 727      * the permanent focus owner will again be the focus owner when the
 728      * temporary focus change ends.
 729      * <p>
 730      * This method does not actually set the focus to the specified Component.
 731      * It merely stores the value to be subsequently returned by
 732      * {@code getPermanentFocusOwner()}. Use
 733      * {@code Component.requestFocus()} or
 734      * {@code Component.requestFocusInWindow()} to change the focus owner,
 735      * subject to platform limitations.
 736      *
 737      * @param permanentFocusOwner the permanent focus owner
 738      * @see #getPermanentFocusOwner
 739      * @see #getGlobalPermanentFocusOwner
 740      * @see Component#requestFocus()
 741      * @see Component#requestFocusInWindow()
 742      * @see Component#isFocusable
 743      * @throws SecurityException if this KeyboardFocusManager is not the
 744      *         current KeyboardFocusManager for the calling thread's context
 745      *         and if the calling thread does not have "replaceKeyboardFocusManager"
 746      *         permission
 747      * @beaninfo
 748      *       bound: true
 749      */
 750     protected void setGlobalPermanentFocusOwner(Component permanentFocusOwner)
 751         throws SecurityException
 752     {
 753         Component oldPermanentFocusOwner = null;
 754         boolean shouldFire = false;


 815      * @see #setGlobalFocusedWindow
 816      * @throws SecurityException if this KeyboardFocusManager is not the
 817      *         current KeyboardFocusManager for the calling thread's context
 818      *         and if the calling thread does not have "replaceKeyboardFocusManager"
 819      *         permission
 820      */
 821     protected Window getGlobalFocusedWindow() throws SecurityException {
 822         synchronized (KeyboardFocusManager.class) {
 823             checkKFMSecurity();
 824             return focusedWindow;
 825         }
 826     }
 827 
 828     /**
 829      * Sets the focused Window. The focused Window is the Window that is or
 830      * contains the focus owner. The operation will be cancelled if the
 831      * specified Window to focus is not a focusable Window.
 832      * <p>
 833      * This method does not actually change the focused Window as far as the
 834      * native windowing system is concerned. It merely stores the value to be
 835      * subsequently returned by {@code getFocusedWindow()}. Use
 836      * {@code Component.requestFocus()} or
 837      * {@code Component.requestFocusInWindow()} to change the focused
 838      * Window, subject to platform limitations.
 839      *
 840      * @param focusedWindow the focused Window
 841      * @see #getFocusedWindow
 842      * @see #getGlobalFocusedWindow
 843      * @see Component#requestFocus()
 844      * @see Component#requestFocusInWindow()
 845      * @see Window#isFocusableWindow
 846      * @throws SecurityException if this KeyboardFocusManager is not the
 847      *         current KeyboardFocusManager for the calling thread's context
 848      *         and if the calling thread does not have "replaceKeyboardFocusManager"
 849      *         permission
 850      * @beaninfo
 851      *       bound: true
 852      */
 853     protected void setGlobalFocusedWindow(Window focusedWindow)
 854         throws SecurityException
 855     {
 856         Window oldFocusedWindow = null;
 857         boolean shouldFire = false;


 921      *         current KeyboardFocusManager for the calling thread's context
 922      *         and if the calling thread does not have "replaceKeyboardFocusManager"
 923      *         permission
 924      */
 925     protected Window getGlobalActiveWindow() throws SecurityException {
 926         synchronized (KeyboardFocusManager.class) {
 927             checkKFMSecurity();
 928             return activeWindow;
 929         }
 930     }
 931 
 932     /**
 933      * Sets the active Window. Only a Frame or a Dialog can be the active
 934      * Window. The native windowing system may denote the active Window or its
 935      * children with special decorations, such as a highlighted title bar. The
 936      * active Window is always either the focused Window, or the first Frame or
 937      * Dialog that is an owner of the focused Window.
 938      * <p>
 939      * This method does not actually change the active Window as far as the
 940      * native windowing system is concerned. It merely stores the value to be
 941      * subsequently returned by {@code getActiveWindow()}. Use
 942      * {@code Component.requestFocus()} or
 943      * {@code Component.requestFocusInWindow()} to change the active
 944      * Window, subject to platform limitations.
 945      *
 946      * @param activeWindow the active Window
 947      * @see #getActiveWindow
 948      * @see #getGlobalActiveWindow
 949      * @see Component#requestFocus()
 950      * @see Component#requestFocusInWindow()
 951      * @throws SecurityException if this KeyboardFocusManager is not the
 952      *         current KeyboardFocusManager for the calling thread's context
 953      *         and if the calling thread does not have "replaceKeyboardFocusManager"
 954      *         permission
 955      * @beaninfo
 956      *       bound: true
 957      */
 958     protected void setGlobalActiveWindow(Window activeWindow)
 959         throws SecurityException
 960     {
 961         Window oldActiveWindow;
 962         synchronized (KeyboardFocusManager.class) {
 963             checkKFMSecurity();


1151                         throw new IllegalArgumentException("focus traversal keys must be unique for a Component");
1152                     }
1153                 }
1154             }
1155 
1156             oldKeys = defaultFocusTraversalKeys[id];
1157             defaultFocusTraversalKeys[id] =
1158                 Collections.unmodifiableSet(new HashSet<>(keystrokes));
1159         }
1160 
1161         firePropertyChange(defaultFocusTraversalKeyPropertyNames[id],
1162                            oldKeys, keystrokes);
1163     }
1164 
1165     /**
1166      * Returns a Set of default focus traversal keys for a given traversal
1167      * operation. This traversal key Set will be in effect on all Windows that
1168      * have no such Set of their own explicitly defined. This Set will also be
1169      * inherited, recursively, by any child Component of those Windows that has
1170      * no such Set of its own explicitly defined. (See
1171      * {@code setDefaultFocusTraversalKeys} for a full description of each
1172      * operation.)
1173      *
1174      * @param id one of KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
1175      *        KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS,
1176      *        KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS, or
1177      *        KeyboardFocusManager.DOWN_CYCLE_TRAVERSAL_KEYS
1178      * @return the {@code Set} of {@code AWTKeyStroke}s
1179      *         for the specified operation; the {@code Set}
1180      *         will be unmodifiable, and may be empty; {@code null}
1181      *         will never be returned
1182      * @see #setDefaultFocusTraversalKeys
1183      * @see Component#setFocusTraversalKeys
1184      * @see Component#getFocusTraversalKeys
1185      * @throws IllegalArgumentException if id is not one of
1186      *         KeyboardFocusManager.FORWARD_TRAVERSAL_KEYS,
1187      *         KeyboardFocusManager.BACKWARD_TRAVERSAL_KEYS,
1188      *         KeyboardFocusManager.UP_CYCLE_TRAVERSAL_KEYS, or
1189      *         KeyboardFocusManager.DOWN_CYCLE_TRAVERSAL_KEYS
1190      */
1191     public Set<AWTKeyStroke> getDefaultFocusTraversalKeys(int id) {
1192         if (id < 0 || id >= TRAVERSAL_KEY_LENGTH) {
1193             throw new IllegalArgumentException("invalid focus traversal key identifier");
1194         }
1195 
1196         // Okay to return Set directly because it is an unmodifiable view
1197         return defaultFocusTraversalKeys[id];
1198     }
1199 
1200     /**


1352      * @param listener the PropertyChangeListener to be removed
1353      * @see #addPropertyChangeListener
1354      * @see #getPropertyChangeListeners
1355      * @see #removePropertyChangeListener(java.lang.String,java.beans.PropertyChangeListener)
1356      */
1357     public void removePropertyChangeListener(PropertyChangeListener listener) {
1358         if (listener != null) {
1359             synchronized (this) {
1360                 if (changeSupport != null) {
1361                     changeSupport.removePropertyChangeListener(listener);
1362                 }
1363             }
1364         }
1365     }
1366 
1367     /**
1368      * Returns an array of all the property change listeners
1369      * registered on this keyboard focus manager.
1370      *
1371      * @return all of this keyboard focus manager's
1372      *         {@code PropertyChangeListener}s
1373      *         or an empty array if no property change
1374      *         listeners are currently registered
1375      *
1376      * @see #addPropertyChangeListener
1377      * @see #removePropertyChangeListener
1378      * @see #getPropertyChangeListeners(java.lang.String)
1379      * @since 1.4
1380      */
1381     public synchronized PropertyChangeListener[] getPropertyChangeListeners() {
1382         if (changeSupport == null) {
1383             changeSupport = new PropertyChangeSupport(this);
1384         }
1385         return changeSupport.getPropertyChangeListeners();
1386     }
1387 
1388     /**
1389      * Adds a PropertyChangeListener to the listener list for a specific
1390      * property. The specified property may be user-defined, or one of the
1391      * following:
1392      * <ul>


1439      *
1440      * @param propertyName a valid property name
1441      * @param listener the PropertyChangeListener to be removed
1442      * @see #addPropertyChangeListener(java.lang.String,java.beans.PropertyChangeListener)
1443      * @see #getPropertyChangeListeners(java.lang.String)
1444      * @see #removePropertyChangeListener(java.beans.PropertyChangeListener)
1445      */
1446     public void removePropertyChangeListener(String propertyName,
1447                                              PropertyChangeListener listener) {
1448         if (listener != null) {
1449             synchronized (this) {
1450                 if (changeSupport != null) {
1451                     changeSupport.removePropertyChangeListener(propertyName,
1452                                                                listener);
1453                 }
1454             }
1455         }
1456     }
1457 
1458     /**
1459      * Returns an array of all the {@code PropertyChangeListener}s
1460      * associated with the named property.
1461      *
1462      * @param  propertyName the property name
1463      * @return all of the {@code PropertyChangeListener}s associated with
1464      *         the named property or an empty array if no such listeners have
1465      *         been added.
1466      *
1467      * @see #addPropertyChangeListener(java.lang.String,java.beans.PropertyChangeListener)
1468      * @see #removePropertyChangeListener(java.lang.String,java.beans.PropertyChangeListener)
1469      * @since 1.4
1470      */
1471     public synchronized PropertyChangeListener[] getPropertyChangeListeners(String propertyName) {
1472         if (changeSupport == null) {
1473             changeSupport = new PropertyChangeSupport(this);
1474         }
1475         return changeSupport.getPropertyChangeListeners(propertyName);
1476     }
1477 
1478     /**
1479      * Fires a PropertyChangeEvent in response to a change in a bound property.
1480      * The event will be delivered to all registered PropertyChangeListeners.
1481      * No event will be delivered if oldValue and newValue are the same.
1482      *
1483      * @param propertyName the name of the property that has changed


1535      * @param listener the VetoableChangeListener to be removed
1536      * @see #addVetoableChangeListener
1537      * @see #getVetoableChangeListeners
1538      * @see #removeVetoableChangeListener(java.lang.String,java.beans.VetoableChangeListener)
1539      */
1540     public void removeVetoableChangeListener(VetoableChangeListener listener) {
1541         if (listener != null) {
1542             synchronized (this) {
1543                 if (vetoableSupport != null) {
1544                     vetoableSupport.removeVetoableChangeListener(listener);
1545                 }
1546             }
1547         }
1548     }
1549 
1550     /**
1551      * Returns an array of all the vetoable change listeners
1552      * registered on this keyboard focus manager.
1553      *
1554      * @return all of this keyboard focus manager's
1555      *         {@code VetoableChangeListener}s
1556      *         or an empty array if no vetoable change
1557      *         listeners are currently registered
1558      *
1559      * @see #addVetoableChangeListener
1560      * @see #removeVetoableChangeListener
1561      * @see #getVetoableChangeListeners(java.lang.String)
1562      * @since 1.4
1563      */
1564     public synchronized VetoableChangeListener[] getVetoableChangeListeners() {
1565         if (vetoableSupport == null) {
1566             vetoableSupport = new VetoableChangeSupport(this);
1567         }
1568         return vetoableSupport.getVetoableChangeListeners();
1569     }
1570 
1571     /**
1572      * Adds a VetoableChangeListener to the listener list for a specific
1573      * property. The specified property may be user-defined, or one of the
1574      * following:
1575      * <ul>


1609      *
1610      * @param propertyName a valid property name
1611      * @param listener the VetoableChangeListener to be removed
1612      * @see #addVetoableChangeListener
1613      * @see #getVetoableChangeListeners
1614      * @see #removeVetoableChangeListener(java.beans.VetoableChangeListener)
1615      */
1616     public void removeVetoableChangeListener(String propertyName,
1617                                              VetoableChangeListener listener) {
1618         if (listener != null) {
1619             synchronized (this) {
1620                 if (vetoableSupport != null) {
1621                     vetoableSupport.removeVetoableChangeListener(propertyName,
1622                                                                  listener);
1623                 }
1624             }
1625         }
1626     }
1627 
1628     /**
1629      * Returns an array of all the {@code VetoableChangeListener}s
1630      * associated with the named property.
1631      *
1632      * @param  propertyName the property name
1633      * @return all of the {@code VetoableChangeListener}s associated with
1634      *         the named property or an empty array if no such listeners have
1635      *         been added.
1636      *
1637      * @see #addVetoableChangeListener(java.lang.String,java.beans.VetoableChangeListener)
1638      * @see #removeVetoableChangeListener(java.lang.String,java.beans.VetoableChangeListener)
1639      * @see #getVetoableChangeListeners
1640      * @since 1.4
1641      */
1642     public synchronized VetoableChangeListener[] getVetoableChangeListeners(String propertyName) {
1643         if (vetoableSupport == null) {
1644             vetoableSupport = new VetoableChangeSupport(this);
1645         }
1646         return vetoableSupport.getVetoableChangeListeners(propertyName);
1647     }
1648 
1649     /**
1650      * Fires a PropertyChangeEvent in response to a change in a vetoable
1651      * property. The event will be delivered to all registered
1652      * VetoableChangeListeners. If a VetoableChangeListener throws a
1653      * PropertyVetoException, a new event is fired reverting all
1654      * VetoableChangeListeners to the old value and the exception is then
1655      * rethrown. No event will be delivered if oldValue and newValue are the
1656      * same.
1657      *
1658      * @param propertyName the name of the property that has changed
1659      * @param oldValue the property's previous value
1660      * @param newValue the property's new value
1661      * @throws java.beans.PropertyVetoException if a
1662      *         {@code VetoableChangeListener} threw
1663      *         {@code PropertyVetoException}
1664      */
1665     protected void fireVetoableChange(String propertyName, Object oldValue,
1666                                       Object newValue)
1667         throws PropertyVetoException
1668     {
1669         if (oldValue == newValue) {
1670             return;
1671         }
1672         VetoableChangeSupport vetoableSupport =
1673             this.vetoableSupport;
1674         if (vetoableSupport != null) {
1675             vetoableSupport.fireVetoableChange(propertyName, oldValue,
1676                                                newValue);
1677         }
1678     }
1679 
1680     /**
1681      * Adds a KeyEventDispatcher to this KeyboardFocusManager's dispatcher
1682      * chain. This KeyboardFocusManager will request that each
1683      * KeyEventDispatcher dispatch KeyEvents generated by the user before
1684      * finally dispatching the KeyEvent itself. KeyEventDispatchers will be
1685      * notified in the order in which they were added. Notifications will halt
1686      * as soon as one KeyEventDispatcher returns {@code true} from its
1687      * {@code dispatchKeyEvent} method. There is no limit to the total
1688      * number of KeyEventDispatchers which can be added, nor to the number of
1689      * times which a particular KeyEventDispatcher instance can be added.
1690      * <p>
1691      * If a null dispatcher is specified, no action is taken and no exception
1692      * is thrown.
1693      * <p>
1694      * In a multithreaded application, {@link KeyEventDispatcher} behaves
1695      * the same as other AWT listeners.  See
1696      * <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
1697      * >AWT Threading Issues</a> for more details.
1698      *
1699      * @param dispatcher the KeyEventDispatcher to add to the dispatcher chain
1700      * @see #removeKeyEventDispatcher
1701      */
1702     public void addKeyEventDispatcher(KeyEventDispatcher dispatcher) {
1703         if (dispatcher != null) {
1704             synchronized (this) {
1705                 if (keyEventDispatchers == null) {
1706                     keyEventDispatchers = new java.util.LinkedList<>();
1707                 }
1708                 keyEventDispatchers.add(dispatcher);
1709             }
1710         }
1711     }
1712 
1713     /**
1714      * Removes a KeyEventDispatcher which was previously added to this
1715      * KeyboardFocusManager's dispatcher chain. This KeyboardFocusManager
1716      * cannot itself be removed, unless it was explicitly re-registered via a
1717      * call to {@code addKeyEventDispatcher}.
1718      * <p>
1719      * If a null dispatcher is specified, if the specified dispatcher is not
1720      * in the dispatcher chain, or if this KeyboardFocusManager is specified
1721      * without having been explicitly re-registered, no action is taken and no
1722      * exception is thrown.
1723      * <p>
1724      * In a multithreaded application, {@link KeyEventDispatcher} behaves
1725      * the same as other AWT listeners.  See
1726      * <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
1727      * >AWT Threading Issues</a> for more details.
1728      *
1729      * @param dispatcher the KeyEventDispatcher to remove from the dispatcher
1730      *        chain
1731      * @see #addKeyEventDispatcher
1732      */
1733     public void removeKeyEventDispatcher(KeyEventDispatcher dispatcher) {
1734         if (dispatcher != null) {
1735             synchronized (this) {
1736                 if (keyEventDispatchers != null) {
1737                     keyEventDispatchers.remove(dispatcher);
1738                 }
1739             }
1740         }
1741     }
1742 
1743     /**
1744      * Returns this KeyboardFocusManager's KeyEventDispatcher chain as a List.
1745      * The List will not include this KeyboardFocusManager unless it was
1746      * explicitly re-registered via a call to
1747      * {@code addKeyEventDispatcher}. If no other KeyEventDispatchers are
1748      * registered, implementations are free to return null or a List of length
1749      * 0. Client code should not assume one behavior over another, nor should
1750      * it assume that the behavior, once established, will not change.
1751      *
1752      * @return a possibly null or empty List of KeyEventDispatchers
1753      * @see #addKeyEventDispatcher
1754      * @see #removeKeyEventDispatcher
1755      */
1756     @SuppressWarnings("unchecked") // Cast of result of clone
1757     protected synchronized java.util.List<KeyEventDispatcher>
1758         getKeyEventDispatchers()
1759     {
1760         return (keyEventDispatchers != null)
1761             ? (java.util.List<KeyEventDispatcher>)keyEventDispatchers.clone()
1762             : null;
1763     }
1764 
1765     /**
1766      * Adds a KeyEventPostProcessor to this KeyboardFocusManager's post-
1767      * processor chain. After a KeyEvent has been dispatched to and handled by
1768      * its target, KeyboardFocusManager will request that each
1769      * KeyEventPostProcessor perform any necessary post-processing as part
1770      * of the KeyEvent's final resolution. KeyEventPostProcessors
1771      * will be notified in the order in which they were added; the current
1772      * KeyboardFocusManager will be notified last. Notifications will halt
1773      * as soon as one KeyEventPostProcessor returns {@code true} from its
1774      * {@code postProcessKeyEvent} method. There is no limit to the
1775      * total number of KeyEventPostProcessors that can be added, nor to the
1776      * number of times that a particular KeyEventPostProcessor instance can be
1777      * added.
1778      * <p>
1779      * If a null post-processor is specified, no action is taken and no
1780      * exception is thrown.
1781      * <p>
1782      * In a multithreaded application, {@link KeyEventPostProcessor} behaves
1783      * the same as other AWT listeners.  See
1784      * <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
1785      * >AWT Threading Issues</a> for more details.
1786      *
1787      * @param processor the KeyEventPostProcessor to add to the post-processor
1788      *        chain
1789      * @see #removeKeyEventPostProcessor
1790      */
1791     public void addKeyEventPostProcessor(KeyEventPostProcessor processor) {
1792         if (processor != null) {
1793             synchronized (this) {
1794                 if (keyEventPostProcessors == null) {
1795                     keyEventPostProcessors = new java.util.LinkedList<>();
1796                 }
1797                 keyEventPostProcessors.add(processor);
1798             }
1799         }
1800     }
1801 
1802 
1803     /**
1804      * Removes a previously added KeyEventPostProcessor from this
1805      * KeyboardFocusManager's post-processor chain. This KeyboardFocusManager
1806      * cannot itself be entirely removed from the chain. Only additional
1807      * references added via {@code addKeyEventPostProcessor} can be
1808      * removed.
1809      * <p>
1810      * If a null post-processor is specified, if the specified post-processor
1811      * is not in the post-processor chain, or if this KeyboardFocusManager is
1812      * specified without having been explicitly added, no action is taken and
1813      * no exception is thrown.
1814      * <p>
1815      * In a multithreaded application, {@link KeyEventPostProcessor} behaves
1816      * the same as other AWT listeners.  See
1817      * <a href="doc-files/AWTThreadIssues.html#ListenersThreads"
1818      * >AWT Threading Issues</a> for more details.
1819      *
1820      * @param processor the KeyEventPostProcessor to remove from the post-
1821      *        processor chain
1822      * @see #addKeyEventPostProcessor
1823      */
1824     public void removeKeyEventPostProcessor(KeyEventPostProcessor processor) {
1825         if (processor != null) {
1826             synchronized (this) {
1827                 if (keyEventPostProcessors != null) {
1828                     keyEventPostProcessors.remove(processor);
1829                 }
1830             }
1831         }
1832     }
1833 
1834 
1835     /**
1836      * Returns this KeyboardFocusManager's KeyEventPostProcessor chain as a
1837      * List. The List will not include this KeyboardFocusManager unless it was
1838      * explicitly added via a call to {@code addKeyEventPostProcessor}. If
1839      * no KeyEventPostProcessors are registered, implementations are free to
1840      * return null or a List of length 0. Client code should not assume one
1841      * behavior over another, nor should it assume that the behavior, once
1842      * established, will not change.
1843      *
1844      * @return a possibly null or empty List of KeyEventPostProcessors
1845      * @see #addKeyEventPostProcessor
1846      * @see #removeKeyEventPostProcessor
1847      */
1848     @SuppressWarnings("unchecked") // Cast of result of clone
1849     protected java.util.List<KeyEventPostProcessor>
1850         getKeyEventPostProcessors()
1851     {
1852         return (keyEventPostProcessors != null)
1853             ? (java.util.List<KeyEventPostProcessor>)keyEventPostProcessors.clone()
1854             : null;
1855     }
1856 
1857 
1858 


1907         }
1908     }
1909 
1910     /*
1911      * Please be careful changing this method! It is called from
1912      * javax.swing.JComponent.runInputVerifier() using reflection.
1913      */
1914     static synchronized Component getMostRecentFocusOwner(Window window) {
1915         WeakReference<Component> weakValue = mostRecentFocusOwners.get(window);
1916         return weakValue == null ? null : weakValue.get();
1917     }
1918 
1919     /**
1920      * This method is called by the AWT event dispatcher requesting that the
1921      * current KeyboardFocusManager dispatch the specified event on its behalf.
1922      * It is expected that all KeyboardFocusManagers will dispatch all
1923      * FocusEvents, all WindowEvents related to focus, and all KeyEvents.
1924      * These events should be dispatched based on the KeyboardFocusManager's
1925      * notion of the focus owner and the focused and active Windows, sometimes
1926      * overriding the source of the specified AWTEvent. Dispatching must be
1927      * done using {@code redispatchEvent} to prevent the AWT event
1928      * dispatcher from recursively requesting that the KeyboardFocusManager
1929      * dispatch the event again. If this method returns {@code false},
1930      * then the AWT event dispatcher will attempt to dispatch the event itself.
1931      *
1932      * @param e the AWTEvent to be dispatched
1933      * @return {@code true} if this method dispatched the event;
1934      *         {@code false} otherwise
1935      * @see #redispatchEvent
1936      * @see #dispatchKeyEvent
1937      */
1938     public abstract boolean dispatchEvent(AWTEvent e);
1939 
1940     /**
1941      * Redispatches an AWTEvent in such a way that the AWT event dispatcher
1942      * will not recursively request that the KeyboardFocusManager, or any
1943      * installed KeyEventDispatchers, dispatch the event again. Client
1944      * implementations of {@code dispatchEvent} and client-defined
1945      * KeyEventDispatchers must call {@code redispatchEvent(target, e)}
1946      * instead of {@code target.dispatchEvent(e)} to dispatch an event.
1947      * <p>
1948      * This method is intended to be used only by KeyboardFocusManagers and
1949      * KeyEventDispatchers. It is not for general client use.
1950      *
1951      * @param target the Component to which the event should be dispatched
1952      * @param e the event to dispatch
1953      * @see #dispatchEvent
1954      * @see KeyEventDispatcher
1955      */
1956     public final void redispatchEvent(Component target, AWTEvent e) {
1957         e.focusManagerIsDispatching = true;
1958         target.dispatchEvent(e);
1959         e.focusManagerIsDispatching = false;
1960     }
1961 
1962     /**
1963      * Typically this method will be called by {@code dispatchEvent} if no
1964      * other KeyEventDispatcher in the dispatcher chain dispatched the
1965      * KeyEvent, or if no other KeyEventDispatchers are registered. If an
1966      * implementation of this method returns {@code false},
1967      * {@code dispatchEvent} may try to dispatch the KeyEvent itself, or
1968      * may simply return {@code false}. If {@code true} is returned,
1969      * {@code dispatchEvent} should return {@code true} as well.
1970      *
1971      * @param e the KeyEvent which the current KeyboardFocusManager has
1972      *        requested that this KeyEventDispatcher dispatch
1973      * @return {@code true} if the KeyEvent was dispatched;
1974      *         {@code false} otherwise
1975      * @see #dispatchEvent
1976      */
1977     public abstract boolean dispatchKeyEvent(KeyEvent e);
1978 
1979     /**
1980      * This method will be called by {@code dispatchKeyEvent}.
1981      * By default, this method will handle any unconsumed KeyEvents that
1982      * map to an AWT {@code MenuShortcut} by consuming the event
1983      * and activating the shortcut.
1984      *
1985      * @param e the KeyEvent to post-process
1986      * @return {@code true} to indicate that no other
1987      *         KeyEventPostProcessor will be notified of the KeyEvent.
1988      * @see #dispatchKeyEvent
1989      * @see MenuShortcut
1990      */
1991     public abstract boolean postProcessKeyEvent(KeyEvent e);
1992 
1993     /**
1994      * This method initiates a focus traversal operation if and only if the
1995      * KeyEvent represents a focus traversal key for the specified
1996      * focusedComponent. It is expected that focusedComponent is the current
1997      * focus owner, although this need not be the case. If it is not,
1998      * focus traversal will nevertheless proceed as if focusedComponent
1999      * were the current focus owner.
2000      *
2001      * @param focusedComponent the Component that will be the basis for a focus
2002      *        traversal operation if the specified event represents a focus
2003      *        traversal key for the Component
2004      * @param e the event that may represent a focus traversal key
2005      */
2006     public abstract void processKeyEvent(Component focusedComponent,
2007                                          KeyEvent e);
2008 
2009     /**
2010      * Called by the AWT to notify the KeyboardFocusManager that it should
2011      * delay dispatching of KeyEvents until the specified Component becomes
2012      * the focus owner. If client code requests a focus change, and the AWT
2013      * determines that this request might be granted by the native windowing
2014      * system, then the AWT will call this method. It is the responsibility of
2015      * the KeyboardFocusManager to delay dispatching of KeyEvents with
2016      * timestamps later than the specified time stamp until the specified
2017      * Component receives a FOCUS_GAINED event, or the AWT cancels the delay
2018      * request by invoking {@code dequeueKeyEvents} or
2019      * {@code discardKeyEvents}.
2020      *
2021      * @param after timestamp of current event, or the current, system time if
2022      *        the current event has no timestamp, or the AWT cannot determine
2023      *        which event is currently being handled
2024      * @param untilFocused Component which should receive a FOCUS_GAINED event
2025      *        before any pending KeyEvents
2026      * @see #dequeueKeyEvents
2027      * @see #discardKeyEvents
2028      */
2029     protected abstract void enqueueKeyEvents(long after,
2030                                              Component untilFocused);
2031 
2032     /**
2033      * Called by the AWT to notify the KeyboardFocusManager that it should
2034      * cancel delayed dispatching of KeyEvents. All KeyEvents which were
2035      * enqueued because of a call to {@code enqueueKeyEvents} with the
2036      * same timestamp and Component should be released for normal dispatching
2037      * to the current focus owner. If the given timestamp is less than zero,
2038      * the outstanding enqueue request for the given Component with the <b>
2039      * oldest</b> timestamp (if any) should be cancelled.
2040      *
2041      * @param after the timestamp specified in the call to
2042      *        {@code enqueueKeyEvents}, or any value &lt; 0
2043      * @param untilFocused the Component specified in the call to
2044      *        {@code enqueueKeyEvents}
2045      * @see #enqueueKeyEvents
2046      * @see #discardKeyEvents
2047      */
2048     protected abstract void dequeueKeyEvents(long after,
2049                                              Component untilFocused);
2050 
2051     /**
2052      * Called by the AWT to notify the KeyboardFocusManager that it should
2053      * cancel delayed dispatching of KeyEvents. All KeyEvents which were
2054      * enqueued because of one or more calls to {@code enqueueKeyEvents}
2055      * with the same Component should be discarded.
2056      *
2057      * @param comp the Component specified in one or more calls to
2058      *        {@code enqueueKeyEvents}
2059      * @see #enqueueKeyEvents
2060      * @see #dequeueKeyEvents
2061      */
2062     protected abstract void discardKeyEvents(Component comp);
2063 
2064     /**
2065      * Focuses the Component after aComponent, typically based on a
2066      * FocusTraversalPolicy.
2067      *
2068      * @param aComponent the Component that is the basis for the focus
2069      *        traversal operation
2070      * @see FocusTraversalPolicy
2071      */
2072     public abstract void focusNextComponent(Component aComponent);
2073 
2074     /**
2075      * Focuses the Component before aComponent, typically based on a
2076      * FocusTraversalPolicy.
2077      *
2078      * @param aComponent the Component that is the basis for the focus


< prev index next >