55 |
import java.util.Map; |
import java.util.Map; |
56 |
import java.util.Set; |
import java.util.Set; |
57 |
|
|
|
// FIXME: finish documentation |
|
|
|
|
58 |
/** |
/** |
59 |
* |
* The <code>KeyboardFocusManager</code> handles the focusing of |
60 |
* FIXME: discuss applet contexts and thread groups and codebases |
* windows for receiving keyboard events. The manager handles |
61 |
* being insulated. |
* the dispatch of all <code>FocusEvent</code>s and |
62 |
* |
* <code>KeyEvent</code>s, along with <code>WindowEvent</code>s |
63 |
* FIXME: discuss where default focus traversal key sets apply |
* relating to the focused window. Users can use the manager |
64 |
* (inherited by child Components etc.) |
* to ascertain the current focus owner and fire events. |
65 |
|
* <br /> |
66 |
|
* <br /> |
67 |
|
* The focus owner is the <code>Component</code> that receives |
68 |
|
* key events. The focus owner is either the currently focused |
69 |
|
* window or a component within this window. |
70 |
|
* <br /> |
71 |
|
* <br /> |
72 |
|
* The underlying native windowing system may denote the active |
73 |
|
* window or its children with special decorations (e.g. a highlighted |
74 |
|
* title bar). The active window is always either a <code>Frame</code> |
75 |
|
* or <code>Dialog</code>, and is either the currently focused |
76 |
|
* window or its owner. |
77 |
|
* <br /> |
78 |
|
* <br /> |
79 |
|
* Applets may be partitioned into different applet contexts, according |
80 |
|
* to their code base. In this case, each context has its own |
81 |
|
* <code>KeyboardFocusManager</code>, as opposed to the global |
82 |
|
* manager maintained by applets which share the same context. |
83 |
|
* Each context is insulated from the others, and they don't interact. |
84 |
|
* The resulting behaviour, as with context division, depends on the browser |
85 |
|
* supporting the applets. Regardless, there can only ever be |
86 |
|
* one focused window, one active window and one focus owner |
87 |
|
* per <code>ClassLoader</code>. |
88 |
|
* <br /> |
89 |
|
* <br /> |
90 |
|
* To support this separation of focus managers, the manager instances |
91 |
|
* and the internal state information is grouped by the |
92 |
|
* <code>ThreadGroup</code> to which it pertains. With respect to |
93 |
|
* applets, each code base has its own <code>ThreadGroup</code>, so the |
94 |
|
* isolation of each context is enforced within the manager. |
95 |
|
* <br /> |
96 |
|
* <br /> |
97 |
|
* By default, the manager defines TAB and Ctrl+TAB as the |
98 |
|
* forward focus traversal keys and Shift+TAB and Ctrl+Shift+TAB |
99 |
|
* as the backward focus traversal keys. No up or down cycle |
100 |
|
* traversal keys are defined by default. Traversal takes effect |
101 |
|
* on the firing of a relevant <code>KEY_PRESSED</code> event. |
102 |
|
* However, all other key events related to the use of the |
103 |
|
* defined focus traversal key sequence are consumed and not |
104 |
|
* dispatched. |
105 |
|
* <br /> |
106 |
|
* <br /> |
107 |
|
* These default traversal keys come into effect on all windows |
108 |
|
* for which no alternative set of keys is defined. This also |
109 |
|
* applies recursively to any child components of such a window, |
110 |
|
* which define no traversal keys of their own. |
111 |
* |
* |
112 |
* @author Eric Blake <ebb9@email.byu.edu> |
* @author Eric Blake <ebb9@email.byu.edu> |
113 |
* @author Thomas Fitzsimmons <fitzsim@redhat.com> |
* @author Thomas Fitzsimmons <fitzsim@redhat.com> |
114 |
|
* @author Andrew John Hughes <gnu_andrew@member.fsf.org> |
115 |
* @since 1.4 |
* @since 1.4 |
|
* @status partially updated to 1.4, needs documentation. |
|
116 |
*/ |
*/ |
117 |
public abstract class KeyboardFocusManager |
public abstract class KeyboardFocusManager |
118 |
implements KeyEventDispatcher, KeyEventPostProcessor |
implements KeyEventDispatcher, KeyEventPostProcessor |
226 |
Collections.EMPTY_SET, Collections.EMPTY_SET |
Collections.EMPTY_SET, Collections.EMPTY_SET |
227 |
}; |
}; |
228 |
|
|
229 |
|
/** |
230 |
|
* A utility class to support the handling of events relating to property changes. |
231 |
|
*/ |
232 |
private final PropertyChangeSupport propertyChangeSupport = new PropertyChangeSupport (this); |
private final PropertyChangeSupport propertyChangeSupport = new PropertyChangeSupport (this); |
233 |
|
|
234 |
|
/** |
235 |
|
* A utility class to support the handling of events relating to vetoable changes. |
236 |
|
*/ |
237 |
private final VetoableChangeSupport vetoableChangeSupport = new VetoableChangeSupport (this); |
private final VetoableChangeSupport vetoableChangeSupport = new VetoableChangeSupport (this); |
238 |
|
|
239 |
/** A list of {@link KeyEventDispatcher}s that process {@link |
/** A list of {@link KeyEventDispatcher}s that process {@link |
674 |
setGlobalObject (currentFocusCycleRoots, cycleRoot, "currentFocusCycleRoot"); |
setGlobalObject (currentFocusCycleRoots, cycleRoot, "currentFocusCycleRoot"); |
675 |
} |
} |
676 |
|
|
677 |
|
/** |
678 |
|
* Registers the supplied property change listener for receiving |
679 |
|
* events caused by the following property changes: |
680 |
|
* |
681 |
|
* <ul> |
682 |
|
* <li>the current focus owner ("focusOwner")</li> |
683 |
|
* <li>the permanent focus owner ("permanentFocusOwner")</li> |
684 |
|
* <li>the focused window ("focusedWindow")</li> |
685 |
|
* <li>the active window ("activeWindow")</li> |
686 |
|
* <li>the default focus traversal policy ("defaultFocusTraversalPolicy")</li> |
687 |
|
* <li>the default set of forward traversal keys ("forwardDefaultFocusTraversalKeys")</li> |
688 |
|
* <li>the default set of backward traversal keys ("backwardDefaultFocusTraversalKeys")</li> |
689 |
|
* <li>the default set of up cycle traversal keys ("upCycleDefaultFocusTraversalKeys")</li> |
690 |
|
* <li>the default set of down cycle traversal keys ("downCycleDefaultFocusTraversalKeys")</li> |
691 |
|
* <li>the current focus cycle root ("currentFocusCycleRoot")</li> |
692 |
|
* </ul> |
693 |
|
* |
694 |
|
* If the supplied listener is null, nothing occurs. |
695 |
|
* |
696 |
|
* @param l the new listener to register. |
697 |
|
* @see KeyboardFocusManager#addPropertyChangeListener(String, java.beans.PropertyChangeListener) |
698 |
|
*/ |
699 |
public void addPropertyChangeListener(PropertyChangeListener l) |
public void addPropertyChangeListener(PropertyChangeListener l) |
700 |
{ |
{ |
701 |
if (l != null) |
if (l != null) |
702 |
propertyChangeSupport.addPropertyChangeListener(l); |
propertyChangeSupport.addPropertyChangeListener(l); |
703 |
} |
} |
704 |
|
|
705 |
|
/** |
706 |
|
* Removes the supplied property change listener from the list |
707 |
|
* of registered listeners. If the supplied listener is null, |
708 |
|
* nothing occurs. |
709 |
|
* |
710 |
|
* @param l the listener to remove. |
711 |
|
*/ |
712 |
public void removePropertyChangeListener(PropertyChangeListener l) |
public void removePropertyChangeListener(PropertyChangeListener l) |
713 |
{ |
{ |
714 |
if (l != null) |
if (l != null) |
715 |
propertyChangeSupport.removePropertyChangeListener(l); |
propertyChangeSupport.removePropertyChangeListener(l); |
716 |
} |
} |
717 |
|
|
718 |
|
/** |
719 |
|
* Returns the currently registered property change listeners |
720 |
|
* in array form. The returned array is empty if no listeners are |
721 |
|
* currently registered. |
722 |
|
* |
723 |
|
* @return an array of registered property change listeners. |
724 |
|
*/ |
725 |
public PropertyChangeListener[] getPropertyChangeListeners() |
public PropertyChangeListener[] getPropertyChangeListeners() |
726 |
{ |
{ |
727 |
return propertyChangeSupport.getPropertyChangeListeners(); |
return propertyChangeSupport.getPropertyChangeListeners(); |
728 |
} |
} |
729 |
|
|
730 |
|
/** |
731 |
|
* Registers a property change listener for receiving events relating |
732 |
|
* to a change to a specified property. The supplied property name can be |
733 |
|
* either user-defined or one from the following list of properties |
734 |
|
* relevant to this class: |
735 |
|
* |
736 |
|
* <ul> |
737 |
|
* <li>the current focus owner ("focusOwner")</li> |
738 |
|
* <li>the permanent focus owner ("permanentFocusOwner")</li> |
739 |
|
* <li>the focused window ("focusedWindow")</li> |
740 |
|
* <li>the active window ("activeWindow")</li> |
741 |
|
* <li>the default focus traversal policy ("defaultFocusTraversalPolicy")</li> |
742 |
|
* <li>the default set of forward traversal keys ("forwardDefaultFocusTraversalKeys")</li> |
743 |
|
* <li>the default set of backward traversal keys ("backwardDefaultFocusTraversalKeys")</li> |
744 |
|
* <li>the default set of up cycle traversal keys ("upCycleDefaultFocusTraversalKeys")</li> |
745 |
|
* <li>the default set of down cycle traversal keys ("downCycleDefaultFocusTraversalKeys")</li> |
746 |
|
* <li>the current focus cycle root ("currentFocusCycleRoot")</li> |
747 |
|
* </ul> |
748 |
|
* |
749 |
|
* Nothing occurs if a null listener is supplied. null is regarded as a valid property name. |
750 |
|
* |
751 |
|
* @param name the name of the property to handle change events for. |
752 |
|
* @param l the listener to register for changes to the specified property. |
753 |
|
* @see KeyboardFocusManager#addPropertyChangeListener(java.beans.PropertyChangeListener) |
754 |
|
*/ |
755 |
public void addPropertyChangeListener(String name, PropertyChangeListener l) |
public void addPropertyChangeListener(String name, PropertyChangeListener l) |
756 |
{ |
{ |
757 |
if (l != null) |
if (l != null) |
758 |
propertyChangeSupport.addPropertyChangeListener(name, l); |
propertyChangeSupport.addPropertyChangeListener(name, l); |
759 |
} |
} |
760 |
|
|
761 |
|
/** |
762 |
|
* Removes the supplied property change listener registered for the |
763 |
|
* specified property from the list of registered listeners. If the |
764 |
|
* supplied listener is null, nothing occurs. |
765 |
|
* |
766 |
|
* @param name the name of the property the listener is |
767 |
|
* monitoring changes to. |
768 |
|
* @param l the listener to remove. |
769 |
|
*/ |
770 |
public void removePropertyChangeListener(String name, |
public void removePropertyChangeListener(String name, |
771 |
PropertyChangeListener l) |
PropertyChangeListener l) |
772 |
{ |
{ |
774 |
propertyChangeSupport.removePropertyChangeListener(name, l); |
propertyChangeSupport.removePropertyChangeListener(name, l); |
775 |
} |
} |
776 |
|
|
777 |
|
/** |
778 |
|
* Returns the currently registered property change listeners |
779 |
|
* in array form, which listen for changes to the supplied property. |
780 |
|
* The returned array is empty, if no listeners are currently registered |
781 |
|
* for events pertaining to the supplied property. |
782 |
|
* |
783 |
|
* @param name The property the returned listeners monitor for changes. |
784 |
|
* @return an array of registered property change listeners which |
785 |
|
* listen for changes to the supplied property. |
786 |
|
*/ |
787 |
public PropertyChangeListener[] getPropertyChangeListeners(String name) |
public PropertyChangeListener[] getPropertyChangeListeners(String name) |
788 |
{ |
{ |
789 |
return propertyChangeSupport.getPropertyChangeListeners(name); |
return propertyChangeSupport.getPropertyChangeListeners(name); |
790 |
} |
} |
791 |
|
|
792 |
|
/** |
793 |
|
* Fires a property change event as a response to a change to |
794 |
|
* to the specified property. The event is only fired if a |
795 |
|
* change has actually occurred (i.e. o and n are different). |
796 |
|
* |
797 |
|
* @param name The name of the property to which a change occurred. |
798 |
|
* @param o The old value of the property. |
799 |
|
* @param n The new value of the property. |
800 |
|
*/ |
801 |
protected void firePropertyChange(String name, Object o, Object n) |
protected void firePropertyChange(String name, Object o, Object n) |
802 |
{ |
{ |
803 |
propertyChangeSupport.firePropertyChange(name, o, n); |
propertyChangeSupport.firePropertyChange(name, o, n); |
804 |
} |
} |
805 |
|
|
806 |
|
/** |
807 |
|
* Registers a vetoable property change listener for receiving events |
808 |
|
* relating to the following properties: |
809 |
|
* |
810 |
|
* <ul> |
811 |
|
* <li>the current focus owner ("focusOwner")</li> |
812 |
|
* <li>the permanent focus owner ("permanentFocusOwner")</li> |
813 |
|
* <li>the focused window ("focusedWindow")</li> |
814 |
|
* <li>the active window ("activeWindow")</li> |
815 |
|
* </ul> |
816 |
|
* |
817 |
|
* Nothing occurs if a null listener is supplied. |
818 |
|
* |
819 |
|
* @param l the listener to register. |
820 |
|
* @see KeyboardFocusManager#addVetoableChangeListener(String, java.beans.VetoableChangeListener) |
821 |
|
*/ |
822 |
public void addVetoableChangeListener(VetoableChangeListener l) |
public void addVetoableChangeListener(VetoableChangeListener l) |
823 |
{ |
{ |
824 |
if (l != null) |
if (l != null) |
825 |
vetoableChangeSupport.addVetoableChangeListener(l); |
vetoableChangeSupport.addVetoableChangeListener(l); |
826 |
} |
} |
827 |
|
|
828 |
|
/** |
829 |
|
* Removes the supplied vetoable property change listener from |
830 |
|
* the list of registered listeners. If the supplied listener |
831 |
|
* is null, nothing occurs. |
832 |
|
* |
833 |
|
* @param l the listener to remove. |
834 |
|
*/ |
835 |
public void removeVetoableChangeListener(VetoableChangeListener l) |
public void removeVetoableChangeListener(VetoableChangeListener l) |
836 |
{ |
{ |
837 |
if (l != null) |
if (l != null) |
838 |
vetoableChangeSupport.removeVetoableChangeListener(l); |
vetoableChangeSupport.removeVetoableChangeListener(l); |
839 |
} |
} |
840 |
|
|
841 |
|
/** |
842 |
|
* Returns the currently registered vetoable property change listeners |
843 |
|
* in array form. The returned array is empty if no listeners are |
844 |
|
* currently registered. |
845 |
|
* |
846 |
|
* @return an array of registered vetoable property change listeners. |
847 |
|
* @since 1.4 |
848 |
|
*/ |
849 |
public VetoableChangeListener[] getVetoableChangeListeners() |
public VetoableChangeListener[] getVetoableChangeListeners() |
850 |
{ |
{ |
851 |
return vetoableChangeSupport.getVetoableChangeListeners(); |
return vetoableChangeSupport.getVetoableChangeListeners(); |
852 |
} |
} |
853 |
|
|
854 |
|
/** |
855 |
|
* Registers a vetoable property change listener for receiving events relating |
856 |
|
* to a vetoable change to a specified property. The supplied property name can be |
857 |
|
* either user-defined or one from the following list of properties |
858 |
|
* relevant to this class: |
859 |
|
* |
860 |
|
* <ul> |
861 |
|
* <li>the current focus owner ("focusOwner")</li> |
862 |
|
* <li>the permanent focus owner ("permanentFocusOwner")</li> |
863 |
|
* <li>the focused window ("focusedWindow")</li> |
864 |
|
* <li>the active window ("activeWindow")</li> |
865 |
|
* </ul> |
866 |
|
* |
867 |
|
* Nothing occurs if a null listener is supplied. null is regarded as a valid property name. |
868 |
|
* |
869 |
|
* @param name the name of the property to handle change events for. |
870 |
|
* @param l the listener to register for changes to the specified property. |
871 |
|
* @see KeyboardFocusManager#addVetoableChangeListener(java.beans.VetoableChangeListener) |
872 |
|
*/ |
873 |
public void addVetoableChangeListener(String name, VetoableChangeListener l) |
public void addVetoableChangeListener(String name, VetoableChangeListener l) |
874 |
{ |
{ |
875 |
if (l != null) |
if (l != null) |
876 |
vetoableChangeSupport.addVetoableChangeListener(name, l); |
vetoableChangeSupport.addVetoableChangeListener(name, l); |
877 |
} |
} |
878 |
|
|
879 |
|
/** |
880 |
|
* Removes the supplied vetoable property change listener registered |
881 |
|
* for the specified property from the list of registered listeners. |
882 |
|
* If the supplied listener is null, nothing occurs. |
883 |
|
* |
884 |
|
* @param name the name of the vetoable property the listener is |
885 |
|
* monitoring changes to. |
886 |
|
* @param l the listener to remove. |
887 |
|
*/ |
888 |
public void removeVetoableChangeListener(String name, |
public void removeVetoableChangeListener(String name, |
889 |
VetoableChangeListener l) |
VetoableChangeListener l) |
890 |
{ |
{ |
892 |
vetoableChangeSupport.removeVetoableChangeListener(name, l); |
vetoableChangeSupport.removeVetoableChangeListener(name, l); |
893 |
} |
} |
894 |
|
|
895 |
|
/** |
896 |
|
* Returns the currently registered vetoable property change listeners |
897 |
|
* in array form, which listen for changes to the supplied property. |
898 |
|
* The returned array is empty, if no listeners are currently registered |
899 |
|
* for events pertaining to the supplied property. |
900 |
|
* |
901 |
|
* @param name The property the returned listeners monitor for changes. |
902 |
|
* @return an array of registered property change listeners which |
903 |
|
* listen for changes to the supplied property. |
904 |
|
* @since 1.4 |
905 |
|
*/ |
906 |
public VetoableChangeListener[] getVetoableChangeListeners(String name) |
public VetoableChangeListener[] getVetoableChangeListeners(String name) |
907 |
{ |
{ |
908 |
return vetoableChangeSupport.getVetoableChangeListeners(name); |
return vetoableChangeSupport.getVetoableChangeListeners(name); |
909 |
} |
} |
910 |
|
|
911 |
|
/** |
912 |
|
* Fires a property change event as a response to a vetoable change to |
913 |
|
* to the specified property. The event is only fired if a |
914 |
|
* change has actually occurred (i.e. o and n are different). |
915 |
|
* In the event that the property change is vetoed, the following |
916 |
|
* occurs: |
917 |
|
* |
918 |
|
* <ol> |
919 |
|
* <li> |
920 |
|
* This method throws a <code>PropertyVetoException</code> to |
921 |
|
* the proposed change. |
922 |
|
* </li> |
923 |
|
* <li> |
924 |
|
* A new event is fired to reverse the previous change. |
925 |
|
* </li> |
926 |
|
* <li> |
927 |
|
* This method again throws a <code>PropertyVetoException</code> |
928 |
|
* in response to the reversion. |
929 |
|
* </li> |
930 |
|
* </ol> |
931 |
|
* |
932 |
|
* @param name The name of the property to which a change occurred. |
933 |
|
* @param o The old value of the property. |
934 |
|
* @param n The new value of the property. |
935 |
|
* @throws PropertyVetoException if one of the listeners vetos |
936 |
|
* the change by throwing this exception. |
937 |
|
*/ |
938 |
protected void fireVetoableChange(String name, Object o, Object n) |
protected void fireVetoableChange(String name, Object o, Object n) |
939 |
throws PropertyVetoException |
throws PropertyVetoException |
940 |
{ |
{ |
941 |
vetoableChangeSupport.fireVetoableChange(name, o, n); |
vetoableChangeSupport.fireVetoableChange(name, o, n); |
942 |
} |
} |
943 |
|
|
944 |
|
/** |
945 |
|
* Adds a key event dispatcher to the list of registered dispatchers. |
946 |
|
* When a key event is fired, each dispatcher's <code>dispatchKeyEvent</code> |
947 |
|
* method is called in the order that they were added, prior to the manager |
948 |
|
* dispatching the event itself. Notifications halt when one of the |
949 |
|
* dispatchers returns true. |
950 |
|
* <br /> |
951 |
|
* <br /> |
952 |
|
* The same dispatcher can exist multiple times within the list |
953 |
|
* of registered dispatchers, and there is no limit on the length |
954 |
|
* of this list. A null dispatcher is simply ignored. |
955 |
|
* |
956 |
|
* @param dispatcher The dispatcher to register. |
957 |
|
*/ |
958 |
public void addKeyEventDispatcher(KeyEventDispatcher dispatcher) |
public void addKeyEventDispatcher(KeyEventDispatcher dispatcher) |
959 |
{ |
{ |
960 |
if (dispatcher != null) |
if (dispatcher != null) |
961 |
keyEventDispatchers.add(dispatcher); |
keyEventDispatchers.add(dispatcher); |
962 |
} |
} |
963 |
|
|
964 |
|
/** |
965 |
|
* Removes the specified key event dispatcher from the list of |
966 |
|
* registered dispatchers. The manager always dispatches events, |
967 |
|
* regardless of its existence within the list. The manager |
968 |
|
* can be added and removed from the list, as with any other |
969 |
|
* dispatcher, but this does not affect its ability to dispatch |
970 |
|
* key events. Non-existent and null dispatchers are simply ignored |
971 |
|
* by this method. |
972 |
|
* |
973 |
|
* @param dispatcher The dispatcher to remove. |
974 |
|
*/ |
975 |
public void removeKeyEventDispatcher(KeyEventDispatcher dispatcher) |
public void removeKeyEventDispatcher(KeyEventDispatcher dispatcher) |
976 |
{ |
{ |
977 |
keyEventDispatchers.remove(dispatcher); |
keyEventDispatchers.remove(dispatcher); |
978 |
} |
} |
979 |
|
|
980 |
|
/** |
981 |
|
* Returns the currently registered key event dispatchers in <code>List</code> |
982 |
|
* form. At present, this only includes dispatchers explicitly registered |
983 |
|
* via the <code>addKeyEventDispatcher()</code> method, but this behaviour |
984 |
|
* is subject to change and should not be depended on. The manager itself |
985 |
|
* may be a member of the list, but only if explicitly registered. If no |
986 |
|
* dispatchers have been registered, the list will be empty. |
987 |
|
* |
988 |
|
* @return A list of explicitly registered key event dispatchers. |
989 |
|
* @see KeyboardFocusManager#addKeyEventDispatcher(java.awt.KeyEventDispatcher) |
990 |
|
*/ |
991 |
protected List getKeyEventDispatchers () |
protected List getKeyEventDispatchers () |
992 |
{ |
{ |
993 |
return (List) keyEventDispatchers.clone (); |
return (List) keyEventDispatchers.clone (); |
994 |
} |
} |
995 |
|
|
996 |
|
/** |
997 |
|
* Adds a key event post processor to the list of registered post processors. |
998 |
|
* Post processors work in the same way as key event dispatchers, except |
999 |
|
* that they are invoked after the manager has dispatched the key event, |
1000 |
|
* and not prior to this. Each post processor's <code>postProcessKeyEvent</code> |
1001 |
|
* method is called to see if any post processing needs to be performed. THe |
1002 |
|
* processors are called in the order in which they were added to the list, |
1003 |
|
* and notifications continue until one returns true. As with key event |
1004 |
|
* dispatchers, the manager is implicitly called following this process, |
1005 |
|
* regardless of whether or not it is present within the list. |
1006 |
|
* <br /> |
1007 |
|
* <br /> |
1008 |
|
* The same post processor can exist multiple times within the list |
1009 |
|
* of registered post processors, and there is no limit on the length |
1010 |
|
* of this list. A null post processor is simply ignored. |
1011 |
|
* |
1012 |
|
* @param postProcessor the post processor to register. |
1013 |
|
* @see KeyboardFocusManager#addKeyEventDispatcher(java.awt.KeyEventDispatcher) |
1014 |
|
*/ |
1015 |
public void addKeyEventPostProcessor (KeyEventPostProcessor postProcessor) |
public void addKeyEventPostProcessor (KeyEventPostProcessor postProcessor) |
1016 |
{ |
{ |
1017 |
if (postProcessor != null) |
if (postProcessor != null) |
1018 |
keyEventPostProcessors.add (postProcessor); |
keyEventPostProcessors.add (postProcessor); |
1019 |
} |
} |
1020 |
|
|
1021 |
|
/** |
1022 |
|
* Removes the specified key event post processor from the list of |
1023 |
|
* registered post processors. The manager always post processes events, |
1024 |
|
* regardless of its existence within the list. The manager |
1025 |
|
* can be added and removed from the list, as with any other |
1026 |
|
* post processor, but this does not affect its ability to post process |
1027 |
|
* key events. Non-existent and null post processors are simply ignored |
1028 |
|
* by this method. |
1029 |
|
* |
1030 |
|
* @param postProcessor the post processor to remove. |
1031 |
|
*/ |
1032 |
public void removeKeyEventPostProcessor (KeyEventPostProcessor postProcessor) |
public void removeKeyEventPostProcessor (KeyEventPostProcessor postProcessor) |
1033 |
{ |
{ |
1034 |
keyEventPostProcessors.remove (postProcessor); |
keyEventPostProcessors.remove (postProcessor); |
1035 |
} |
} |
1036 |
|
|
1037 |
|
/** |
1038 |
|
* Returns the currently registered key event post processors in <code>List</code> |
1039 |
|
* form. At present, this only includes post processors explicitly registered |
1040 |
|
* via the <code>addKeyEventPostProcessor()</code> method, but this behaviour |
1041 |
|
* is subject to change and should not be depended on. The manager itself |
1042 |
|
* may be a member of the list, but only if explicitly registered. If no |
1043 |
|
* post processors have been registered, the list will be empty. |
1044 |
|
* |
1045 |
|
* @return A list of explicitly registered key event post processors. |
1046 |
|
* @see KeyboardFocusManager#addKeyEventPostProcessor(java.awt.KeyEventPostProcessor) |
1047 |
|
*/ |
1048 |
protected List getKeyEventPostProcessors () |
protected List getKeyEventPostProcessors () |
1049 |
{ |
{ |
1050 |
return (List) keyEventPostProcessors.clone (); |
return (List) keyEventPostProcessors.clone (); |
1051 |
} |
} |
1052 |
|
|
1053 |
|
/** |
1054 |
|
* The AWT event dispatcher uses this method to request that the manager |
1055 |
|
* handle a particular event. If the manager fails or refuses to |
1056 |
|
* dispatch the supplied event (this method returns false), the |
1057 |
|
* AWT event dispatcher will try to dispatch the event itself. |
1058 |
|
* <br /> |
1059 |
|
* <br /> |
1060 |
|
* The manager is expected to handle all <code>FocusEvent</code>s |
1061 |
|
* and <code>KeyEvent</code>s, and <code>WindowEvent</code>s |
1062 |
|
* relating to the focus. Dispatch is done with regard to the |
1063 |
|
* the focus owner and the currently focused and active windows. |
1064 |
|
* In handling the event, the source of the event may be overridden. |
1065 |
|
* <br /> |
1066 |
|
* <br /> |
1067 |
|
* The actual dispatching is performed by calling |
1068 |
|
* <code>redispatchEvent()</code>. This avoids the infinite recursion |
1069 |
|
* of dispatch requests which may occur if this method is called on |
1070 |
|
* the target component. |
1071 |
|
* |
1072 |
|
* @param e the event to dispatch. |
1073 |
|
* @return true if the event was dispatched. |
1074 |
|
* @see KeyboardFocusManager#redispatchEvent(java.awt.Component, java.awt.AWTEvent) |
1075 |
|
* @see KeyEvent |
1076 |
|
* @see FocusEvent |
1077 |
|
* @see WindowEvent |
1078 |
|
*/ |
1079 |
public abstract boolean dispatchEvent (AWTEvent e); |
public abstract boolean dispatchEvent (AWTEvent e); |
1080 |
|
|
1081 |
|
/** |
1082 |
|
* Handles redispatching of an event so that recursion of |
1083 |
|
* dispatch requests does not occur. Event dispatch methods |
1084 |
|
* within this manager (<code>dispatchEvent()</code>) and |
1085 |
|
* the key event dispatchers should use this method to handle |
1086 |
|
* dispatching rather than the dispatch method of the target |
1087 |
|
* component. |
1088 |
|
* <br /> |
1089 |
|
* <br /> |
1090 |
|
* <strong> |
1091 |
|
* This method is not intended for general consumption, and is |
1092 |
|
* only for the use of the aforementioned classes. |
1093 |
|
* </strong> |
1094 |
|
* |
1095 |
|
* @param target the target component to which the event is |
1096 |
|
* dispatched. |
1097 |
|
* @param e the event to dispatch. |
1098 |
|
*/ |
1099 |
public final void redispatchEvent (Component target, AWTEvent e) |
public final void redispatchEvent (Component target, AWTEvent e) |
1100 |
{ |
{ |
1101 |
e.setSource (target); |
e.setSource (target); |
1102 |
dispatchEvent (e); |
dispatchEvent (e); |
1103 |
} |
} |
1104 |
|
|
1105 |
|
/** |
1106 |
|
* Attempts to dispatch key events for which no key event dispatcher |
1107 |
|
* has so far succeeded. This method is usually called by |
1108 |
|
* <code>dispatchEvent()</code> following the sending of the key |
1109 |
|
* event to any registered key event dispatchers. If the key |
1110 |
|
* event reaches this stage, none of the dispatchers returned |
1111 |
|
* true. This is, of course, always the case if there are no |
1112 |
|
* registered dispatchers. |
1113 |
|
* <br /> |
1114 |
|
* <br /> |
1115 |
|
* If this method also fails to handle the key event, then |
1116 |
|
* false is returned to the caller. In the case of |
1117 |
|
* <code>dispatchEvent()</code>, the calling method may try |
1118 |
|
* to handle the event itself or simply forward on the |
1119 |
|
* false result to its caller. When the event is dispatched |
1120 |
|
* by this method, a true result is propogated through the |
1121 |
|
* calling methods. |
1122 |
|
* |
1123 |
|
* @param e the key event to dispatch. |
1124 |
|
* @return true if the event was dispatched successfully. |
1125 |
|
*/ |
1126 |
public abstract boolean dispatchKeyEvent (KeyEvent e); |
public abstract boolean dispatchKeyEvent (KeyEvent e); |
1127 |
|
|
1128 |
|
/** |
1129 |
|
* Handles the post processing of key events. By default, |
1130 |
|
* this method will map unhandled key events to appropriate |
1131 |
|
* <code>MenuShortcut</code>s. The event is consumed |
1132 |
|
* in the process and the shortcut is activated. This |
1133 |
|
* method is usually called by <code>dispatchKeyEvent</code>. |
1134 |
|
* |
1135 |
|
* @param e the key event to post process. |
1136 |
|
* @return true by default, as the event was handled. |
1137 |
|
*/ |
1138 |
public abstract boolean postProcessKeyEvent (KeyEvent e); |
public abstract boolean postProcessKeyEvent (KeyEvent e); |
1139 |
|
|
1140 |
|
/** |
1141 |
|
* Handles focus traversal operations for key events which |
1142 |
|
* represent focus traversal keys in relation to the supplied |
1143 |
|
* component. The supplied component is assumed to have the |
1144 |
|
* focus, whether it does so or not, and the operation is |
1145 |
|
* carried out as appropriate, with this in mind. |
1146 |
|
* |
1147 |
|
* @param focused the component on which to perform focus traversal, |
1148 |
|
* on the assumption that this component has the focus. |
1149 |
|
* @param e the possible focus traversal key event. |
1150 |
|
*/ |
1151 |
public abstract void processKeyEvent (Component focused, KeyEvent e); |
public abstract void processKeyEvent (Component focused, KeyEvent e); |
1152 |
|
|
1153 |
|
/** |
1154 |
|
* Delays all key events following the specified timestamp until the |
1155 |
|
* supplied component has focus. The AWT calls this method when it is |
1156 |
|
* determined that a focus change may occur within the native windowing |
1157 |
|
* system. Any key events which occur following the time specified by |
1158 |
|
* after are delayed until a <code>FOCUS_GAINED</code> event is received |
1159 |
|
* for the untilFocused component. The manager is responsible for ensuring |
1160 |
|
* this takes place. |
1161 |
|
* |
1162 |
|
* @param after the timestamp beyond which all key events are delayed until |
1163 |
|
* the supplied component gains focus. |
1164 |
|
* @param untilFocused the component to wait on gaining focus. |
1165 |
|
*/ |
1166 |
protected abstract void enqueueKeyEvents (long after, Component untilFocused); |
protected abstract void enqueueKeyEvents (long after, Component untilFocused); |
1167 |
|
|
1168 |
|
/** |
1169 |
|
* Removes the key event block specified by the supplied timestamp and component. |
1170 |
|
* All delayed key events are released for normal dispatching following its |
1171 |
|
* removal and subsequent key events that would have been blocked are now |
1172 |
|
* immediately dispatched. If the specified timestamp is below 0, then |
1173 |
|
* the request with the oldest timestamp is removed. |
1174 |
|
* |
1175 |
|
* @param after the timestamp of the key event block to be removed, or a |
1176 |
|
* value smaller than 0 if the oldest is to be removed. |
1177 |
|
* @param untilFocused the component of the key event block to be removed. |
1178 |
|
*/ |
1179 |
protected abstract void dequeueKeyEvents (long after, Component untilFocused); |
protected abstract void dequeueKeyEvents (long after, Component untilFocused); |
1180 |
|
|
1181 |
|
/** |
1182 |
|
* Discards all key event blocks relating to focus requirements for |
1183 |
|
* the supplied component, regardless of timestamp. |
1184 |
|
* |
1185 |
|
* @param comp the component of the key event block(s) to be removed. |
1186 |
|
*/ |
1187 |
protected abstract void discardKeyEvents (Component comp); |
protected abstract void discardKeyEvents (Component comp); |
1188 |
|
|
1189 |
public abstract void focusNextComponent (Component comp); |
/** |
1190 |
|
* Moves the current focus to the next component following |
1191 |
public abstract void focusPreviousComponent (Component comp); |
* comp, based on the current focus traversal policy. By |
1192 |
|
* default, only visible, displayable, accepted components |
1193 |
public abstract void upFocusCycle (Component comp); |
* can receive focus. <code>Canvas</code>es, <code>Panel</code>s, |
1194 |
|
* <code>Label</code>s, <code>ScrollPane</code>s, <code>Scrollbar</code>s, |
1195 |
public abstract void downFocusCycle (Container cont); |
* <code>Window</code>s and lightweight components are judged |
1196 |
|
* to be unacceptable by default. See the |
1197 |
|
* <code>DefaultFocusTraversalPolicy</code> for more details. |
1198 |
|
* |
1199 |
|
* @param comp the component prior to the one which will |
1200 |
|
* become the focus, following execution of this method. |
1201 |
|
* @see DefaultFocusTraversalPolicy |
1202 |
|
*/ |
1203 |
|
public abstract void focusNextComponent(Component comp); |
1204 |
|
|
1205 |
|
/** |
1206 |
|
* Moves the current focus to the previous component, prior to |
1207 |
|
* comp, based on the current focus traversal policy. By |
1208 |
|
* default, only visible, displayable, accepted components |
1209 |
|
* can receive focus. <code>Canvas</code>es, <code>Panel</code>s, |
1210 |
|
* <code>Label</code>s, <code>ScrollPane</code>s, <code>Scrollbar</code>s, |
1211 |
|
* <code>Window</code>s and lightweight components are judged |
1212 |
|
* to be unacceptable by default. See the |
1213 |
|
* <code>DefaultFocusTraversalPolicy</code> for more details. |
1214 |
|
* |
1215 |
|
* @param comp the component following the one which will |
1216 |
|
* become the focus, following execution of this method. |
1217 |
|
* @see DefaultFocusTraversalPolicy |
1218 |
|
*/ |
1219 |
|
public abstract void focusPreviousComponent(Component comp); |
1220 |
|
|
1221 |
|
/** |
1222 |
|
* Moves the current focus upwards by one focus cycle. |
1223 |
|
* Both the current focus owner and current focus cycle root |
1224 |
|
* become the focus cycle root of the supplied component. |
1225 |
|
* However, in the case of a <code>Window</code>, the default |
1226 |
|
* focus component becomes the focus owner and the focus cycle |
1227 |
|
* root is not changed. |
1228 |
|
* |
1229 |
|
* @param comp the component used as part of the focus traversal. |
1230 |
|
*/ |
1231 |
|
public abstract void upFocusCycle(Component comp); |
1232 |
|
|
1233 |
public final void focusNextComponent () |
/** |
1234 |
|
* Moves the current focus downwards by one focus cycle. |
1235 |
|
* If the supplied container is a focus cycle root, then this |
1236 |
|
* becomes the current focus cycle root and the focus goes |
1237 |
|
* to the default component of the specified container. |
1238 |
|
* Nothing happens for non-focus cycle root containers. |
1239 |
|
* |
1240 |
|
* @param comp the component used as part of the focus traversal. |
1241 |
|
*/ |
1242 |
|
public abstract void downFocusCycle(Container cont); |
1243 |
|
|
1244 |
|
/** |
1245 |
|
* Moves the current focus to the next component, based on the |
1246 |
|
* current focus traversal policy. By default, only visible, |
1247 |
|
* displayable, accepted component can receive focus. |
1248 |
|
* <code>Canvas</code>es, <code>Panel</code>s, |
1249 |
|
* <code>Label</code>s, <code>ScrollPane</code>s, <code>Scrollbar</code>s, |
1250 |
|
* <code>Window</code>s and lightweight components are judged |
1251 |
|
* to be unacceptable by default. See the |
1252 |
|
* <code>DefaultFocusTraversalPolicy</code> for more details. |
1253 |
|
* |
1254 |
|
* @see DefaultFocusTraversalPolicy |
1255 |
|
*/ |
1256 |
|
public final void focusNextComponent() |
1257 |
{ |
{ |
1258 |
focusNextComponent (null); |
focusNextComponent (null); |
1259 |
} |
} |
1260 |
|
|
1261 |
public final void focusPreviousComponent () |
/** |
1262 |
|
* Moves the current focus to the previous component, based on the |
1263 |
|
* current focus traversal policy. By default, only visible, |
1264 |
|
* displayable, accepted component can receive focus. |
1265 |
|
* <code>Canvas</code>es, <code>Panel</code>s, |
1266 |
|
* <code>Label</code>s, <code>ScrollPane</code>s, <code>Scrollbar</code>s, |
1267 |
|
* <code>Window</code>s and lightweight components are judged |
1268 |
|
* to be unacceptable by default. See the |
1269 |
|
* <code>DefaultFocusTraversalPolicy</code> for more details. |
1270 |
|
* |
1271 |
|
* @see DefaultFocusTraversalPolicy |
1272 |
|
*/ |
1273 |
|
public final void focusPreviousComponent() |
1274 |
{ |
{ |
1275 |
focusPreviousComponent (null); |
focusPreviousComponent (null); |
1276 |
} |
} |
1277 |
|
|
1278 |
public final void upFocusCycle () |
/** |
1279 |
|
* Moves the current focus upwards by one focus cycle, |
1280 |
|
* so that the new focus owner is the focus cycle root |
1281 |
|
* of the current owner. The current focus cycle root then |
1282 |
|
* becomes the focus cycle root of the new focus owner. |
1283 |
|
* However, in the case of the focus cycle root of the |
1284 |
|
* current focus owner being a <code>Window</code>, the default |
1285 |
|
* component of this window becomes the focus owner and the |
1286 |
|
* focus cycle root is not changed. |
1287 |
|
*/ |
1288 |
|
public final void upFocusCycle() |
1289 |
{ |
{ |
1290 |
upFocusCycle (null); |
upFocusCycle (null); |
1291 |
} |
} |
1292 |
|
|
1293 |
public final void downFocusCycle () |
/** |
1294 |
|
* Moves the current focus downwards by one focus cycle, |
1295 |
|
* iff the current focus cycle root is a <code>Container</code>. |
1296 |
|
* Usually, the new focus owner is set to the default component |
1297 |
|
* of the container and the current focus cycle root is set |
1298 |
|
* to the current focus owner. Nothing occurs if the current |
1299 |
|
* focus cycle root is not a container. |
1300 |
|
*/ |
1301 |
|
public final void downFocusCycle() |
1302 |
{ |
{ |
1303 |
Component focusOwner = getGlobalFocusOwner (); |
Component focusOwner = getGlobalFocusOwner (); |
1304 |
if (focusOwner instanceof Container |
if (focusOwner instanceof Container |