1 /*
   2  * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 package javax.swing;
  26 
  27 import java.awt.*;
  28 import java.awt.event.*;
  29 import java.beans.*;
  30 
  31 /**
  32  * The {@code Action} interface provides a useful extension to the
  33  * {@code ActionListener}
  34  * interface in cases where the same functionality may be accessed by
  35  * several controls.
  36  * <p>
  37  * In addition to the {@code actionPerformed} method defined by the
  38  * {@code ActionListener} interface, this interface allows the
  39  * application to define, in a single place:
  40  * <ul>
  41  * <li>One or more text strings that describe the function. These strings
  42  *     can be used, for example, to display the flyover text for a button
  43  *     or to set the text in a menu item.
  44  * <li>One or more icons that depict the function. These icons can be used
  45  *     for the images in a menu control, or for composite entries in a more
  46  *     sophisticated user interface.
  47  * <li>The enabled/disabled state of the functionality. Instead of having
  48  *     to separately disable the menu item and the toolbar button, the
  49  *     application can disable the function that implements this interface.
  50  *     All components which are registered as listeners for the state change
  51  *     then know to disable event generation for that item and to modify the
  52  *     display accordingly.
  53  * </ul>
  54  * <p>
  55  * This interface can be added to an existing class or used to create an
  56  * adapter (typically, by subclassing {@code AbstractAction}).
  57  * The {@code Action} object
  58  * can then be added to multiple {@code Action}-aware containers
  59  * and connected to {@code Action}-capable
  60  * components. The GUI controls can then be activated or
  61  * deactivated all at once by invoking the {@code Action} object's
  62  * {@code setEnabled} method.
  63  * <p>
  64  * Note that {@code Action} implementations tend to be more expensive
  65  * in terms of storage than a typical {@code ActionListener},
  66  * which does not offer the benefits of centralized control of
  67  * functionality and broadcast of property changes.  For this reason,
  68  * you should take care to only use {@code Action}s where their benefits
  69  * are desired, and use simple {@code ActionListener}s elsewhere.
  70  * <br>
  71  *
  72  * <h3><a name="buttonActions"></a>Swing Components Supporting {@code Action}</h3>
  73  * <p>
  74  * Many of Swing's components have an {@code Action} property.  When
  75  * an {@code Action} is set on a component, the following things
  76  * happen:
  77  * <ul>
  78  * <li>The {@code Action} is added as an {@code ActionListener} to
  79  *     the component.
  80  * <li>The component configures some of its properties to match the
  81  *      {@code Action}.
  82  * <li>The component installs a {@code PropertyChangeListener} on the
  83  *     {@code Action} so that the component can change its properties
  84  *     to reflect changes in the {@code Action}'s properties.
  85  * </ul>
  86  * <p>
  87  * The following table describes the properties used by
  88  * {@code Swing} components that support {@code Actions}.
  89  * In the table, <em>button</em> refers to any
  90  * {@code AbstractButton} subclass, which includes not only
  91  * {@code JButton} but also classes such as
  92  * {@code JMenuItem}. Unless otherwise stated, a
  93  * {@code null} property value in an {@code Action} (or a
  94  * {@code Action} that is {@code null}) results in the
  95  * button's corresponding property being set to {@code null}.
  96  *
  97  * <table border="1" cellpadding="1" cellspacing="0"
  98  *         summary="Supported Action properties">
  99  *  <tr valign="top"  align="left">
 100  *    <th style="background-color:#CCCCFF" align="left">Component Property
 101  *    <th style="background-color:#CCCCFF" align="left">Components
 102  *    <th style="background-color:#CCCCFF" align="left">Action Key
 103  *    <th style="background-color:#CCCCFF" align="left">Notes
 104  *  <tr valign="top"  align="left">
 105  *      <td><b>{@code enabled}</b>
 106  *      <td>All
 107  *      <td>The {@code isEnabled} method
 108  *      <td>&nbsp;
 109  *  <tr valign="top"  align="left">
 110  *      <td><b>{@code toolTipText}</b>
 111  *      <td>All
 112  *      <td>{@code SHORT_DESCRIPTION}
 113  *      <td>&nbsp;
 114  *  <tr valign="top"  align="left">
 115  *      <td><b>{@code actionCommand}</b>
 116  *      <td>All
 117  *      <td>{@code ACTION_COMMAND_KEY}
 118  *      <td>&nbsp;
 119  *  <tr valign="top"  align="left">
 120  *      <td><b>{@code mnemonic}</b>
 121  *      <td>All buttons
 122  *      <td>{@code MNEMONIC_KEY}
 123  *      <td>A {@code null} value or {@code Action} results in the
 124  *          button's {@code mnemonic} property being set to
 125  *          {@code '\0'}.
 126  *  <tr valign="top"  align="left">
 127  *      <td><b>{@code text}</b>
 128  *      <td>All buttons
 129  *      <td>{@code NAME}
 130  *      <td>If you do not want the text of the button to mirror that
 131  *          of the {@code Action}, set the property
 132  *          {@code hideActionText} to {@code true}.  If
 133  *          {@code hideActionText} is {@code true}, setting the
 134  *          {@code Action} changes the text of the button to
 135  *          {@code null} and any changes to {@code NAME}
 136  *          are ignored.  {@code hideActionText} is useful for
 137  *          tool bar buttons that typically only show an {@code Icon}.
 138  *          {@code JToolBar.add(Action)} sets the property to
 139  *          {@code true} if the {@code Action} has a
 140  *          non-{@code null} value for {@code LARGE_ICON_KEY} or
 141  *          {@code SMALL_ICON}.
 142  *  <tr valign="top"  align="left">
 143  *      <td><b>{@code displayedMnemonicIndex}</b>
 144  *      <td>All buttons
 145  *      <td>{@code DISPLAYED_MNEMONIC_INDEX_KEY}
 146  *      <td>If the value of {@code DISPLAYED_MNEMONIC_INDEX_KEY} is
 147  *          beyond the bounds of the text, it is ignored.  When
 148  *          {@code setAction} is called, if the value from the
 149  *          {@code Action} is {@code null}, the displayed
 150  *          mnemonic index is not updated.  In any subsequent changes to
 151  *          {@code DISPLAYED_MNEMONIC_INDEX_KEY}, {@code null}
 152  *          is treated as -1.
 153  *  <tr valign="top"  align="left">
 154  *      <td><b>{@code icon}</b>
 155  *      <td>All buttons except of {@code JCheckBox},
 156  *      {@code JToggleButton} and {@code JRadioButton}.
 157  *      <td>either {@code LARGE_ICON_KEY} or
 158  *          {@code SMALL_ICON}
 159  *     <td>The {@code JMenuItem} subclasses only use
 160  *         {@code SMALL_ICON}.  All other buttons will use
 161  *         {@code LARGE_ICON_KEY}; if the value is {@code null} they
 162  *         use {@code SMALL_ICON}.
 163  *  <tr valign="top"  align="left">
 164  *      <td><b>{@code accelerator}</b>
 165  *      <td>All {@code JMenuItem} subclasses, with the exception of
 166  *          {@code JMenu}.
 167  *      <td>{@code ACCELERATOR_KEY}
 168  *      <td>&nbsp;
 169  *  <tr valign="top"  align="left">
 170  *      <td><b>{@code selected}</b>
 171  *      <td>{@code JToggleButton}, {@code JCheckBox},
 172  *          {@code JRadioButton}, {@code JCheckBoxMenuItem} and
 173  *          {@code JRadioButtonMenuItem}
 174  *      <td>{@code SELECTED_KEY}
 175  *      <td>Components that honor this property only use
 176  *          the value if it is {@code non-null}. For example, if
 177  *          you set an {@code Action} that has a {@code null}
 178  *          value for {@code SELECTED_KEY} on a {@code JToggleButton}, the
 179  *          {@code JToggleButton} will not update it's selected state in
 180  *          any way. Similarly, any time the {@code JToggleButton}'s
 181  *          selected state changes it will only set the value back on
 182  *          the {@code Action} if the {@code Action} has a {@code non-null}
 183  *          value for {@code SELECTED_KEY}.
 184  *          <br>
 185  *          Components that honor this property keep their selected state
 186  *          in sync with this property. When the same {@code Action} is used
 187  *          with multiple components, all the components keep their selected
 188  *          state in sync with this property. Mutually exclusive
 189  *          buttons, such as {@code JToggleButton}s in a {@code ButtonGroup},
 190  *          force only one of the buttons to be selected. As such, do not
 191  *          use the same {@code Action} that defines a value for the
 192  *          {@code SELECTED_KEY} property with multiple mutually
 193  *          exclusive buttons.
 194  * </table>
 195  * <p>
 196  * {@code JPopupMenu}, {@code JToolBar} and {@code JMenu}
 197  * all provide convenience methods for creating a component and setting the
 198  * {@code Action} on the corresponding component.  Refer to each of
 199  * these classes for more information.
 200  * <p>
 201  * {@code Action} uses {@code PropertyChangeListener} to
 202  * inform listeners the {@code Action} has changed.  The beans
 203  * specification indicates that a {@code null} property name can
 204  * be used to indicate multiple values have changed.  By default Swing
 205  * components that take an {@code Action} do not handle such a
 206  * change.  To indicate that Swing should treat {@code null}
 207  * according to the beans specification set the system property
 208  * {@code swing.actions.reconfigureOnNull} to the {@code String}
 209  * value {@code true}.
 210  *
 211  * @author Georges Saab
 212  * @see AbstractAction
 213  * @since 1.2
 214  */
 215 public interface Action extends ActionListener {
 216     /**
 217      * Useful constants that can be used as the storage-retrieval key
 218      * when setting or getting one of this object's properties (text
 219      * or icon).
 220      */
 221     /**
 222      * Not currently used.
 223      */
 224     public static final String DEFAULT = "Default";
 225     /**
 226      * The key used for storing the {@code String} name
 227      * for the action, used for a menu or button.
 228      */
 229     public static final String NAME = "Name";
 230     /**
 231      * The key used for storing a short {@code String}
 232      * description for the action, used for tooltip text.
 233      */
 234     public static final String SHORT_DESCRIPTION = "ShortDescription";
 235     /**
 236      * The key used for storing a longer {@code String}
 237      * description for the action, could be used for context-sensitive help.
 238      */
 239     public static final String LONG_DESCRIPTION = "LongDescription";
 240     /**
 241      * The key used for storing a small {@code Icon}, such
 242      * as {@code ImageIcon}.  This is typically used with
 243      * menus such as {@code JMenuItem}.
 244      * <p>
 245      * If the same {@code Action} is used with menus and buttons you'll
 246      * typically specify both a {@code SMALL_ICON} and a
 247      * {@code LARGE_ICON_KEY}.  The menu will use the
 248      * {@code SMALL_ICON} and the button will use the
 249      * {@code LARGE_ICON_KEY}.
 250      */
 251     public static final String SMALL_ICON = "SmallIcon";
 252 
 253     /**
 254      * The key used to determine the command {@code String} for the
 255      * {@code ActionEvent} that will be created when an
 256      * {@code Action} is going to be notified as the result of
 257      * residing in a {@code Keymap} associated with a
 258      * {@code JComponent}.
 259      */
 260     public static final String ACTION_COMMAND_KEY = "ActionCommandKey";
 261 
 262     /**
 263      * The key used for storing a {@code KeyStroke} to be used as the
 264      * accelerator for the action.
 265      *
 266      * @since 1.3
 267      */
 268     public static final String ACCELERATOR_KEY="AcceleratorKey";
 269 
 270     /**
 271      * The key used for storing an {@code Integer} that corresponds to
 272      * one of the {@code KeyEvent} key codes.  The value is
 273      * commonly used to specify a mnemonic.  For example:
 274      * {@code myAction.putValue(Action.MNEMONIC_KEY, KeyEvent.VK_A)}
 275      * sets the mnemonic of {@code myAction} to 'a', while
 276      * <code>myAction.putValue(Action.MNEMONIC_KEY, KeyEvent.getExtendedKeyCodeForChar('\u0444'))</code>
 277      * sets the mnemonic of {@code myAction} to Cyrillic letter "Ef".
 278      *
 279      * @since 1.3
 280      */
 281     public static final String MNEMONIC_KEY="MnemonicKey";
 282 
 283     /**
 284      * The key used for storing a {@code Boolean} that corresponds
 285      * to the selected state.  This is typically used only for components
 286      * that have a meaningful selection state.  For example,
 287      * {@code JRadioButton} and {@code JCheckBox} make use of
 288      * this but instances of {@code JMenu} don't.
 289      * <p>
 290      * This property differs from the others in that it is both read
 291      * by the component and set by the component.  For example,
 292      * if an {@code Action} is attached to a {@code JCheckBox}
 293      * the selected state of the {@code JCheckBox} will be set from
 294      * that of the {@code Action}.  If the user clicks on the
 295      * {@code JCheckBox} the selected state of the {@code JCheckBox}
 296      * <b>and</b> the {@code Action} will <b>both</b> be updated.
 297      * <p>
 298      * Note: the value of this field is prefixed with 'Swing' to
 299      * avoid possible collisions with existing {@code Actions}.
 300      *
 301      * @since 1.6
 302      */
 303     public static final String SELECTED_KEY = "SwingSelectedKey";
 304 
 305     /**
 306      * The key used for storing an {@code Integer} that corresponds
 307      * to the index in the text (identified by the {@code NAME}
 308      * property) that the decoration for a mnemonic should be rendered at.  If
 309      * the value of this property is greater than or equal to the length of
 310      * the text, it will treated as -1.
 311      * <p>
 312      * Note: the value of this field is prefixed with 'Swing' to
 313      * avoid possible collisions with existing {@code Actions}.
 314      *
 315      * @see AbstractButton#setDisplayedMnemonicIndex
 316      * @since 1.6
 317      */
 318     public static final String DISPLAYED_MNEMONIC_INDEX_KEY =
 319                                  "SwingDisplayedMnemonicIndexKey";
 320 
 321     /**
 322      * The key used for storing an {@code Icon}.  This is typically
 323      * used by buttons, such as {@code JButton} and
 324      * {@code JToggleButton}.
 325      * <p>
 326      * If the same {@code Action} is used with menus and buttons you'll
 327      * typically specify both a {@code SMALL_ICON} and a
 328      * {@code LARGE_ICON_KEY}.  The menu will use the
 329      * {@code SMALL_ICON} and the button the {@code LARGE_ICON_KEY}.
 330      * <p>
 331      * Note: the value of this field is prefixed with 'Swing' to
 332      * avoid possible collisions with existing {@code Actions}.
 333      *
 334      * @since 1.6
 335      */
 336     public static final String LARGE_ICON_KEY = "SwingLargeIconKey";
 337 
 338     /**
 339      * Gets one of this object's properties
 340      * using the associated key.
 341      *
 342      * @param key a {@code String} containing the key
 343      * @return the {@code Object} value
 344      * @see #putValue
 345      */
 346     public Object getValue(String key);
 347     /**
 348      * Sets one of this object's properties
 349      * using the associated key. If the value has
 350      * changed, a {@code PropertyChangeEvent} is sent
 351      * to listeners.
 352      *
 353      * @param key    a {@code String} containing the key
 354      * @param value  an {@code Object} value
 355      */
 356     public void putValue(String key, Object value);
 357 
 358     /**
 359      * Sets the enabled state of the {@code Action}.  When enabled,
 360      * any component associated with this object is active and
 361      * able to fire this object's {@code actionPerformed} method.
 362      * If the value has changed, a {@code PropertyChangeEvent} is sent
 363      * to listeners.
 364      *
 365      * @param  b true to enable this {@code Action}, false to disable it
 366      */
 367     public void setEnabled(boolean b);
 368     /**
 369      * Returns the enabled state of the {@code Action}. When enabled,
 370      * any component associated with this object is active and
 371      * able to fire this object's {@code actionPerformed} method.
 372      *
 373      * @return true if this {@code Action} is enabled
 374      */
 375     public boolean isEnabled();
 376 
 377     /**
 378      * Adds a {@code PropertyChange} listener. Containers and attached
 379      * components use these methods to register interest in this
 380      * {@code Action} object. When its enabled state or other property
 381      * changes, the registered listeners are informed of the change.
 382      *
 383      * @param listener  a {@code PropertyChangeListener} object
 384      */
 385     public void addPropertyChangeListener(PropertyChangeListener listener);
 386     /**
 387      * Removes a {@code PropertyChange} listener.
 388      *
 389      * @param listener  a {@code PropertyChangeListener} object
 390      * @see #addPropertyChangeListener
 391      */
 392     public void removePropertyChangeListener(PropertyChangeListener listener);
 393 
 394 }