KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > swing > Action


1 /*
2  * @(#)Action.java 1.30 03/12/19
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7 package javax.swing;
8
9 import java.awt.*;
10 import java.awt.event.*;
11 import java.beans.*;
12
13 /**
14  * The <code>Action</code> interface provides a useful extension to the
15  * <code>ActionListener</code>
16  * interface in cases where the same functionality may be accessed by
17  * several controls.
18  * <p>
19  * In addition to the <code>actionPerformed</code> method defined by the
20  * <code>ActionListener</code> interface, this interface allows the
21  * application to define, in a single place:
22  * <ul>
23  * <li>One or more text strings that describe the function. These strings
24  * can be used, for example, to display the flyover text for a button
25  * or to set the text in a menu item.
26  * <li>One or more icons that depict the function. These icons can be used
27  * for the images in a menu control, or for composite entries in a more
28  * sophisticated user interface.
29  * <li>The enabled/disabled state of the functionality. Instead of having
30  * to separately disable the menu item and the toolbar button, the
31  * application can disable the function that implements this interface.
32  * All components which are registered as listeners for the state change
33  * then know to disable event generation for that item and to modify the
34  * display accordingly.
35  * </ul>
36  * Certain containers, including menus and tool bars, know how to add an
37  * <code>Action</code> object. When an <code>Action</code> object is added
38  * to such a container, the container:
39  * <ol type="a">
40  * <li>Creates a component that is appropriate for that container
41  * (a tool bar creates a button component, for example).
42  * <li>Gets the appropriate property(s) from the <code>Action</code> object to
43  * customize the component (for example, the icon image and flyover text).
44  * <li>Checks the initial state of the <code>Action</code> object to determine
45  * if it is enabled or disabled, and renders the component in the
46  * appropriate fashion.
47  * <li>Registers a listener with the <code>Action</code> object so that is
48  * notified of state changes. When the <code>Action</code> object changes
49  * from enabled to disabled,
50  * or back, the container makes the appropriate revisions to the
51  * event-generation mechanisms and renders the component accordingly.
52  * </ol>
53  * For example, both a menu item and a toolbar button could access a
54  * <code>Cut</code> action object. The text associated with the object is
55  * specified as "Cut", and an image depicting a pair of scissors is specified
56  * as its icon. The <code>Cut</code> action-object can then be added to a
57  * menu and to a tool bar. Each container does the appropriate things with the
58  * object, and invokes its <code>actionPerformed</code> method when the
59  * component associated with it is activated. The application can then disable
60  * or enable the application object without worrying about what user-interface
61  * components are connected to it.
62  * <p>
63  * This interface can be added to an existing class or used to create an
64  * adapter (typically, by subclassing <code>AbstractAction</code>).
65  * The <code>Action</code> object
66  * can then be added to multiple <code>Action</code>-aware containers
67  * and connected to <code>Action</code>-capable
68  * components. The GUI controls can then be activated or
69  * deactivated all at once by invoking the <code>Action</code> object's
70  * <code>setEnabled</code> method.
71  * <p>
72  * Note that <code>Action</code> implementations tend to be more expensive
73  * in terms of storage than a typical <code>ActionListener</code>,
74  * which does not offer the benefits of centralized control of
75  * functionality and broadcast of property changes. For this reason,
76  * you should take care to only use <code>Action</code>s where their benefits
77  * are desired, and use simple <code>ActionListener</code>s elsewhere.
78  *
79  * @version 1.30 12/19/03
80  * @author Georges Saab
81  * @see AbstractAction
82  */

83 public interface Action extends ActionListener {
84     /**
85      * Useful constants that can be used as the storage-retrieval key
86      * when setting or getting one of this object's properties (text
87      * or icon).
88      */

89     /**
90      * Not currently used.
91      */

92     public static final String JavaDoc DEFAULT = "Default";
93     /**
94      * The key used for storing the <code>String</code> name
95      * for the action, used for a menu or button.
96      */

97     public static final String JavaDoc NAME = "Name";
98     /**
99      * The key used for storing a short <code>String</code>
100      * description for the action, used for tooltip text.
101      */

102     public static final String JavaDoc SHORT_DESCRIPTION = "ShortDescription";
103     /**
104      * The key used for storing a longer <code>String</code>
105      * description for the action, could be used for context-sensitive help.
106      */

107     public static final String JavaDoc LONG_DESCRIPTION = "LongDescription";
108     /**
109      * The key used for storing a small <code>Icon</code>, such
110      * as <code>ImageIcon</code>, for the action, used for toolbar buttons.
111      */

112     public static final String JavaDoc SMALL_ICON = "SmallIcon";
113
114     /**
115      * The key used to determine the command <code>String</code> for the
116      * <code>ActionEvent</code> that will be created when an
117      * <code>Action</code> is going to be notified as the result of
118      * residing in a <code>Keymap</code> associated with a
119      * <code>JComponent</code>.
120      */

121     public static final String JavaDoc ACTION_COMMAND_KEY = "ActionCommandKey";
122
123     /**
124      * The key used for storing a <code>KeyStroke</code> to be used as the
125      * accelerator for the action.
126      *
127      * @since 1.3
128      */

129     public static final String JavaDoc ACCELERATOR_KEY="AcceleratorKey";
130     
131     /**
132      * The key used for storing a <code>KeyEvent</code> to be used as
133      * the mnemonic for the action.
134      *
135      * @since 1.3
136      */

137     public static final String JavaDoc MNEMONIC_KEY="MnemonicKey";
138
139     /**
140      * Gets one of this object's properties
141      * using the associated key.
142      * @see #putValue
143      */

144     public Object JavaDoc getValue(String JavaDoc key);
145     /**
146      * Sets one of this object's properties
147      * using the associated key. If the value has
148      * changed, a <code>PropertyChangeEvent</code> is sent
149      * to listeners.
150      *
151      * @param key a <code>String</code> containing the key
152      * @param value an <code>Object</code> value
153      */

154     public void putValue(String JavaDoc key, Object JavaDoc value);
155
156     /**
157      * Sets the enabled state of the <code>Action</code>. When enabled,
158      * any component associated with this object is active and
159      * able to fire this object's <code>actionPerformed</code> method.
160      * If the value has changed, a <code>PropertyChangeEvent</code> is sent
161      * to listeners.
162      *
163      * @param b true to enable this <code>Action</code>, false to disable it
164      */

165     public void setEnabled(boolean b);
166     /**
167      * Returns the enabled state of the <code>Action</code>. When enabled,
168      * any component associated with this object is active and
169      * able to fire this object's <code>actionPerformed</code> method.
170      *
171      * @return true if this <code>Action</code> is enabled
172      */

173     public boolean isEnabled();
174
175     /**
176      * Adds a <code>PropertyChange</code> listener. Containers and attached
177      * components use these methods to register interest in this
178      * <code>Action</code> object. When its enabled state or other property
179      * changes, the registered listeners are informed of the change.
180      *
181      * @param listener a <code>PropertyChangeListener</code> object
182      */

183     public void addPropertyChangeListener(PropertyChangeListener listener);
184     /**
185      * Removes a <code>PropertyChange</code> listener.
186      *
187      * @param listener a <code>PropertyChangeListener</code> object
188      * @see #addPropertyChangeListener
189      */

190     public void removePropertyChangeListener(PropertyChangeListener listener);
191
192 }
193
Popular Tags