Index: ChangeLog =================================================================== RCS file: /cvsroot/classpath/classpath/ChangeLog,v retrieving revision 1.2429 diff -u -3 -p -u -r1.2429 ChangeLog --- ChangeLog 19 Aug 2004 05:57:11 -0000 1.2429 +++ ChangeLog 21 Aug 2004 01:31:28 -0000 @@ -1,3 +1,8 @@ +2004-08-20 Andrew John Hughes
+ + * java/awt/KeyboardFocusManager.java + Added missing documentation. + 2004-08-18 Casey Marshall * lib/Makefile.am (dist-hook): add `org' to remove commands, too. Index: java/awt/KeyboardFocusManager.java =================================================================== RCS file: /cvsroot/classpath/classpath/java/awt/KeyboardFocusManager.java,v retrieving revision 1.5 diff -u -3 -p -u -r1.5 KeyboardFocusManager.java --- java/awt/KeyboardFocusManager.java 22 Jul 2004 19:45:38 -0000 1.5 +++ java/awt/KeyboardFocusManager.java 21 Aug 2004 01:31:30 -0000 @@ -55,20 +55,64 @@ import java.util.List; import java.util.Map; import java.util.Set; -// FIXME: finish documentation - /** - * - * FIXME: discuss applet contexts and thread groups and codebases - * being insulated. - * - * FIXME: discuss where default focus traversal key sets apply - * (inherited by child Components etc.) + * TheKeyboardFocusManager
handles the focusing of
+ * windows for receiving keyboard events. The manager handles
+ * the dispatch of all FocusEvent
s and
+ * KeyEvent
s, along with WindowEvent
s
+ * relating to the focused window. Users can use the manager
+ * to ascertain the current focus owner and fire events.
+ * Component
that receives
+ * key events. The focus owner is either the currently focused
+ * window or a component within this window.
+ * Frame
+ * or Dialog
, and is either the currently focused
+ * window or its owner.
+ * KeyboardFocusManager
, as opposed to the global
+ * manager maintained by applets which share the same context.
+ * Each context is insulated from the others, and they don't interact.
+ * The resulting behaviour, as with context division, depends on the browser
+ * supporting the applets. Regardless, there can only ever be
+ * one focused window, one active window and one focus owner
+ * per ClassLoader
.
+ * ThreadGroup
to which it pertains. With respect to
+ * applets, each code base has its own ThreadGroup
, so the
+ * isolation of each context is enforced within the manager.
+ * KEY_PRESSED
event.
+ * However, all other key events related to the use of the
+ * defined focus traversal key sequence are consumed and not
+ * dispatched.
+ * PropertyVetoException
to
+ * the proposed change.
+ * PropertyVetoException
+ * in response to the reversion.
+ * dispatchKeyEvent
+ * method is called in the order that they were added, prior to the manager
+ * dispatching the event itself. Notifications halt when one of the
+ * dispatchers returns true.
+ * List
+ * form. At present, this only includes dispatchers explicitly registered
+ * via the addKeyEventDispatcher()
method, but this behaviour
+ * is subject to change and should not be depended on. The manager itself
+ * may be a member of the list, but only if explicitly registered. If no
+ * dispatchers have been registered, the list will be empty.
+ *
+ * @return A list of explicitly registered key event dispatchers.
+ * @see KeyboardFocusManager#addKeyEventDispatcher(java.awt.KeyEventDispatcher)
+ */
protected List getKeyEventDispatchers ()
{
return (List) keyEventDispatchers.clone ();
}
+ /**
+ * Adds a key event post processor to the list of registered post processors.
+ * Post processors work in the same way as key event dispatchers, except
+ * that they are invoked after the manager has dispatched the key event,
+ * and not prior to this. Each post processor's postProcessKeyEvent
+ * method is called to see if any post processing needs to be performed. THe
+ * processors are called in the order in which they were added to the list,
+ * and notifications continue until one returns true. As with key event
+ * dispatchers, the manager is implicitly called following this process,
+ * regardless of whether or not it is present within the list.
+ * List
+ * form. At present, this only includes post processors explicitly registered
+ * via the addKeyEventPostProcessor()
method, but this behaviour
+ * is subject to change and should not be depended on. The manager itself
+ * may be a member of the list, but only if explicitly registered. If no
+ * post processors have been registered, the list will be empty.
+ *
+ * @return A list of explicitly registered key event post processors.
+ * @see KeyboardFocusManager#addKeyEventPostProcessor(java.awt.KeyEventPostProcessor)
+ */
protected List getKeyEventPostProcessors ()
{
return (List) keyEventPostProcessors.clone ();
}
+ /**
+ * The AWT event dispatcher uses this method to request that the manager
+ * handle a particular event. If the manager fails or refuses to
+ * dispatch the supplied event (this method returns false), the
+ * AWT event dispatcher will try to dispatch the event itself.
+ * FocusEvent
s
+ * and KeyEvent
s, and WindowEvent
s
+ * relating to the focus. Dispatch is done with regard to the
+ * the focus owner and the currently focused and active windows.
+ * In handling the event, the source of the event may be overridden.
+ * redispatchEvent()
. This avoids the infinite recursion
+ * of dispatch requests which may occur if this method is called on
+ * the target component.
+ *
+ * @param e the event to dispatch.
+ * @return true if the event was dispatched.
+ * @see KeyboardFocusManager#redispatchEvent(java.awt.Component, java.awt.AWTEvent)
+ * @see KeyEvent
+ * @see FocusEvent
+ * @see WindowEvent
+ */
public abstract boolean dispatchEvent (AWTEvent e);
+ /**
+ * Handles redispatching of an event so that recursion of
+ * dispatch requests does not occur. Event dispatch methods
+ * within this manager (dispatchEvent()
) and
+ * the key event dispatchers should use this method to handle
+ * dispatching rather than the dispatch method of the target
+ * component.
+ * dispatchEvent()
following the sending of the key
+ * event to any registered key event dispatchers. If the key
+ * event reaches this stage, none of the dispatchers returned
+ * true. This is, of course, always the case if there are no
+ * registered dispatchers.
+ * dispatchEvent()
, the calling method may try
+ * to handle the event itself or simply forward on the
+ * false result to its caller. When the event is dispatched
+ * by this method, a true result is propogated through the
+ * calling methods.
+ *
+ * @param e the key event to dispatch.
+ * @return true if the event was dispatched successfully.
+ */
public abstract boolean dispatchKeyEvent (KeyEvent e);
+ /**
+ * Handles the post processing of key events. By default,
+ * this method will map unhandled key events to appropriate
+ * MenuShortcut
s. The event is consumed
+ * in the process and the shortcut is activated. This
+ * method is usually called by dispatchKeyEvent
.
+ *
+ * @param e the key event to post process.
+ * @return true by default, as the event was handled.
+ */
public abstract boolean postProcessKeyEvent (KeyEvent e);
+ /**
+ * Handles focus traversal operations for key events which
+ * represent focus traversal keys in relation to the supplied
+ * component. The supplied component is assumed to have the
+ * focus, whether it does so or not, and the operation is
+ * carried out as appropriate, with this in mind.
+ *
+ * @param focused the component on which to perform focus traversal,
+ * on the assumption that this component has the focus.
+ * @param e the possible focus traversal key event.
+ */
public abstract void processKeyEvent (Component focused, KeyEvent e);
+ /**
+ * Delays all key events following the specified timestamp until the
+ * supplied component has focus. The AWT calls this method when it is
+ * determined that a focus change may occur within the native windowing
+ * system. Any key events which occur following the time specified by
+ * after are delayed until a FOCUS_GAINED
event is received
+ * for the untilFocused component. The manager is responsible for ensuring
+ * this takes place.
+ *
+ * @param after the timestamp beyond which all key events are delayed until
+ * the supplied component gains focus.
+ * @param untilFocused the component to wait on gaining focus.
+ */
protected abstract void enqueueKeyEvents (long after, Component untilFocused);
+ /**
+ * Removes the key event block specified by the supplied timestamp and component.
+ * All delayed key events are released for normal dispatching following its
+ * removal and subsequent key events that would have been blocked are now
+ * immediately dispatched. If the specified timestamp is below 0, then
+ * the request with the oldest timestamp is removed.
+ *
+ * @param after the timestamp of the key event block to be removed, or a
+ * value smaller than 0 if the oldest is to be removed.
+ * @param untilFocused the component of the key event block to be removed.
+ */
protected abstract void dequeueKeyEvents (long after, Component untilFocused);
+ /**
+ * Discards all key event blocks relating to focus requirements for
+ * the supplied component, regardless of timestamp.
+ *
+ * @param comp the component of the key event block(s) to be removed.
+ */
protected abstract void discardKeyEvents (Component comp);
- public abstract void focusNextComponent (Component comp);
-
- public abstract void focusPreviousComponent (Component comp);
-
- public abstract void upFocusCycle (Component comp);
-
- public abstract void downFocusCycle (Container cont);
+ /**
+ * Moves the current focus to the next component following
+ * comp, based on the current focus traversal policy. By
+ * default, only visible, displayable, accepted components
+ * can receive focus. Canvas
es, Panel
s,
+ * Label
s, ScrollPane
s, Scrollbar
s,
+ * Window
s and lightweight components are judged
+ * to be unacceptable by default. See the
+ * DefaultFocusTraversalPolicy
for more details.
+ *
+ * @param comp the component prior to the one which will
+ * become the focus, following execution of this method.
+ * @see DefaultFocusTraversalPolicy
+ */
+ public abstract void focusNextComponent(Component comp);
+
+ /**
+ * Moves the current focus to the previous component, prior to
+ * comp, based on the current focus traversal policy. By
+ * default, only visible, displayable, accepted components
+ * can receive focus. Canvas
es, Panel
s,
+ * Label
s, ScrollPane
s, Scrollbar
s,
+ * Window
s and lightweight components are judged
+ * to be unacceptable by default. See the
+ * DefaultFocusTraversalPolicy
for more details.
+ *
+ * @param comp the component following the one which will
+ * become the focus, following execution of this method.
+ * @see DefaultFocusTraversalPolicy
+ */
+ public abstract void focusPreviousComponent(Component comp);
+
+ /**
+ * Moves the current focus upwards by one focus cycle.
+ * Both the current focus owner and current focus cycle root
+ * become the focus cycle root of the supplied component.
+ * However, in the case of a Window
, the default
+ * focus component becomes the focus owner and the focus cycle
+ * root is not changed.
+ *
+ * @param comp the component used as part of the focus traversal.
+ */
+ public abstract void upFocusCycle(Component comp);
- public final void focusNextComponent ()
+ /**
+ * Moves the current focus downwards by one focus cycle.
+ * If the supplied container is a focus cycle root, then this
+ * becomes the current focus cycle root and the focus goes
+ * to the default component of the specified container.
+ * Nothing happens for non-focus cycle root containers.
+ *
+ * @param comp the component used as part of the focus traversal.
+ */
+ public abstract void downFocusCycle(Container cont);
+
+ /**
+ * Moves the current focus to the next component, based on the
+ * current focus traversal policy. By default, only visible,
+ * displayable, accepted component can receive focus.
+ * Canvas
es, Panel
s,
+ * Label
s, ScrollPane
s, Scrollbar
s,
+ * Window
s and lightweight components are judged
+ * to be unacceptable by default. See the
+ * DefaultFocusTraversalPolicy
for more details.
+ *
+ * @see DefaultFocusTraversalPolicy
+ */
+ public final void focusNextComponent()
{
focusNextComponent (null);
}
- public final void focusPreviousComponent ()
+ /**
+ * Moves the current focus to the previous component, based on the
+ * current focus traversal policy. By default, only visible,
+ * displayable, accepted component can receive focus.
+ * Canvas
es, Panel
s,
+ * Label
s, ScrollPane
s, Scrollbar
s,
+ * Window
s and lightweight components are judged
+ * to be unacceptable by default. See the
+ * DefaultFocusTraversalPolicy
for more details.
+ *
+ * @see DefaultFocusTraversalPolicy
+ */
+ public final void focusPreviousComponent()
{
focusPreviousComponent (null);
}
- public final void upFocusCycle ()
+ /**
+ * Moves the current focus upwards by one focus cycle,
+ * so that the new focus owner is the focus cycle root
+ * of the current owner. The current focus cycle root then
+ * becomes the focus cycle root of the new focus owner.
+ * However, in the case of the focus cycle root of the
+ * current focus owner being a Window
, the default
+ * component of this window becomes the focus owner and the
+ * focus cycle root is not changed.
+ */
+ public final void upFocusCycle()
{
upFocusCycle (null);
}
- public final void downFocusCycle ()
+ /**
+ * Moves the current focus downwards by one focus cycle,
+ * iff the current focus cycle root is a Container
.
+ * Usually, the new focus owner is set to the default component
+ * of the container and the current focus cycle root is set
+ * to the current focus owner. Nothing occurs if the current
+ * focus cycle root is not a container.
+ */
+ public final void downFocusCycle()
{
Component focusOwner = getGlobalFocusOwner ();
if (focusOwner instanceof Container