/* * Copyright (c) 1997, 2009, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package javax.swing; import java.awt.*; import java.awt.event.*; import java.beans.*; /** * The Action interface provides a useful extension to the * ActionListener * interface in cases where the same functionality may be accessed by * several controls. *

* In addition to the actionPerformed method defined by the * ActionListener interface, this interface allows the * application to define, in a single place: *

*

* This interface can be added to an existing class or used to create an * adapter (typically, by subclassing AbstractAction). * The Action object * can then be added to multiple Action-aware containers * and connected to Action-capable * components. The GUI controls can then be activated or * deactivated all at once by invoking the Action object's * setEnabled method. *

* Note that Action implementations tend to be more expensive * in terms of storage than a typical 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 Actions where their benefits * are desired, and use simple ActionListeners elsewhere. *

* *

Swing Components Supporting Action

*

* Many of Swing's components have an Action property. When * an Action is set on a component, the following things * happen: *

*

* The following table describes the properties used by * Swing components that support Actions. * In the table, button refers to any * AbstractButton subclass, which includes not only * JButton but also classes such as * JMenuItem. Unless otherwise stated, a * null property value in an Action (or a * Action that is null) results in the * button's corresponding property being set to null. *

* * * * * * * * * * * *
Component Property * Components * Action Key * Notes *
enabled * All * The isEnabled method *   *
toolTipText * All * SHORT_DESCRIPTION *   *
actionCommand * All * ACTION_COMMAND_KEY *   *
mnemonic * All buttons * MNEMONIC_KEY * A null value or Action results in the * button's mnemonic property being set to * '\0'. *
text * All buttons * NAME * If you do not want the text of the button to mirror that * of the Action, set the property * hideActionText to true. If * hideActionText is true, setting the * Action changes the text of the button to * null and any changes to NAME * are ignored. hideActionText is useful for * tool bar buttons that typically only show an Icon. * JToolBar.add(Action) sets the property to * true if the Action has a * non-null value for LARGE_ICON_KEY or * SMALL_ICON. *
displayedMnemonicIndex * All buttons * DISPLAYED_MNEMONIC_INDEX_KEY * If the value of DISPLAYED_MNEMONIC_INDEX_KEY is * beyond the bounds of the text, it is ignored. When * setAction is called, if the value from the * Action is null, the displayed * mnemonic index is not updated. In any subsequent changes to * DISPLAYED_MNEMONIC_INDEX_KEY, null * is treated as -1. *
icon * All buttons except of JCheckBox, * JToggleButton and JRadioButton. * either LARGE_ICON_KEY or * SMALL_ICON * The JMenuItem subclasses only use * SMALL_ICON. All other buttons will use * LARGE_ICON_KEY; if the value is null they * use SMALL_ICON. *
accelerator * All JMenuItem subclasses, with the exception of * JMenu. * ACCELERATOR_KEY *   *
selected * JToggleButton, JCheckBox, * JRadioButton, JCheckBoxMenuItem and * JRadioButtonMenuItem * SELECTED_KEY * 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 * any way. Similarly, any time the {@code JToggleButton}'s * selected state changes it will only set the value back on * the {@code Action} if the {@code Action} has a {@code non-null} * value for {@code SELECTED_KEY}. *
* Components that honor this property keep their selected state * in sync with this property. When the same {@code Action} is used * with multiple components, all the components keep their selected * state in sync with this property. Mutually exclusive * buttons, such as {@code JToggleButton}s in a {@code ButtonGroup}, * force only one of the buttons to be selected. As such, do not * use the same {@code Action} that defines a value for the * {@code SELECTED_KEY} property with multiple mutually * exclusive buttons. *
*

* JPopupMenu, JToolBar and JMenu * all provide convenience methods for creating a component and setting the * Action on the corresponding component. Refer to each of * these classes for more information. *

* Action uses PropertyChangeListener to * inform listeners the Action has changed. The beans * specification indicates that a null property name can * be used to indicate multiple values have changed. By default Swing * components that take an Action do not handle such a * change. To indicate that Swing should treat null * according to the beans specification set the system property * swing.actions.reconfigureOnNull to the String * value true. * * @author Georges Saab * @see AbstractAction */ public interface Action extends ActionListener { /** * Useful constants that can be used as the storage-retrieval key * when setting or getting one of this object's properties (text * or icon). */ /** * Not currently used. */ public static final String DEFAULT = "Default"; /** * The key used for storing the String name * for the action, used for a menu or button. */ public static final String NAME = "Name"; /** * The key used for storing a short String * description for the action, used for tooltip text. */ public static final String SHORT_DESCRIPTION = "ShortDescription"; /** * The key used for storing a longer 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 Icon, such * as ImageIcon. This is typically used with * menus such as JMenuItem. *

* If the same Action is used with menus and buttons you'll * typically specify both a SMALL_ICON and a * LARGE_ICON_KEY. The menu will use the * SMALL_ICON and the button will use the * LARGE_ICON_KEY. */ public static final String SMALL_ICON = "SmallIcon"; /** * The key used to determine the command String for the * ActionEvent that will be created when an * Action is going to be notified as the result of * residing in a Keymap associated with a * JComponent. */ public static final String ACTION_COMMAND_KEY = "ActionCommandKey"; /** * The key used for storing a 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 Integer that corresponds to * one of the KeyEvent key codes. The value is * commonly used to specify a mnemonic. For example: * myAction.putValue(Action.MNEMONIC_KEY, KeyEvent.VK_A) * sets the mnemonic of myAction to 'a', while * myAction.putValue(Action.MNEMONIC_KEY, KeyEvent.getExtendedKeyCodeForChar('\u0444')) * sets the mnemonic of myAction to Cyrillic letter "Ef". * * @since 1.3 */ public static final String MNEMONIC_KEY="MnemonicKey"; /** * The key used for storing a Boolean that corresponds * to the selected state. This is typically used only for components * that have a meaningful selection state. For example, * JRadioButton and JCheckBox make use of * this but instances of JMenu don't. *

* This property differs from the others in that it is both read * by the component and set by the component. For example, * if an Action is attached to a JCheckBox * the selected state of the JCheckBox will be set from * that of the Action. If the user clicks on the * JCheckBox the selected state of the JCheckBox * and the Action will both be updated. *

* Note: the value of this field is prefixed with 'Swing' to * avoid possible collisions with existing Actions. * * @since 1.6 */ public static final String SELECTED_KEY = "SwingSelectedKey"; /** * The key used for storing an Integer that corresponds * to the index in the text (identified by the 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. *

* Note: the value of this field is prefixed with 'Swing' to * avoid possible collisions with existing Actions. * * @see AbstractButton#setDisplayedMnemonicIndex * @since 1.6 */ public static final String DISPLAYED_MNEMONIC_INDEX_KEY = "SwingDisplayedMnemonicIndexKey"; /** * The key used for storing an Icon. This is typically * used by buttons, such as JButton and * JToggleButton. *

* If the same Action is used with menus and buttons you'll * typically specify both a SMALL_ICON and a * LARGE_ICON_KEY. The menu will use the * SMALL_ICON and the button the LARGE_ICON_KEY. *

* Note: the value of this field is prefixed with 'Swing' to * avoid possible collisions with existing Actions. * * @since 1.6 */ public static final String LARGE_ICON_KEY = "SwingLargeIconKey"; /** * Gets one of this object's properties * using the associated key. * @see #putValue */ public Object getValue(String key); /** * Sets one of this object's properties * using the associated key. If the value has * changed, a PropertyChangeEvent is sent * to listeners. * * @param key a String containing the key * @param value an Object value */ public void putValue(String key, Object value); /** * Sets the enabled state of the Action. When enabled, * any component associated with this object is active and * able to fire this object's actionPerformed method. * If the value has changed, a PropertyChangeEvent is sent * to listeners. * * @param b true to enable this Action, false to disable it */ public void setEnabled(boolean b); /** * Returns the enabled state of the Action. When enabled, * any component associated with this object is active and * able to fire this object's actionPerformed method. * * @return true if this Action is enabled */ public boolean isEnabled(); /** * Adds a PropertyChange listener. Containers and attached * components use these methods to register interest in this * Action object. When its enabled state or other property * changes, the registered listeners are informed of the change. * * @param listener a PropertyChangeListener object */ public void addPropertyChangeListener(PropertyChangeListener listener); /** * Removes a PropertyChange listener. * * @param listener a PropertyChangeListener object * @see #addPropertyChangeListener */ public void removePropertyChangeListener(PropertyChangeListener listener); }