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 < 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 < 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
|