< prev index next >

src/java.desktop/share/classes/javax/swing/Action.java

Print this page

        

@@ -27,17 +27,17 @@
 import java.awt.*;
 import java.awt.event.*;
 import java.beans.*;
 
 /**
- * The <code>Action</code> interface provides a useful extension to the
- * <code>ActionListener</code>
+ * The {@code Action} interface provides a useful extension to the
+ * {@code ActionListener}
  * interface in cases where the same functionality may be accessed by
  * several controls.
  * <p>
- * In addition to the <code>actionPerformed</code> method defined by the
- * <code>ActionListener</code> interface, this interface allows the
+ * In addition to the {@code actionPerformed} method defined by the
+ * {@code ActionListener} interface, this interface allows the
  * application to define, in a single place:
  * <ul>
  * <li>One or more text strings that describe the function. These strings
  *     can be used, for example, to display the flyover text for a button
  *     or to set the text in a menu item.

@@ -51,129 +51,129 @@
  *     then know to disable event generation for that item and to modify the
  *     display accordingly.
  * </ul>
  * <p>
  * This interface can be added to an existing class or used to create an
- * adapter (typically, by subclassing <code>AbstractAction</code>).
- * The <code>Action</code> object
- * can then be added to multiple <code>Action</code>-aware containers
- * and connected to <code>Action</code>-capable
+ * adapter (typically, by subclassing {@code AbstractAction}).
+ * The {@code Action} object
+ * can then be added to multiple {@code Action}-aware containers
+ * and connected to {@code Action}-capable
  * components. The GUI controls can then be activated or
- * deactivated all at once by invoking the <code>Action</code> object's
- * <code>setEnabled</code> method.
+ * deactivated all at once by invoking the {@code Action} object's
+ * {@code setEnabled} method.
  * <p>
- * Note that <code>Action</code> implementations tend to be more expensive
- * in terms of storage than a typical <code>ActionListener</code>,
+ * Note that {@code Action} implementations tend to be more expensive
+ * in terms of storage than a typical {@code ActionListener},
  * which does not offer the benefits of centralized control of
  * functionality and broadcast of property changes.  For this reason,
- * you should take care to only use <code>Action</code>s where their benefits
- * are desired, and use simple <code>ActionListener</code>s elsewhere.
+ * you should take care to only use {@code Action}s where their benefits
+ * are desired, and use simple {@code ActionListener}s elsewhere.
  * <br>
  *
- * <h3><a name="buttonActions"></a>Swing Components Supporting <code>Action</code></h3>
+ * <h3><a name="buttonActions"></a>Swing Components Supporting {@code Action}</h3>
  * <p>
- * Many of Swing's components have an <code>Action</code> property.  When
- * an <code>Action</code> is set on a component, the following things
+ * Many of Swing's components have an {@code Action} property.  When
+ * an {@code Action} is set on a component, the following things
  * happen:
  * <ul>
- * <li>The <code>Action</code> is added as an <code>ActionListener</code> to
+ * <li>The {@code Action} is added as an {@code ActionListener} to
  *     the component.
  * <li>The component configures some of its properties to match the
- *      <code>Action</code>.
- * <li>The component installs a <code>PropertyChangeListener</code> on the
- *     <code>Action</code> so that the component can change its properties
- *     to reflect changes in the <code>Action</code>'s properties.
+ *      {@code Action}.
+ * <li>The component installs a {@code PropertyChangeListener} on the
+ *     {@code Action} so that the component can change its properties
+ *     to reflect changes in the {@code Action}'s properties.
  * </ul>
  * <p>
  * The following table describes the properties used by
- * <code>Swing</code> components that support <code>Actions</code>.
+ * {@code Swing} components that support {@code Actions}.
  * In the table, <em>button</em> refers to any
- * <code>AbstractButton</code> subclass, which includes not only
- * <code>JButton</code> but also classes such as
- * <code>JMenuItem</code>. Unless otherwise stated, a
- * <code>null</code> property value in an <code>Action</code> (or a
- * <code>Action</code> that is <code>null</code>) results in the
- * button's corresponding property being set to <code>null</code>.
+ * {@code AbstractButton} subclass, which includes not only
+ * {@code JButton} but also classes such as
+ * {@code JMenuItem}. Unless otherwise stated, a
+ * {@code null} property value in an {@code Action} (or a
+ * {@code Action} that is {@code null}) results in the
+ * button's corresponding property being set to {@code null}.
  *
  * <table border="1" cellpadding="1" cellspacing="0"
  *         summary="Supported Action properties">
  *  <tr valign="top"  align="left">
  *    <th style="background-color:#CCCCFF" align="left">Component Property
  *    <th style="background-color:#CCCCFF" align="left">Components
  *    <th style="background-color:#CCCCFF" align="left">Action Key
  *    <th style="background-color:#CCCCFF" align="left">Notes
  *  <tr valign="top"  align="left">
- *      <td><b><code>enabled</code></b>
+ *      <td><b>{@code enabled}</b>
  *      <td>All
- *      <td>The <code>isEnabled</code> method
+ *      <td>The {@code isEnabled} method
  *      <td>&nbsp;
  *  <tr valign="top"  align="left">
- *      <td><b><code>toolTipText</code></b>
+ *      <td><b>{@code toolTipText}</b>
  *      <td>All
- *      <td><code>SHORT_DESCRIPTION</code>
+ *      <td>{@code SHORT_DESCRIPTION}
  *      <td>&nbsp;
  *  <tr valign="top"  align="left">
- *      <td><b><code>actionCommand</code></b>
+ *      <td><b>{@code actionCommand}</b>
  *      <td>All
- *      <td><code>ACTION_COMMAND_KEY</code>
+ *      <td>{@code ACTION_COMMAND_KEY}
  *      <td>&nbsp;
  *  <tr valign="top"  align="left">
- *      <td><b><code>mnemonic</code></b>
+ *      <td><b>{@code mnemonic}</b>
  *      <td>All buttons
- *      <td><code>MNEMONIC_KEY</code>
- *      <td>A <code>null</code> value or <code>Action</code> results in the
- *          button's <code>mnemonic</code> property being set to
- *          <code>'\0'</code>.
+ *      <td>{@code MNEMONIC_KEY}
+ *      <td>A {@code null} value or {@code Action} results in the
+ *          button's {@code mnemonic} property being set to
+ *          {@code '\0'}.
  *  <tr valign="top"  align="left">
- *      <td><b><code>text</code></b>
+ *      <td><b>{@code text}</b>
  *      <td>All buttons
- *      <td><code>NAME</code>
+ *      <td>{@code NAME}
  *      <td>If you do not want the text of the button to mirror that
- *          of the <code>Action</code>, set the property
- *          <code>hideActionText</code> to <code>true</code>.  If
- *          <code>hideActionText</code> is <code>true</code>, setting the
- *          <code>Action</code> changes the text of the button to
- *          <code>null</code> and any changes to <code>NAME</code>
- *          are ignored.  <code>hideActionText</code> is useful for
- *          tool bar buttons that typically only show an <code>Icon</code>.
- *          <code>JToolBar.add(Action)</code> sets the property to
- *          <code>true</code> if the <code>Action</code> has a
- *          non-<code>null</code> value for <code>LARGE_ICON_KEY</code> or
- *          <code>SMALL_ICON</code>.
+ *          of the {@code Action}, set the property
+ *          {@code hideActionText} to {@code true}.  If
+ *          {@code hideActionText} is {@code true}, setting the
+ *          {@code Action} changes the text of the button to
+ *          {@code null} and any changes to {@code NAME}
+ *          are ignored.  {@code hideActionText} is useful for
+ *          tool bar buttons that typically only show an {@code Icon}.
+ *          {@code JToolBar.add(Action)} sets the property to
+ *          {@code true} if the {@code Action} has a
+ *          non-{@code null} value for {@code LARGE_ICON_KEY} or
+ *          {@code SMALL_ICON}.
  *  <tr valign="top"  align="left">
- *      <td><b><code>displayedMnemonicIndex</code></b>
+ *      <td><b>{@code displayedMnemonicIndex}</b>
  *      <td>All buttons
- *      <td><code>DISPLAYED_MNEMONIC_INDEX_KEY</code>
- *      <td>If the value of <code>DISPLAYED_MNEMONIC_INDEX_KEY</code> is
+ *      <td>{@code DISPLAYED_MNEMONIC_INDEX_KEY}
+ *      <td>If the value of {@code DISPLAYED_MNEMONIC_INDEX_KEY} is
  *          beyond the bounds of the text, it is ignored.  When
- *          <code>setAction</code> is called, if the value from the
- *          <code>Action</code> is <code>null</code>, the displayed
+ *          {@code setAction} is called, if the value from the
+ *          {@code Action} is {@code null}, the displayed
  *          mnemonic index is not updated.  In any subsequent changes to
- *          <code>DISPLAYED_MNEMONIC_INDEX_KEY</code>, <code>null</code>
+ *          {@code DISPLAYED_MNEMONIC_INDEX_KEY}, {@code null}
  *          is treated as -1.
  *  <tr valign="top"  align="left">
- *      <td><b><code>icon</code></b>
- *      <td>All buttons except of <code>JCheckBox</code>,
- *      <code>JToggleButton</code> and <code>JRadioButton</code>.
- *      <td>either <code>LARGE_ICON_KEY</code> or
- *          <code>SMALL_ICON</code>
- *     <td>The <code>JMenuItem</code> subclasses only use
- *         <code>SMALL_ICON</code>.  All other buttons will use
- *         <code>LARGE_ICON_KEY</code>; if the value is <code>null</code> they
- *         use <code>SMALL_ICON</code>.
+ *      <td><b>{@code icon}</b>
+ *      <td>All buttons except of {@code JCheckBox},
+ *      {@code JToggleButton} and {@code JRadioButton}.
+ *      <td>either {@code LARGE_ICON_KEY} or
+ *          {@code SMALL_ICON}
+ *     <td>The {@code JMenuItem} subclasses only use
+ *         {@code SMALL_ICON}.  All other buttons will use
+ *         {@code LARGE_ICON_KEY}; if the value is {@code null} they
+ *         use {@code SMALL_ICON}.
  *  <tr valign="top"  align="left">
- *      <td><b><code>accelerator</code></b>
- *      <td>All <code>JMenuItem</code> subclasses, with the exception of
- *          <code>JMenu</code>.
- *      <td><code>ACCELERATOR_KEY</code>
+ *      <td><b>{@code accelerator}</b>
+ *      <td>All {@code JMenuItem} subclasses, with the exception of
+ *          {@code JMenu}.
+ *      <td>{@code ACCELERATOR_KEY}
  *      <td>&nbsp;
  *  <tr valign="top"  align="left">
- *      <td><b><code>selected</code></b>
- *      <td><code>JToggleButton</code>, <code>JCheckBox</code>,
- *          <code>JRadioButton</code>, <code>JCheckBoxMenuItem</code> and
- *          <code>JRadioButtonMenuItem</code>
- *      <td><code>SELECTED_KEY</code>
+ *      <td><b>{@code selected}</b>
+ *      <td>{@code JToggleButton}, {@code JCheckBox},
+ *          {@code JRadioButton}, {@code JCheckBoxMenuItem} and
+ *          {@code JRadioButtonMenuItem}
+ *      <td>{@code SELECTED_KEY}
  *      <td>Components that honor this property only use
  *          the value if it is {@code non-null}. For example, if
  *          you set an {@code Action} that has a {@code null}
  *          value for {@code SELECTED_KEY} on a {@code JToggleButton}, the
  *          {@code JToggleButton} will not update it's selected state in

@@ -191,24 +191,24 @@
  *          use the same {@code Action} that defines a value for the
  *          {@code SELECTED_KEY} property with multiple mutually
  *          exclusive buttons.
  * </table>
  * <p>
- * <code>JPopupMenu</code>, <code>JToolBar</code> and <code>JMenu</code>
+ * {@code JPopupMenu}, {@code JToolBar} and {@code JMenu}
  * all provide convenience methods for creating a component and setting the
- * <code>Action</code> on the corresponding component.  Refer to each of
+ * {@code Action} on the corresponding component.  Refer to each of
  * these classes for more information.
  * <p>
- * <code>Action</code> uses <code>PropertyChangeListener</code> to
- * inform listeners the <code>Action</code> has changed.  The beans
- * specification indicates that a <code>null</code> property name can
+ * {@code Action} uses {@code PropertyChangeListener} to
+ * inform listeners the {@code Action} has changed.  The beans
+ * specification indicates that a {@code null} property name can
  * be used to indicate multiple values have changed.  By default Swing
- * components that take an <code>Action</code> do not handle such a
- * change.  To indicate that Swing should treat <code>null</code>
+ * components that take an {@code Action} do not handle such a
+ * change.  To indicate that Swing should treat {@code null}
  * according to the beans specification set the system property
- * <code>swing.actions.reconfigureOnNull</code> to the <code>String</code>
- * value <code>true</code>.
+ * {@code swing.actions.reconfigureOnNull} to the {@code String}
+ * value {@code true}.
  *
  * @author Georges Saab
  * @see AbstractAction
  * @since 1.2
  */

