diff options
Diffstat (limited to 'libjava/classpath/javax/swing/JComponent.java')
| -rw-r--r-- | libjava/classpath/javax/swing/JComponent.java | 218 |
1 files changed, 138 insertions, 80 deletions
diff --git a/libjava/classpath/javax/swing/JComponent.java b/libjava/classpath/javax/swing/JComponent.java index 42a5317dc77..dc7689b0930 100644 --- a/libjava/classpath/javax/swing/JComponent.java +++ b/libjava/classpath/javax/swing/JComponent.java @@ -38,12 +38,14 @@ exception statement from your version. */ package javax.swing; +import java.applet.Applet; import java.awt.AWTEvent; import java.awt.Color; import java.awt.Component; import java.awt.Container; import java.awt.Dimension; import java.awt.FlowLayout; +import java.awt.FocusTraversalPolicy; import java.awt.Font; import java.awt.Graphics; import java.awt.Graphics2D; @@ -51,6 +53,7 @@ import java.awt.Image; import java.awt.Insets; import java.awt.Point; import java.awt.Rectangle; +import java.awt.Window; import java.awt.dnd.DropTarget; import java.awt.event.ActionEvent; import java.awt.event.ActionListener; @@ -71,6 +74,7 @@ import java.io.Serializable; import java.util.EventListener; import java.util.Hashtable; import java.util.Locale; +import java.util.Set; import javax.accessibility.Accessible; import javax.accessibility.AccessibleContext; @@ -86,7 +90,7 @@ import javax.swing.event.SwingPropertyChangeSupport; import javax.swing.plaf.ComponentUI; /** - * Every component in swing inherits from this class (JLabel, JButton, etc). + * The base class of all Swing components. * It contains generic methods to manage events, properties and sizes. Actual * drawing of the component is channeled to a look-and-feel class that is * implemented elsewhere. @@ -103,10 +107,17 @@ public abstract class JComponent extends Container implements Serializable */ protected AccessibleContext accessibleContext; + /** + * Basic accessibility support for <code>JComponent</code> derived + * widgets. + */ public abstract class AccessibleJComponent extends AccessibleAWTContainer implements AccessibleExtendedComponent { + /** + * Accessibility support for <code>JComponent</code>'s focus handler. + */ protected class AccessibleFocusHandler implements FocusListener { @@ -115,6 +126,9 @@ public abstract class JComponent extends Container implements Serializable public void focusLost(FocusEvent valevent){} } + /** + * Accessibility support for <code>JComponent</code>'s container handler. + */ protected class AccessibleContainerHandler implements ContainerListener { @@ -273,7 +287,7 @@ public abstract class JComponent extends Container implements Serializable * repainting of the component are usually delegated to this object. * * @see #setUI - * @see #getUI + * @see #getUIClassID * @see #updateUI */ protected ComponentUI ui; @@ -361,7 +375,7 @@ public abstract class JComponent extends Container implements Serializable * Constant used to indicate that no condition has been assigned to a * particular action. * - * @see #registerKeyboardAction + * @see #registerKeyboardAction(ActionListener, KeyStroke, int) */ public static final int UNDEFINED_CONDITION = -1; @@ -369,7 +383,7 @@ public abstract class JComponent extends Container implements Serializable * Constant used to indicate that an action should be performed only when * the component has focus. * - * @see #registerKeyboardAction + * @see #registerKeyboardAction(ActionListener, KeyStroke, int) */ public static final int WHEN_FOCUSED = 0; @@ -377,7 +391,7 @@ public abstract class JComponent extends Container implements Serializable * Constant used to indicate that an action should be performed only when * the component is an ancestor of the component which has focus. * - * @see #registerKeyboardAction + * @see #registerKeyboardAction(ActionListener, KeyStroke, int) */ public static final int WHEN_ANCESTOR_OF_FOCUSED_COMPONENT = 1; @@ -385,7 +399,7 @@ public abstract class JComponent extends Container implements Serializable * Constant used to indicate that an action should be performed only when * the component is in the window which has focus. * - * @see #registerKeyboardAction + * @see #registerKeyboardAction(ActionListener, KeyStroke, int) */ public static final int WHEN_IN_FOCUSED_WINDOW = 2; @@ -449,7 +463,10 @@ public abstract class JComponent extends Container implements Serializable */ public final void putClientProperty(Object key, Object value) { - getClientProperties().put(key, value); + if (value != null) + getClientProperties().put(key, value); + else + getClientProperties().remove(key); } /** @@ -457,7 +474,7 @@ public abstract class JComponent extends Container implements Serializable * * @param listener The listener to unregister * - * @see addAncestorListener + * @see #addAncestorListener */ public void removeAncestorListener(AncestorListener listener) { @@ -469,7 +486,7 @@ public abstract class JComponent extends Container implements Serializable * * @param listener The listener to register * - * @see #addPropertyChangeListener + * @see #addPropertyChangeListener(PropertyChangeListener) * @see #changeSupport */ public void removePropertyChangeListener(PropertyChangeListener listener) @@ -484,7 +501,7 @@ public abstract class JComponent extends Container implements Serializable * @param propertyName The property name to unregister the listener from * @param listener The listener to unregister * - * @see #addPropertyChangeListener + * @see #addPropertyChangeListener(String, PropertyChangeListener) * @see #changeSupport */ public void removePropertyChangeListener(String propertyName, @@ -526,7 +543,7 @@ public abstract class JComponent extends Container implements Serializable * * @param listener The listener to register * - * @see #removePropertyChangeListener + * @see #removePropertyChangeListener(PropertyChangeListener) * @see #changeSupport */ public void addPropertyChangeListener(PropertyChangeListener listener) @@ -544,7 +561,7 @@ public abstract class JComponent extends Container implements Serializable * @param propertyName The property name to listen to * @param listener The listener to register * - * @see #removePropertyChangeListener + * @see #removePropertyChangeListener(String, PropertyChangeListener) * @see #changeSupport */ public void addPropertyChangeListener(String propertyName, @@ -712,8 +729,8 @@ public abstract class JComponent extends Container implements Serializable * @param newValue The new value of the property * * @see #changeSupport - * @see #addPropertyChangeListener - * @see #removePropertyChangeListener + * @see #addPropertyChangeListener(PropertyChangeListener) + * @see #removePropertyChangeListener(PropertyChangeListener) */ protected void firePropertyChange(String propertyName, Object oldValue, Object newValue) @@ -745,8 +762,8 @@ public abstract class JComponent extends Container implements Serializable * * @throws PropertyVetoException if the change was vetoed by a listener * - * @see addVetoableChangeListener - * @see removeVetoableChangeListener + * @see #addVetoableChangeListener + * @see #removeVetoableChangeListener */ protected void fireVetoableChange(String propertyName, Object oldValue, Object newValue) @@ -945,7 +962,7 @@ public abstract class JComponent extends Container implements Serializable /** * Get the component's maximum size. If the {@link #maximumSize} property * has been explicitly set, it is returned. If the {@link #maximumSize} - * property has not been set but the {@link ui} property has been, the + * property has not been set but the {@link #ui} property has been, the * result of {@link ComponentUI#getMaximumSize} is returned. If neither * property has been set, the result of {@link Container#getMaximumSize} * is returned. @@ -974,7 +991,7 @@ public abstract class JComponent extends Container implements Serializable /** * Get the component's minimum size. If the {@link #minimumSize} property * has been explicitly set, it is returned. If the {@link #minimumSize} - * property has not been set but the {@link ui} property has been, the + * property has not been set but the {@link #ui} property has been, the * result of {@link ComponentUI#getMinimumSize} is returned. If neither * property has been set, the result of {@link Container#getMinimumSize} * is returned. @@ -1003,7 +1020,7 @@ public abstract class JComponent extends Container implements Serializable /** * Get the component's preferred size. If the {@link #preferredSize} * property has been explicitly set, it is returned. If the {@link - * #preferredSize} property has not been set but the {@link ui} property + * #preferredSize} property has not been set but the {@link #ui} property * has been, the result of {@link ComponentUI#getPreferredSize} is * returned. If neither property has been set, the result of {@link * Container#getPreferredSize} is returned. @@ -1077,7 +1094,7 @@ public abstract class JComponent extends Container implements Serializable } /** - * Return the value of the {@link #nextFocusableComponent} property. + * Return the value of the <code>nextFocusableComponent</code> property. * * @return The current value of the property, or <code>null</code> * if none has been set. @@ -1132,7 +1149,7 @@ public abstract class JComponent extends Container implements Serializable } /** - * Return the {@link #toolTip} property of this component, creating it and + * Return the <code>toolTip</code> property of this component, creating it and * setting it if it is currently <code>null</code>. This method can be * overridden in subclasses which wish to control the exact form of * tooltip created. @@ -1149,7 +1166,7 @@ public abstract class JComponent extends Container implements Serializable } /** - * Return the location at which the {@link #toolTip} property should be + * Return the location at which the {@link #toolTipText} property should be * displayed, when triggered by a particular mouse event. * * @param event The event the tooltip is being presented in response to @@ -1167,7 +1184,7 @@ public abstract class JComponent extends Container implements Serializable * * @param text The new property value * - * @see #getToolTipText + * @see #getToolTipText() */ public void setToolTipText(String text) { @@ -1218,7 +1235,7 @@ public abstract class JComponent extends Container implements Serializable /** * Return the top level ancestral container (usually a {@link - * java.awt.Window} or {@link java.awt.Applet}) which this component is + * java.awt.Window} or {@link java.applet.Applet}) which this component is * contained within, or <code>null</code> if no ancestors exist. * * @return The top level container, if it exists @@ -1275,9 +1292,9 @@ public abstract class JComponent extends Container implements Serializable * displayable, focusable, visible components.</p> * * <p>This method should not be called by clients; it is intended for - * focus implementations. Use {@link Component#requestFocus} instead.</p> + * focus implementations. Use {@link Component#requestFocus()} instead.</p> * - * @see {@link Component#requestFocus} + * @see Component#requestFocus() */ public void grabFocus() { @@ -1317,8 +1334,8 @@ public abstract class JComponent extends Container implements Serializable * @return <code>true</code> if you want this component to manage its own * focus, otherwise (by default) <code>false</code> * - * @deprecated 1.4 Use {@link Component.setFocusTraversalKeys(int,Set)} and - * {@link Container.setFocusCycleRoot(boolean)} instead + * @deprecated 1.4 Use {@link Component#setFocusTraversalKeys(int, Set)} and + * {@link Container#setFocusCycleRoot(boolean)} instead */ public boolean isManagingFocus() { @@ -1326,7 +1343,7 @@ public abstract class JComponent extends Container implements Serializable } /** - * Return the current value of the {@link opaque} property. + * Return the current value of the {@link #opaque} property. * * @return The current property value */ @@ -1370,10 +1387,10 @@ public abstract class JComponent extends Container implements Serializable /** * Return <code>true</code> if this component is a validation root; this - * will cause calls to {@link #invalidate} in this component's children + * will cause calls to {@link #invalidate()} in this component's children * to be "captured" at this component, and not propagate to its parents. * For most components this should return <code>false</code>, but some - * components such as {@link JViewPort} will want to return + * components such as {@link JViewport} will want to return * <code>true</code>. * * @return Whether this component is a validation root @@ -1386,7 +1403,7 @@ public abstract class JComponent extends Container implements Serializable /** * <p>Paint the component. This is a delicate process, and should only be * called from the repaint thread, under control of the {@link - * RepaintManager}. Client code should usually call {@link #repaint} to + * RepaintManager}. Client code should usually call {@link #repaint()} to * trigger painting.</p> * * <p>This method will acquire a double buffer from the {@link @@ -1410,7 +1427,7 @@ public abstract class JComponent extends Container implements Serializable * * @param g The graphics context to paint with * - * @see #paintImmediately + * @see #paintImmediately(Rectangle) */ public void paint(Graphics g) { @@ -1633,18 +1650,18 @@ public abstract class JComponent extends Container implements Serializable * to fetch mapping tables from keystrokes to commands, and commands to * actions, respectively, and modify those mappings directly. * - * @param anAction The action to be registered - * @param aCommand The command to deliver in the delivered {@link - * java.awt.ActionEvent} - * @param aKeyStroke The keystroke to register on - * @param aCondition One of the values {@link #UNDEFINED_CONDITION}, + * @param act The action to be registered + * @param cmd The command to deliver in the delivered {@link + * java.awt.event.ActionEvent} + * @param stroke The keystroke to register on + * @param cond One of the values {@link #UNDEFINED_CONDITION}, * {@link #WHEN_ANCESTOR_OF_FOCUSED_COMPONENT}, {@link #WHEN_FOCUSED}, or * {@link #WHEN_IN_FOCUSED_WINDOW}, indicating the condition which must * be met for the action to be fired * * @see #unregisterKeyboardAction - * @see #getConditionForKeystroke - * @see #resetKeyboardActiond + * @see #getConditionForKeyStroke + * @see #resetKeyboardActions */ public void registerKeyboardAction(ActionListener act, String cmd, @@ -1724,7 +1741,7 @@ public abstract class JComponent extends Container implements Serializable * Return the condition that determines whether a registered action * occurs in response to the specified keystroke. * - * @param aKeyStroke The keystroke to return the condition of + * @param ks The keystroke to return the condition of * * @return One of the values {@link #UNDEFINED_CONDITION}, {@link * #WHEN_ANCESTOR_OF_FOCUSED_COMPONENT}, {@link #WHEN_FOCUSED}, or {@link @@ -1733,9 +1750,9 @@ public abstract class JComponent extends Container implements Serializable * @deprecated As of 1.3 KeyStrokes can be registered with multiple * simultaneous conditions. * - * @see #registerKeyboardAction + * @see #registerKeyboardAction(ActionListener, KeyStroke, int) * @see #unregisterKeyboardAction - * @see #resetKeyboardActiond + * @see #resetKeyboardActions */ public int getConditionForKeyStroke(KeyStroke ks) { @@ -1756,7 +1773,7 @@ public abstract class JComponent extends Container implements Serializable * Get the ActionListener (typically an {@link Action} object) which is * associated with a particular keystroke. * - * @param aKeyStroke The keystroke to retrieve the action of + * @param ks The keystroke to retrieve the action of * * @return The action associated with the specified keystroke * @@ -1796,12 +1813,52 @@ public abstract class JComponent extends Container implements Serializable super.processKeyEvent(e); processComponentKeyEvent(e); - // FIXME: this needs to be elaborated significantly, to do all the - // focus / ancestor / window searching for the various binding modes. - if (! e.isConsumed() && - processKeyBinding(KeyStroke.getKeyStrokeForEvent(e), + if (e.isConsumed()) + return; + + // Input maps are checked in this order: + // 1. The focused component's WHEN_FOCUSED map is checked. + // 2. The focused component's WHEN_ANCESTOR_OF_FOCUSED_COMPONENT map. + // 3. The WHEN_ANCESTOR_OF_FOCUSED_COMPONENT maps of the focused + // component's parent, then its parent's parent, and so on. + // Note: Input maps for disabled components are skipped. + // 4. The WHEN_IN_FOCUSED_WINDOW maps of all the enabled components in + // the focused window are searched. + + if (processKeyBinding(KeyStroke.getKeyStrokeForEvent(e), e, WHEN_FOCUSED, e.getID() == KeyEvent.KEY_PRESSED)) + // This is step 1 from above comment. e.consume(); + else if (processKeyBinding(KeyStroke.getKeyStrokeForEvent(e), + e, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, + e.getID() == KeyEvent.KEY_PRESSED)) + // This is step 2 from above comment. + e.consume(); + else + { + // This is step 3 from above comment. + Container current = this; + while ((current = current.getParent()) instanceof JComponent) + { + if (((JComponent)current).processKeyBinding + (KeyStroke.getKeyStrokeForEvent(e), e, + WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, + e.getID() == KeyEvent.KEY_PRESSED)) + { + e.consume(); + break; + } + if (current instanceof Window || current instanceof Applet + || current instanceof JInternalFrame) + break; + } + if (e.isConsumed()) + return; + + // This is step 4 from above comment. + // FIXME: Implement. Note, should use ComponentInputMaps rather + // than walking the entire containment hierarchy. + } } protected boolean processKeyBinding(KeyStroke ks, @@ -1833,11 +1890,11 @@ public abstract class JComponent extends Container implements Serializable /** * Remove a keyboard action registry. * - * @param stroke The keystroke to unregister + * @param aKeyStroke The keystroke to unregister * - * @see #registerKeyboardAction - * @see #getConditionForKeystroke - * @see #resetKeyboardActiond + * @see #registerKeyboardAction(ActionListener, KeyStroke, int) + * @see #getConditionForKeyStroke + * @see #resetKeyboardActions */ public void unregisterKeyboardAction(KeyStroke aKeyStroke) { @@ -1848,9 +1905,9 @@ public abstract class JComponent extends Container implements Serializable /** * Reset all keyboard action registries. * - * @see #registerKeyboardAction + * @see #registerKeyboardAction(ActionListener, KeyStroke, int) * @see #unregisterKeyboardAction - * @see #getConditionForKeystroke + * @see #getConditionForKeyStroke */ public void resetKeyboardActions() { @@ -1902,7 +1959,7 @@ public abstract class JComponent extends Container implements Serializable * Request focus on the default component of this component's {@link * FocusTraversalPolicy}. * - * @return The result of {@link #requestFocus} + * @return The result of {@link #requestFocus()} * * @deprecated Use {@link #requestFocus()} on the default component provided * from the {@link FocusTraversalPolicy} instead. @@ -1986,7 +2043,7 @@ public abstract class JComponent extends Container implements Serializable } /** - * Set the value of the {@link #enabled} property. + * Set the value of the <code>enabled</code> property. * * @param enable The new value of the property */ @@ -1998,7 +2055,7 @@ public abstract class JComponent extends Container implements Serializable } /** - * Set the value of the {@link #font} property. + * Set the value of the <code>font</code> property. * * @param f The new value of the property */ @@ -2008,7 +2065,7 @@ public abstract class JComponent extends Container implements Serializable } /** - * Set the value of the {@link #background} property. + * Set the value of the <code>background</code> property. * * @param bg The new value of the property */ @@ -2018,7 +2075,7 @@ public abstract class JComponent extends Container implements Serializable } /** - * Set the value of the {@link #foreground} property. + * Set the value of the <code>foreground</code> property. * * @param fg The new value of the property */ @@ -2091,7 +2148,7 @@ public abstract class JComponent extends Container implements Serializable * * @return The current value of the property * - * @see ComponentUI#setTransferHandler + * @see #setTransferHandler */ public TransferHandler getTransferHandler() @@ -2104,7 +2161,7 @@ public abstract class JComponent extends Container implements Serializable * * @param newHandler The new value of the property * - * @see ComponentUI#getTransferHandler + * @see #getTransferHandler */ public void setTransferHandler(TransferHandler newHandler) @@ -2142,7 +2199,7 @@ public abstract class JComponent extends Container implements Serializable } /** - * Call {@link paint}. + * Call {@link #paint}. * * @param g The graphics context to paint into */ @@ -2155,7 +2212,7 @@ public abstract class JComponent extends Container implements Serializable * Get the value of the UIClassID property. This property should be a key * in the {@link UIDefaults} table managed by {@link UIManager}, the * value of which is the name of a class to load for the component's - * {@link ui} property. + * {@link #ui} property. * * @return A "symbolic" name which will map to a class to use for the * component's UI, such as <code>"ComponentUI"</code> @@ -2169,10 +2226,10 @@ public abstract class JComponent extends Container implements Serializable } /** - * Install a new UI delegate as the component's {@link ui} property. In - * the process, this will call {@link ComponentUI.uninstallUI} on any - * existing value for the {@link ui} property, and {@link - * ComponentUI.installUI} on the new UI delegate. + * Install a new UI delegate as the component's {@link #ui} property. In + * the process, this will call {@link ComponentUI#uninstallUI} on any + * existing value for the {@link #ui} property, and {@link + * ComponentUI#installUI} on the new UI delegate. * * @param newUI The new UI delegate to install * @@ -2198,7 +2255,7 @@ public abstract class JComponent extends Container implements Serializable * This method should be overridden in subclasses. In JComponent, the * method does nothing. In subclasses, it should a UI delegate * (corresponding to the symbolic name returned from {@link - * getUIClassID}) from the {@link UIManager}, and calls {@link setUI} + * #getUIClassID}) from the {@link UIManager}, and calls {@link #setUI} * with the new delegate. */ public void updateUI() @@ -2273,9 +2330,9 @@ public abstract class JComponent extends Container implements Serializable * situations in which it is not possible to get the focus. So developers * should not assume that the component has the focus until it receives * a {@link java.awt.event.FocusEvent} with a value of - * {@link java.awt.event.FocusEvent.FOCUS_GAINED}. + * {@link java.awt.event.FocusEvent#FOCUS_GAINED}. * - * @see {@link Component#requestFocus()} + * @see Component#requestFocus() */ public void requestFocus() { @@ -2288,15 +2345,15 @@ public abstract class JComponent extends Container implements Serializable * by look and feel implementations. * * You should not use this method directly. Instead you are strongly - * encouraged to call {@link #requestFocus} or {@link #requestFocusInWindow} - * instead. + * encouraged to call {@link #requestFocus()} or + * {@link #requestFocusInWindow()} instead. * * @param temporary if the focus change is temporary * * @return <code>false</code> if the focus change request will definitly * fail, <code>true</code> if it will likely succeed * - * @see {@link Component#requestFocus(boolean)} + * @see Component#requestFocus(boolean) * * @since 1.4 */ @@ -2317,12 +2374,12 @@ public abstract class JComponent extends Container implements Serializable * situations in which it is not possible to get the focus. So developers * should not assume that the component has the focus until it receives * a {@link java.awt.event.FocusEvent} with a value of - * {@link java.awt.event.FocusEvent.FOCUS_GAINED}. + * {@link java.awt.event.FocusEvent#FOCUS_GAINED}. * * @return <code>false</code> if the focus change request will definitly * fail, <code>true</code> if it will likely succeed * - * @see {@link Component#requestFocusInWindow()} + * @see Component#requestFocusInWindow() */ public boolean requestFocusInWindow() { @@ -2337,15 +2394,15 @@ public abstract class JComponent extends Container implements Serializable * by look and feel implementations. * * You should not use this method directly. Instead you are strongly - * encouraged to call {@link #requestFocus} or {@link #requestFocusInWindow} - * instead. + * encouraged to call {@link #requestFocus()} or + * {@link #requestFocusInWindow()} instead. * * @param temporary if the focus change is temporary * * @return <code>false</code> if the focus change request will definitly * fail, <code>true</code> if it will likely succeed * - * @see {@link Component#requestFocus(boolean)} + * @see Component#requestFocus(boolean) * * @since 1.4 */ @@ -2426,7 +2483,8 @@ public abstract class JComponent extends Container implements Serializable * has changed. * * This method is called before the component is actually removed from - * its parent, so the parent is still visible through {@link #getParent}. + * its parent, so the parent is still visible through + * {@link Component#getParent}. */ public void removeNotify() { @@ -2585,7 +2643,7 @@ public abstract class JComponent extends Container implements Serializable /** * Prints this component to the given Graphics context. A call to this * method results in calls to the methods {@link #printComponent}, - * {@link #printBorder} and {@link printChildren} in this order. + * {@link #printBorder} and {@link #printChildren} in this order. * * Double buffering is temporarily turned off so the painting goes directly * to the supplied Graphics context. |
