001 /*
002 * Copyright 1996-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.awt.event;
027
028 import java.awt.AWTEvent;
029 import java.awt.Event;
030
031 /**
032 * A semantic event which indicates that a component-defined action occurred.
033 * This high-level event is generated by a component (such as a
034 * <code>Button</code>) when
035 * the component-specific action occurs (such as being pressed).
036 * The event is passed to every <code>ActionListener</code> object
037 * that registered to receive such events using the component's
038 * <code>addActionListener</code> method.
039 * <p>
040 * <b>Note:</b> To invoke an <code>ActionEvent</code> on a
041 * <code>Button</code> using the keyboard, use the Space bar.
042 * <P>
043 * The object that implements the <code>ActionListener</code> interface
044 * gets this <code>ActionEvent</code> when the event occurs. The listener
045 * is therefore spared the details of processing individual mouse movements
046 * and mouse clicks, and can instead process a "meaningful" (semantic)
047 * event like "button pressed".
048 *
049 * @see ActionListener
050 * @see <a href="http://java.sun.com/docs/books/tutorial/post1.0/ui/eventmodel.html">Tutorial: Java 1.1 Event Model</a>
051 *
052 * @author Carl Quinn
053 * @version 1.38 05/05/07
054 * @since 1.1
055 */
056 public class ActionEvent extends AWTEvent {
057
058 /**
059 * The shift modifier. An indicator that the shift key was held
060 * down during the event.
061 */
062 public static final int SHIFT_MASK = Event.SHIFT_MASK;
063
064 /**
065 * The control modifier. An indicator that the control key was held
066 * down during the event.
067 */
068 public static final int CTRL_MASK = Event.CTRL_MASK;
069
070 /**
071 * The meta modifier. An indicator that the meta key was held
072 * down during the event.
073 */
074 public static final int META_MASK = Event.META_MASK;
075
076 /**
077 * The alt modifier. An indicator that the alt key was held
078 * down during the event.
079 */
080 public static final int ALT_MASK = Event.ALT_MASK;
081
082 /**
083 * The first number in the range of ids used for action events.
084 */
085 public static final int ACTION_FIRST = 1001;
086
087 /**
088 * The last number in the range of ids used for action events.
089 */
090 public static final int ACTION_LAST = 1001;
091
092 /**
093 * This event id indicates that a meaningful action occured.
094 */
095 public static final int ACTION_PERFORMED = ACTION_FIRST; //Event.ACTION_EVENT
096
097 /**
098 * The nonlocalized string that gives more details
099 * of what actually caused the event.
100 * This information is very specific to the component
101 * that fired it.
102
103 * @serial
104 * @see #getActionCommand
105 */
106 String actionCommand;
107
108 /**
109 * Timestamp of when this event occurred. Because an ActionEvent is a high-
110 * level, semantic event, the timestamp is typically the same as an
111 * underlying InputEvent.
112 *
113 * @serial
114 * @see #getWhen
115 */
116 long when;
117
118 /**
119 * This represents the key modifier that was selected,
120 * and is used to determine the state of the selected key.
121 * If no modifier has been selected it will default to
122 * zero.
123 *
124 * @serial
125 * @see #getModifiers
126 */
127 int modifiers;
128
129 /*
130 * JDK 1.1 serialVersionUID
131 */
132 private static final long serialVersionUID = -7671078796273832149L;
133
134 /**
135 * Constructs an <code>ActionEvent</code> object.
136 * <p>
137 * Note that passing in an invalid <code>id</code> results in
138 * unspecified behavior. This method throws an
139 * <code>IllegalArgumentException</code> if <code>source</code>
140 * is <code>null</code>.
141 * A <code>null</code> <code>command</code> string is legal,
142 * but not recommended.
143 *
144 * @param source the object that originated the event
145 * @param id an integer that identifies the event
146 * @param command a string that may specify a command (possibly one
147 * of several) associated with the event
148 * @throws IllegalArgumentException if <code>source</code> is null
149 */
150 public ActionEvent(Object source, int id, String command) {
151 this (source, id, command, 0);
152 }
153
154 /**
155 * Constructs an <code>ActionEvent</code> object with modifier keys.
156 * <p>
157 * Note that passing in an invalid <code>id</code> results in
158 * unspecified behavior. This method throws an
159 * <code>IllegalArgumentException</code> if <code>source</code>
160 * is <code>null</code>.
161 * A <code>null</code> <code>command</code> string is legal,
162 * but not recommended.
163 *
164 * @param source the object that originated the event
165 * @param id an integer that identifies the event
166 * @param command a string that may specify a command (possibly one
167 * of several) associated with the event
168 * @param modifiers the modifier keys held down during this action
169 * @throws IllegalArgumentException if <code>source</code> is null
170 */
171 public ActionEvent(Object source, int id, String command,
172 int modifiers) {
173 this (source, id, command, 0, modifiers);
174 }
175
176 /**
177 * Constructs an <code>ActionEvent</code> object with the specified
178 * modifier keys and timestamp.
179 * <p>
180 * Note that passing in an invalid <code>id</code> results in
181 * unspecified behavior. This method throws an
182 * <code>IllegalArgumentException</code> if <code>source</code>
183 * is <code>null</code>.
184 * A <code>null</code> <code>command</code> string is legal,
185 * but not recommended.
186 *
187 * @param source the object that originated the event
188 * @param id an integer that identifies the event
189 * @param command a string that may specify a command (possibly one
190 * of several) associated with the event
191 * @param when the time the event occurred
192 * @param modifiers the modifier keys held down during this action
193 * @throws IllegalArgumentException if <code>source</code> is null
194 *
195 * @since 1.4
196 */
197 public ActionEvent(Object source, int id, String command,
198 long when, int modifiers) {
199 super (source, id);
200 this .actionCommand = command;
201 this .when = when;
202 this .modifiers = modifiers;
203 }
204
205 /**
206 * Returns the command string associated with this action.
207 * This string allows a "modal" component to specify one of several
208 * commands, depending on its state. For example, a single button might
209 * toggle between "show details" and "hide details". The source object
210 * and the event would be the same in each case, but the command string
211 * would identify the intended action.
212 * <p>
213 * Note that if a <code>null</code> command string was passed
214 * to the constructor for this <code>ActionEvent</code>, this
215 * this method returns <code>null</code>.
216 *
217 * @return the string identifying the command for this event
218 */
219 public String getActionCommand() {
220 return actionCommand;
221 }
222
223 /**
224 * Returns the timestamp of when this event occurred. Because an
225 * ActionEvent is a high-level, semantic event, the timestamp is typically
226 * the same as an underlying InputEvent.
227 *
228 * @return this event's timestamp
229 * @since 1.4
230 */
231 public long getWhen() {
232 return when;
233 }
234
235 /**
236 * Returns the modifier keys held down during this action event.
237 *
238 * @return the bitwise-or of the modifier constants
239 */
240 public int getModifiers() {
241 return modifiers;
242 }
243
244 /**
245 * Returns a parameter string identifying this action event.
246 * This method is useful for event-logging and for debugging.
247 *
248 * @return a string identifying the event and its associated command
249 */
250 public String paramString() {
251 String typeStr;
252 switch (id) {
253 case ACTION_PERFORMED:
254 typeStr = "ACTION_PERFORMED";
255 break;
256 default:
257 typeStr = "unknown type";
258 }
259 return typeStr + ",cmd=" + actionCommand + ",when=" + when
260 + ",modifiers="
261 + KeyEvent.getKeyModifiersText(modifiers);
262 }
263 }
|