@@ -221,117 +221,117 @@
     /**
      * Not currently used.
      */
     public static final String DEFAULT = "Default";
     /**
-     * The key used for storing the <code>String</code> name
+     * The key used for storing the {@code String} name
      * for the action, used for a menu or button.
      */
     public static final String NAME = "Name";
     /**
-     * The key used for storing a short <code>String</code>
+     * The key used for storing a short {@code String}
      * description for the action, used for tooltip text.
      */
     public static final String SHORT_DESCRIPTION = "ShortDescription";
     /**
-     * The key used for storing a longer <code>String</code>
+     * The key used for storing a longer {@code String}
      * description for the action, could be used for context-sensitive help.
      */
     public static final String LONG_DESCRIPTION = "LongDescription";
     /**
-     * The key used for storing a small <code>Icon</code>, such
-     * as <code>ImageIcon</code>.  This is typically used with
-     * menus such as <code>JMenuItem</code>.
-     * <p>
-     * If the same <code>Action</code> is used with menus and buttons you'll
-     * typically specify both a <code>SMALL_ICON</code> and a
-     * <code>LARGE_ICON_KEY</code>.  The menu will use the
-     * <code>SMALL_ICON</code> and the button will use the
-     * <code>LARGE_ICON_KEY</code>.
+     * The key used for storing a small {@code Icon}, such
+     * as {@code ImageIcon}.  This is typically used with
+     * menus such as {@code JMenuItem}.
+     * <p>
+     * If the same {@code Action} is used with menus and buttons you'll
+     * typically specify both a {@code SMALL_ICON} and a
+     * {@code LARGE_ICON_KEY}.  The menu will use the
+     * {@code SMALL_ICON} and the button will use the
+     * {@code LARGE_ICON_KEY}.
      */
     public static final String SMALL_ICON = "SmallIcon";
 
     /**
-     * The key used to determine the command <code>String</code> for the
-     * <code>ActionEvent</code> that will be created when an
-     * <code>Action</code> is going to be notified as the result of
-     * residing in a <code>Keymap</code> associated with a
-     * <code>JComponent</code>.
+     * The key used to determine the command {@code String} for the
+     * {@code ActionEvent} that will be created when an
+     * {@code Action} is going to be notified as the result of
+     * residing in a {@code Keymap} associated with a
+     * {@code JComponent}.
      */
     public static final String ACTION_COMMAND_KEY = "ActionCommandKey";
 
     /**
-     * The key used for storing a <code>KeyStroke</code> to be used as the
+     * The key used for storing a {@code KeyStroke} to be used as the
      * accelerator for the action.
      *
      * @since 1.3
      */
     public static final String ACCELERATOR_KEY="AcceleratorKey";
 
     /**
-     * The key used for storing an <code>Integer</code> that corresponds to
-     * one of the <code>KeyEvent</code> key codes.  The value is
+     * The key used for storing an {@code Integer} that corresponds to
+     * one of the {@code KeyEvent} key codes.  The value is
      * commonly used to specify a mnemonic.  For example:
-     * <code>myAction.putValue(Action.MNEMONIC_KEY, KeyEvent.VK_A)</code>
-     * sets the mnemonic of <code>myAction</code> to 'a', while
+     * {@code myAction.putValue(Action.MNEMONIC_KEY, KeyEvent.VK_A)}
+     * sets the mnemonic of {@code myAction} to 'a', while
      * <code>myAction.putValue(Action.MNEMONIC_KEY, KeyEvent.getExtendedKeyCodeForChar('\u0444'))</code>
-     * sets the mnemonic of <code>myAction</code> to Cyrillic letter "Ef".
+     * sets the mnemonic of {@code myAction} to Cyrillic letter "Ef".
      *
      * @since 1.3
      */
     public static final String MNEMONIC_KEY="MnemonicKey";
 
     /**
-     * The key used for storing a <code>Boolean</code> that corresponds
+     * The key used for storing a {@code Boolean} that corresponds
      * to the selected state.  This is typically used only for components
      * that have a meaningful selection state.  For example,
-     * <code>JRadioButton</code> and <code>JCheckBox</code> make use of
-     * this but instances of <code>JMenu</code> don't.
+     * {@code JRadioButton} and {@code JCheckBox} make use of
+     * this but instances of {@code JMenu} don't.
      * <p>
      * This property differs from the others in that it is both read
      * by the component and set by the component.  For example,
-     * if an <code>Action</code> is attached to a <code>JCheckBox</code>
-     * the selected state of the <code>JCheckBox</code> will be set from
-     * that of the <code>Action</code>.  If the user clicks on the
-     * <code>JCheckBox</code> the selected state of the <code>JCheckBox</code>
-     * <b>and</b> the <code>Action</code> will <b>both</b> be updated.
+     * if an {@code Action} is attached to a {@code JCheckBox}
+     * the selected state of the {@code JCheckBox} will be set from
+     * that of the {@code Action}.  If the user clicks on the
+     * {@code JCheckBox} the selected state of the {@code JCheckBox}
+     * <b>and</b> the {@code Action} will <b>both</b> be updated.
      * <p>
      * Note: the value of this field is prefixed with 'Swing' to
-     * avoid possible collisions with existing <code>Actions</code>.
+     * avoid possible collisions with existing {@code Actions}.
      *
      * @since 1.6
      */
     public static final String SELECTED_KEY = "SwingSelectedKey";
 
     /**
-     * The key used for storing an <code>Integer</code> that corresponds
-     * to the index in the text (identified by the <code>NAME</code>
+     * The key used for storing an {@code Integer} that corresponds
+     * to the index in the text (identified by the {@code NAME}
      * property) that the decoration for a mnemonic should be rendered at.  If
      * the value of this property is greater than or equal to the length of
      * the text, it will treated as -1.
      * <p>
      * Note: the value of this field is prefixed with 'Swing' to
-     * avoid possible collisions with existing <code>Actions</code>.
+     * avoid possible collisions with existing {@code Actions}.
      *
      * @see AbstractButton#setDisplayedMnemonicIndex
      * @since 1.6
      */
     public static final String DISPLAYED_MNEMONIC_INDEX_KEY =
                                  "SwingDisplayedMnemonicIndexKey";
 
     /**
-     * The key used for storing an <code>Icon</code>.  This is typically
-     * used by buttons, such as <code>JButton</code> and
-     * <code>JToggleButton</code>.
-     * <p>
-     * If the same <code>Action</code> is used with menus and buttons you'll
-     * typically specify both a <code>SMALL_ICON</code> and a
-     * <code>LARGE_ICON_KEY</code>.  The menu will use the
-     * <code>SMALL_ICON</code> and the button the <code>LARGE_ICON_KEY</code>.
+     * The key used for storing an {@code Icon}.  This is typically
+     * used by buttons, such as {@code JButton} and
+     * {@code JToggleButton}.
+     * <p>
+     * If the same {@code Action} is used with menus and buttons you'll
+     * typically specify both a {@code SMALL_ICON} and a
+     * {@code LARGE_ICON_KEY}.  The menu will use the
+     * {@code SMALL_ICON} and the button the {@code LARGE_ICON_KEY}.
      * <p>
      * Note: the value of this field is prefixed with 'Swing' to
-     * avoid possible collisions with existing <code>Actions</code>.
+     * avoid possible collisions with existing {@code Actions}.
      *
      * @since 1.6
      */
     public static final String LARGE_ICON_KEY = "SwingLargeIconKey";
 

