PatchSet 5104 Date: 2004/08/25 22:06:00 Author: dalibor Branch: HEAD Tag: (none) Log: Resynced with GNU Classpath: AWT accessibility and documentation improvements
2004-08-25 Dalibor Topic <[EMAIL PROTECTED]> * libraries/javalib/java/awt/Label.java, libraries/javalib/java/awt/Canvas.java, libraries/javalib/java/awt/KeyboardFocusManager.java: Resynced with GNU Classpath. 2004-08-24 Andrew John Hughes <[EMAIL PROTECTED]> * java/awt/Label.java, java/awt/Canvas.java Added accessibility classes to AWT Label and Canvas, as well as additional documentation for Canvas. 2004-08-24 Andrew John Hughes <[EMAIL PROTECTED]> * java/awt/KeyboardFocusManager.java Added missing documentation. Members: ChangeLog:1.2660->1.2661 libraries/javalib/java/awt/Canvas.java:1.12->1.13 libraries/javalib/java/awt/KeyboardFocusManager.java:1.2->1.3 libraries/javalib/java/awt/Label.java:1.2->1.3 Index: kaffe/ChangeLog diff -u kaffe/ChangeLog:1.2660 kaffe/ChangeLog:1.2661 --- kaffe/ChangeLog:1.2660 Wed Aug 25 21:54:15 2004 +++ kaffe/ChangeLog Wed Aug 25 22:06:00 2004 @@ -1,5 +1,23 @@ 2004-08-25 Dalibor Topic <[EMAIL PROTECTED]> + * libraries/javalib/java/awt/Label.java, + libraries/javalib/java/awt/Canvas.java, + libraries/javalib/java/awt/KeyboardFocusManager.java: + Resynced with GNU Classpath. + + 2004-08-24 Andrew John Hughes <[EMAIL PROTECTED]> + + * java/awt/Label.java, java/awt/Canvas.java + Added accessibility classes to AWT Label and Canvas, + as well as additional documentation for Canvas. + + 2004-08-24 Andrew John Hughes <[EMAIL PROTECTED]> + + * java/awt/KeyboardFocusManager.java + Added missing documentation. + +2004-08-25 Dalibor Topic <[EMAIL PROTECTED]> + * libraries/javalib/java/security/cert/X509CRLSelector.java: Resynced with GNU Classpath. Index: kaffe/libraries/javalib/java/awt/Canvas.java diff -u kaffe/libraries/javalib/java/awt/Canvas.java:1.12 kaffe/libraries/javalib/java/awt/Canvas.java:1.13 --- kaffe/libraries/javalib/java/awt/Canvas.java:1.12 Thu Jul 22 19:20:21 2004 +++ kaffe/libraries/javalib/java/awt/Canvas.java Wed Aug 25 22:06:02 2004 @@ -37,17 +37,60 @@ package java.awt; +import java.awt.image.BufferStrategy; import java.awt.peer.ComponentPeer; - -public class Canvas extends Component implements java.io.Serializable +import java.io.Serializable; +import javax.accessibility.Accessible; +import javax.accessibility.AccessibleContext; +import javax.accessibility.AccessibleRole; + +/** + * The <code>Canvas</code> component provides a blank rectangular + * area, which the client application can use for drawing and for + * capturing events. By overriding the <code>paint()</code> method, + * the canvas can be used for anything from simple line drawings to + * full-scale custom components. + * + * @author Original author unknown + * @author Tom Tromey <[EMAIL PROTECTED]> + * @author Andrew John Hughes <[EMAIL PROTECTED]> + * @since 1.0 + */ + +public class Canvas + extends Component + implements Serializable, Accessible { + + /** + * Compatible with Sun's JDK. + */ + private static final long serialVersionUID = -2284879212465893870L; + + /** + * The graphics configuration associated with the canvas. + */ transient GraphicsConfiguration graphicsConfiguration; /** + * The buffer strategy associated with this canvas. + */ + transient BufferStrategy bufferStrategy; + + /** * Initializes a new instance of <code>Canvas</code>. */ - public Canvas() { } + public Canvas() + { + } + /** + * Initializes a new instance of <code>Canvas</code> + * with the supplied graphics configuration. + * + * @param graphicsConfiguration the graphics configuration to use + * for this particular canvas. + */ public Canvas(GraphicsConfiguration graphicsConfiguration) { this.graphicsConfiguration = graphicsConfiguration; @@ -71,7 +114,7 @@ } /** - * Repaints the canvas window. This method should be overriden by + * Repaints the canvas window. This method should be overridden by * a subclass to do something useful, as this method simply paints * the window with the background color. */ @@ -86,6 +129,83 @@ gfx.fillRect(0, 0, size.width, size.height); } - // Serialization constant - private static final long serialVersionUID = -2284879212465893870L; + + /** + * This class provides accessibility support for the canvas. + */ + protected class AccessibleAWTCanvas + extends AccessibleAWTComponent + { + + /** + * Constructor for the accessible canvas. + */ + protected AccessibleAWTCanvas() + { + } + + /** + * Returns the accessible role for the canvas. + * + * @return an instance of <code>AccessibleRole</code>, describing + * the role of the canvas. + */ + public AccessibleRole getAccessibleRole() + { + return AccessibleRole.CANVAS; + } + + } + + /** + * Gets the AccessibleContext associated with this <code>Canvas</code>. + * The context is created, if necessary. + * + * @return the associated context + */ + public AccessibleContext getAccessibleContext() + { + /* Create the context if this is the first request */ + if (accessibleContext == null) + { + /* Create the context */ + accessibleContext = new AccessibleAWTCanvas(); + } + return accessibleContext; + } + + /** + * Returns the buffer strategy used by the canvas. + * + * @return the buffer strategy. + * @since 1.4 + */ + public BufferStrategy getBufferStrategy() + { + return bufferStrategy; + } + + /** + * Updates the canvas in response to a request to + * <code>repaint()</code> it. The canvas is cleared + * with the current background colour, before <code>paint()</code> + * is called to add the new contents. Subclasses + * which override this method should either call this + * method via <code>super.update(graphics)</code> or re-implement + * this behaviour, so as to ensure that the canvas is + * clear before painting takes place. + * + * @param graphics the graphics context. + */ + public void update(Graphics graphics) + { + Dimension size; + + /* Clear the canvas */ + size = getSize(); + graphics.clearRect(0, 0, size.width, size.height); + /* Call the paint method */ + paint(graphics); + } + } Index: kaffe/libraries/javalib/java/awt/KeyboardFocusManager.java diff -u kaffe/libraries/javalib/java/awt/KeyboardFocusManager.java:1.2 kaffe/libraries/javalib/java/awt/KeyboardFocusManager.java:1.3 --- kaffe/libraries/javalib/java/awt/KeyboardFocusManager.java:1.2 Sun Jul 25 06:37:41 2004 +++ kaffe/libraries/javalib/java/awt/KeyboardFocusManager.java Wed Aug 25 22:06:02 2004 @@ -55,20 +55,64 @@ 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.) + * The <code>KeyboardFocusManager</code> handles the focusing of + * windows for receiving keyboard events. The manager handles + * the dispatch of all <code>FocusEvent</code>s and + * <code>KeyEvent</code>s, along with <code>WindowEvent</code>s + * relating to the focused window. Users can use the manager + * to ascertain the current focus owner and fire events. + * <br /> + * <br /> + * The focus owner is the <code>Component</code> that receives + * key events. The focus owner is either the currently focused + * window or a component within this window. + * <br /> + * <br /> + * The underlying native windowing system may denote the active + * window or its children with special decorations (e.g. a highlighted + * title bar). The active window is always either a <code>Frame</code> + * or <code>Dialog</code>, and is either the currently focused + * window or its owner. + * <br /> + * <br /> + * Applets may be partitioned into different applet contexts, according + * to their code base. In this case, each context has its own + * <code>KeyboardFocusManager</code>, 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 <code>ClassLoader</code>. + * <br /> + * <br /> + * To support this separation of focus managers, the manager instances + * and the internal state information is grouped by the + * <code>ThreadGroup</code> to which it pertains. With respect to + * applets, each code base has its own <code>ThreadGroup</code>, so the + * isolation of each context is enforced within the manager. + * <br /> + * <br /> + * By default, the manager defines TAB and Ctrl+TAB as the + * forward focus traversal keys and Shift+TAB and Ctrl+Shift+TAB + * as the backward focus traversal keys. No up or down cycle + * traversal keys are defined by default. Traversal takes effect + * on the firing of a relevant <code>KEY_PRESSED</code> event. + * However, all other key events related to the use of the + * defined focus traversal key sequence are consumed and not + * dispatched. + * <br /> + * <br /> + * These default traversal keys come into effect on all windows + * for which no alternative set of keys is defined. This also + * applies recursively to any child components of such a window, + * which define no traversal keys of their own. * * @author Eric Blake <[EMAIL PROTECTED]> * @author Thomas Fitzsimmons <[EMAIL PROTECTED]> + * @author Andrew John Hughes <[EMAIL PROTECTED]> * @since 1.4 - * @status partially updated to 1.4, needs documentation. */ public abstract class KeyboardFocusManager implements KeyEventDispatcher, KeyEventPostProcessor @@ -182,7 +226,14 @@ Collections.EMPTY_SET, Collections.EMPTY_SET }; + /** + * A utility class to support the handling of events relating to property changes. + */ private final PropertyChangeSupport propertyChangeSupport = new PropertyChangeSupport (this); + + /** + * A utility class to support the handling of events relating to vetoable changes. + */ private final VetoableChangeSupport vetoableChangeSupport = new VetoableChangeSupport (this); /** A list of [EMAIL PROTECTED] KeyEventDispatcher}s that process [EMAIL PROTECTED] @@ -623,29 +674,99 @@ setGlobalObject (currentFocusCycleRoots, cycleRoot, "currentFocusCycleRoot"); } + /** + * Registers the supplied property change listener for receiving + * events caused by the following property changes: + * + * <ul> + * <li>the current focus owner ("focusOwner")</li> + * <li>the permanent focus owner ("permanentFocusOwner")</li> + * <li>the focused window ("focusedWindow")</li> + * <li>the active window ("activeWindow")</li> + * <li>the default focus traversal policy ("defaultFocusTraversalPolicy")</li> + * <li>the default set of forward traversal keys ("forwardDefaultFocusTraversalKeys")</li> + * <li>the default set of backward traversal keys ("backwardDefaultFocusTraversalKeys")</li> + * <li>the default set of up cycle traversal keys ("upCycleDefaultFocusTraversalKeys")</li> + * <li>the default set of down cycle traversal keys ("downCycleDefaultFocusTraversalKeys")</li> + * <li>the current focus cycle root ("currentFocusCycleRoot")</li> + * </ul> + * + * If the supplied listener is null, nothing occurs. + * + * @param l the new listener to register. + * @see KeyboardFocusManager#addPropertyChangeListener(String, java.beans.PropertyChangeListener) + */ public void addPropertyChangeListener(PropertyChangeListener l) { if (l != null) propertyChangeSupport.addPropertyChangeListener(l); } + /** + * Removes the supplied property change listener from the list + * of registered listeners. If the supplied listener is null, + * nothing occurs. + * + * @param l the listener to remove. + */ public void removePropertyChangeListener(PropertyChangeListener l) { if (l != null) propertyChangeSupport.removePropertyChangeListener(l); } + /** + * Returns the currently registered property change listeners + * in array form. The returned array is empty if no listeners are + * currently registered. + * + * @return an array of registered property change listeners. + */ public PropertyChangeListener[] getPropertyChangeListeners() { return propertyChangeSupport.getPropertyChangeListeners(); } + /** + * Registers a property change listener for receiving events relating + * to a change to a specified property. The supplied property name can be + * either user-defined or one from the following list of properties + * relevant to this class: + * + * <ul> + * <li>the current focus owner ("focusOwner")</li> + * <li>the permanent focus owner ("permanentFocusOwner")</li> + * <li>the focused window ("focusedWindow")</li> + * <li>the active window ("activeWindow")</li> + * <li>the default focus traversal policy ("defaultFocusTraversalPolicy")</li> + * <li>the default set of forward traversal keys ("forwardDefaultFocusTraversalKeys")</li> + * <li>the default set of backward traversal keys ("backwardDefaultFocusTraversalKeys")</li> + * <li>the default set of up cycle traversal keys ("upCycleDefaultFocusTraversalKeys")</li> + * <li>the default set of down cycle traversal keys ("downCycleDefaultFocusTraversalKeys")</li> + * <li>the current focus cycle root ("currentFocusCycleRoot")</li> + * </ul> + * + * Nothing occurs if a null listener is supplied. null is regarded as a valid property name. + * + * @param name the name of the property to handle change events for. + * @param l the listener to register for changes to the specified property. + * @see KeyboardFocusManager#addPropertyChangeListener(java.beans.PropertyChangeListener) + */ public void addPropertyChangeListener(String name, PropertyChangeListener l) { if (l != null) propertyChangeSupport.addPropertyChangeListener(name, l); } + /** + * Removes the supplied property change listener registered for the + * specified property from the list of registered listeners. If the + * supplied listener is null, nothing occurs. + * + * @param name the name of the property the listener is + * monitoring changes to. + * @param l the listener to remove. + */ public void removePropertyChangeListener(String name, PropertyChangeListener l) { @@ -653,39 +774,117 @@ propertyChangeSupport.removePropertyChangeListener(name, l); } + /** + * Returns the currently registered property change listeners + * in array form, which listen for changes to the supplied property. + * The returned array is empty, if no listeners are currently registered + * for events pertaining to the supplied property. + * + * @param name The property the returned listeners monitor for changes. + * @return an array of registered property change listeners which + * listen for changes to the supplied property. + */ public PropertyChangeListener[] getPropertyChangeListeners(String name) { return propertyChangeSupport.getPropertyChangeListeners(name); } + /** + * Fires a property change event as a response to a change to + * to the specified property. The event is only fired if a + * change has actually occurred (i.e. o and n are different). + * + * @param name The name of the property to which a change occurred. + * @param o The old value of the property. + * @param n The new value of the property. + */ protected void firePropertyChange(String name, Object o, Object n) { propertyChangeSupport.firePropertyChange(name, o, n); } + /** + * Registers a vetoable property change listener for receiving events + * relating to the following properties: + * + * <ul> + * <li>the current focus owner ("focusOwner")</li> + * <li>the permanent focus owner ("permanentFocusOwner")</li> + * <li>the focused window ("focusedWindow")</li> + * <li>the active window ("activeWindow")</li> + * </ul> + * + * Nothing occurs if a null listener is supplied. + * + * @param l the listener to register. + * @see KeyboardFocusManager#addVetoableChangeListener(String, java.beans.VetoableChangeListener) + */ public void addVetoableChangeListener(VetoableChangeListener l) { if (l != null) vetoableChangeSupport.addVetoableChangeListener(l); } + /** + * Removes the supplied vetoable property change listener from + * the list of registered listeners. If the supplied listener + * is null, nothing occurs. + * + * @param l the listener to remove. + */ public void removeVetoableChangeListener(VetoableChangeListener l) { if (l != null) vetoableChangeSupport.removeVetoableChangeListener(l); } + /** + * Returns the currently registered vetoable property change listeners + * in array form. The returned array is empty if no listeners are + * currently registered. + * + * @return an array of registered vetoable property change listeners. + * @since 1.4 + */ public VetoableChangeListener[] getVetoableChangeListeners() { return vetoableChangeSupport.getVetoableChangeListeners(); } + /** + * Registers a vetoable property change listener for receiving events relating + * to a vetoable change to a specified property. The supplied property name can be + * either user-defined or one from the following list of properties + * relevant to this class: + * + * <ul> + * <li>the current focus owner ("focusOwner")</li> + * <li>the permanent focus owner ("permanentFocusOwner")</li> + * <li>the focused window ("focusedWindow")</li> + * <li>the active window ("activeWindow")</li> + * </ul> + * + * Nothing occurs if a null listener is supplied. null is regarded as a valid property name. + * + * @param name the name of the property to handle change events for. + * @param l the listener to register for changes to the specified property. + * @see KeyboardFocusManager#addVetoableChangeListener(java.beans.VetoableChangeListener) + */ public void addVetoableChangeListener(String name, VetoableChangeListener l) { if (l != null) vetoableChangeSupport.addVetoableChangeListener(name, l); } + /** + * Removes the supplied vetoable property change listener registered + * for the specified property from the list of registered listeners. + * If the supplied listener is null, nothing occurs. + * + * @param name the name of the vetoable property the listener is + * monitoring changes to. + * @param l the listener to remove. + */ public void removeVetoableChangeListener(String name, VetoableChangeListener l) { @@ -693,93 +892,413 @@ vetoableChangeSupport.removeVetoableChangeListener(name, l); } + /** + * Returns the currently registered vetoable property change listeners + * in array form, which listen for changes to the supplied property. + * The returned array is empty, if no listeners are currently registered + * for events pertaining to the supplied property. + * + * @param name The property the returned listeners monitor for changes. + * @return an array of registered property change listeners which + * listen for changes to the supplied property. + * @since 1.4 + */ public VetoableChangeListener[] getVetoableChangeListeners(String name) { return vetoableChangeSupport.getVetoableChangeListeners(name); } + /** + * Fires a property change event as a response to a vetoable change to + * to the specified property. The event is only fired if a + * change has actually occurred (i.e. o and n are different). + * In the event that the property change is vetoed, the following + * occurs: + * + * <ol> + * <li> + * This method throws a <code>PropertyVetoException</code> to + * the proposed change. + * </li> + * <li> + * A new event is fired to reverse the previous change. + * </li> + * <li> + * This method again throws a <code>PropertyVetoException</code> + * in response to the reversion. + * </li> + * </ol> + * + * @param name The name of the property to which a change occurred. + * @param o The old value of the property. + * @param n The new value of the property. + * @throws PropertyVetoException if one of the listeners vetos + * the change by throwing this exception. + */ protected void fireVetoableChange(String name, Object o, Object n) throws PropertyVetoException { vetoableChangeSupport.fireVetoableChange(name, o, n); } + /** + * Adds a key event dispatcher to the list of registered dispatchers. + * When a key event is fired, each dispatcher's <code>dispatchKeyEvent</code> + * 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. + * <br /> + * <br /> + * The same dispatcher can exist multiple times within the list + * of registered dispatchers, and there is no limit on the length + * of this list. A null dispatcher is simply ignored. + * + * @param dispatcher The dispatcher to register. + */ public void addKeyEventDispatcher(KeyEventDispatcher dispatcher) { if (dispatcher != null) keyEventDispatchers.add(dispatcher); } + /** + * Removes the specified key event dispatcher from the list of + * registered dispatchers. The manager always dispatches events, + * regardless of its existence within the list. The manager + * can be added and removed from the list, as with any other + * dispatcher, but this does not affect its ability to dispatch + * key events. Non-existent and null dispatchers are simply ignored + * by this method. + * + * @param dispatcher The dispatcher to remove. + */ public void removeKeyEventDispatcher(KeyEventDispatcher dispatcher) { keyEventDispatchers.remove(dispatcher); } + /** + * Returns the currently registered key event dispatchers in <code>List</code> + * form. At present, this only includes dispatchers explicitly registered + * via the <code>addKeyEventDispatcher()</code> 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 <code>postProcessKeyEvent</code> + * 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. + * <br /> + * <br /> + * The same post processor can exist multiple times within the list + * of registered post processors, and there is no limit on the length + * of this list. A null post processor is simply ignored. + * + * @param postProcessor the post processor to register. + * @see KeyboardFocusManager#addKeyEventDispatcher(java.awt.KeyEventDispatcher) + */ public void addKeyEventPostProcessor (KeyEventPostProcessor postProcessor) { if (postProcessor != null) keyEventPostProcessors.add (postProcessor); } + /** + * Removes the specified key event post processor from the list of + * registered post processors. The manager always post processes events, + * regardless of its existence within the list. The manager + * can be added and removed from the list, as with any other + * post processor, but this does not affect its ability to post process + * key events. Non-existent and null post processors are simply ignored + * by this method. + * + * @param postProcessor the post processor to remove. + */ public void removeKeyEventPostProcessor (KeyEventPostProcessor postProcessor) { keyEventPostProcessors.remove (postProcessor); } + /** + * Returns the currently registered key event post processors in <code>List</code> + * form. At present, this only includes post processors explicitly registered + * via the <code>addKeyEventPostProcessor()</code> 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. + * <br /> + * <br /> + * The manager is expected to handle all <code>FocusEvent</code>s + * and <code>KeyEvent</code>s, and <code>WindowEvent</code>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. + * <br /> + * <br /> + * The actual dispatching is performed by calling + * <code>redispatchEvent()</code>. 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 (<code>dispatchEvent()</code>) and + * the key event dispatchers should use this method to handle + * dispatching rather than the dispatch method of the target + * component. + * <br /> + * <br /> + * <strong> + * This method is not intended for general consumption, and is + * only for the use of the aforementioned classes. + * </strong> + * + * @param target the target component to which the event is + * dispatched. + * @param e the event to dispatch. + */ public final void redispatchEvent (Component target, AWTEvent e) { e.setSource (target); dispatchEvent (e); } + /** + * Attempts to dispatch key events for which no key event dispatcher + * has so far succeeded. This method is usually called by + * <code>dispatchEvent()</code> 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. + * <br /> + * <br /> + * If this method also fails to handle the key event, then + * false is returned to the caller. In the case of + * <code>dispatchEvent()</code>, 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 + * <code>MenuShortcut</code>s. The event is consumed + * in the process and the shortcut is activated. This + * method is usually called by <code>dispatchKeyEvent</code>. + * + * @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 <code>FOCUS_GAINED</code> 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. <code>Canvas</code>es, <code>Panel</code>s, + * <code>Label</code>s, <code>ScrollPane</code>s, <code>Scrollbar</code>s, + * <code>Window</code>s and lightweight components are judged + * to be unacceptable by default. See the + * <code>DefaultFocusTraversalPolicy</code> 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. <code>Canvas</code>es, <code>Panel</code>s, + * <code>Label</code>s, <code>ScrollPane</code>s, <code>Scrollbar</code>s, + * <code>Window</code>s and lightweight components are judged + * to be unacceptable by default. See the + * <code>DefaultFocusTraversalPolicy</code> 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 <code>Window</code>, 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. + * <code>Canvas</code>es, <code>Panel</code>s, + * <code>Label</code>s, <code>ScrollPane</code>s, <code>Scrollbar</code>s, + * <code>Window</code>s and lightweight components are judged + * to be unacceptable by default. See the + * <code>DefaultFocusTraversalPolicy</code> 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. + * <code>Canvas</code>es, <code>Panel</code>s, + * <code>Label</code>s, <code>ScrollPane</code>s, <code>Scrollbar</code>s, + * <code>Window</code>s and lightweight components are judged + * to be unacceptable by default. See the + * <code>DefaultFocusTraversalPolicy</code> 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 <code>Window</code>, 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 <code>Container</code>. + * 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 Index: kaffe/libraries/javalib/java/awt/Label.java diff -u kaffe/libraries/javalib/java/awt/Label.java:1.2 kaffe/libraries/javalib/java/awt/Label.java:1.3 --- kaffe/libraries/javalib/java/awt/Label.java:1.2 Thu Jul 22 19:37:01 2004 +++ kaffe/libraries/javalib/java/awt/Label.java Wed Aug 25 22:06:02 2004 @@ -40,13 +40,16 @@ import java.awt.peer.LabelPeer; import javax.accessibility.Accessible; +import javax.accessibility.AccessibleContext; +import javax.accessibility.AccessibleRole; /** * This component is used for displaying simple text strings that cannot - * be edited. + * be edited by the user. * * @author Aaron M. Renn ([EMAIL PROTECTED]) * @author Tom Tromey <[EMAIL PROTECTED]> + * @author Andrew John Hughes <[EMAIL PROTECTED]> */ public class Label extends Component implements Accessible { @@ -247,6 +250,61 @@ { return ("text=" + getText() + ",alignment=" + getAlignment() + "," + super.paramString()); +} + +/** + * This class provides accessibility support for the label. + */ +protected class AccessibleAWTLabel + extends AccessibleAWTComponent +{ + /** + * Constructor for the accessible label. + */ + public AccessibleAWTLabel() + { + } + *** Patch too long, truncated *** _______________________________________________ kaffe mailing list [EMAIL PROTECTED] http://kaffe.org/cgi-bin/mailman/listinfo/kaffe