/[classpath]/classpath/java/awt/KeyboardFocusManager.java
ViewVC logotype

Diff of /classpath/java/awt/KeyboardFocusManager.java

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.5 by mark, Thu Jul 22 19:45:38 2004 UTC revision 1.6 by gnu_andrew, Tue Aug 24 18:38:01 2004 UTC
# Line 55  import java.util.List; Line 55  import java.util.List;
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
# Line 182  public abstract class KeyboardFocusManag Line 226  public abstract class KeyboardFocusManag
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
# Line 623  public abstract class KeyboardFocusManag Line 674  public abstract class KeyboardFocusManag
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    {    {
# Line 653  public abstract class KeyboardFocusManag Line 774  public abstract class KeyboardFocusManag
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    {    {
# Line 693  public abstract class KeyboardFocusManag Line 892  public abstract class KeyboardFocusManag
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

Legend:
Removed from v.1.5  
changed lines
  Added in v.1.6

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26