@@ -345,50 +345,50 @@
      */
     public Object getValue(String key);
     /**
      * Sets one of this object's properties
      * using the associated key. If the value has
-     * changed, a <code>PropertyChangeEvent</code> is sent
+     * changed, a {@code PropertyChangeEvent} is sent
      * to listeners.
      *
-     * @param key    a <code>String</code> containing the key
-     * @param value  an <code>Object</code> value
+     * @param key    a {@code String} containing the key
+     * @param value  an {@code Object} value
      */
     public void putValue(String key, Object value);
 
     /**
-     * Sets the enabled state of the <code>Action</code>.  When enabled,
+     * Sets the enabled state of the {@code Action}.  When enabled,
      * any component associated with this object is active and
-     * able to fire this object's <code>actionPerformed</code> method.
-     * If the value has changed, a <code>PropertyChangeEvent</code> is sent
+     * able to fire this object's {@code actionPerformed} method.
+     * If the value has changed, a {@code PropertyChangeEvent} is sent
      * to listeners.
      *
-     * @param  b true to enable this <code>Action</code>, false to disable it
+     * @param  b true to enable this {@code Action}, false to disable it
      */
     public void setEnabled(boolean b);
     /**
-     * Returns the enabled state of the <code>Action</code>. When enabled,
+     * Returns the enabled state of the {@code Action}. When enabled,
      * any component associated with this object is active and
-     * able to fire this object's <code>actionPerformed</code> method.
+     * able to fire this object's {@code actionPerformed} method.
      *
-     * @return true if this <code>Action</code> is enabled
+     * @return true if this {@code Action} is enabled
      */
     public boolean isEnabled();
 
     /**
-     * Adds a <code>PropertyChange</code> listener. Containers and attached
+     * Adds a {@code PropertyChange} listener. Containers and attached
      * components use these methods to register interest in this
-     * <code>Action</code> object. When its enabled state or other property
+     * {@code Action} object. When its enabled state or other property
      * changes, the registered listeners are informed of the change.
      *
-     * @param listener  a <code>PropertyChangeListener</code> object
+     * @param listener  a {@code PropertyChangeListener} object
      */
     public void addPropertyChangeListener(PropertyChangeListener listener);
     /**
-     * Removes a <code>PropertyChange</code> listener.
+     * Removes a {@code PropertyChange} listener.
      *
-     * @param listener  a <code>PropertyChangeListener</code> object
+     * @param listener  a {@code PropertyChangeListener} object
      * @see #addPropertyChangeListener
      */
     public void removePropertyChangeListener(PropertyChangeListener listener);
 
 }
< prev index next >