1 /*
2 * Copyright (c) 1996, 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
26 package java.awt.event;
27
28 import java.awt.AWTEvent;
29 import java.awt.Event;
30 import java.lang.annotation.Native;
31
32 /**
33 * A semantic event which indicates that a component-defined action occurred.
34 * This high-level event is generated by a component (such as a
35 * <code>Button</code>) when
36 * the component-specific action occurs (such as being pressed).
37 * The event is passed to every <code>ActionListener</code> object
38 * that registered to receive such events using the component's
39 * <code>addActionListener</code> method.
40 * <p>
41 * <b>Note:</b> To invoke an <code>ActionEvent</code> on a
42 * <code>Button</code> using the keyboard, use the Space bar.
43 * <P>
44 * The object that implements the <code>ActionListener</code> interface
45 * gets this <code>ActionEvent</code> when the event occurs. The listener
46 * is therefore spared the details of processing individual mouse movements
47 * and mouse clicks, and can instead process a "meaningful" (semantic)
48 * event like "button pressed".
49 * <p>
50 * An unspecified behavior will be caused if the {@code id} parameter
51 * of any particular {@code ActionEvent} instance is not
52 * in the range from {@code ACTION_FIRST} to {@code ACTION_LAST}.
53 *
54 * @see ActionListener
55 * @see <a href="http://java.sun.com/docs/books/tutorial/uiswing/events/actionlistener.html">Tutorial: How to Write an Action Listener</a>
56 *
57 * @author Carl Quinn
58 * @since 1.1
59 */
60 public class ActionEvent extends AWTEvent {
61
62 /**
63 * The shift modifier. An indicator that the shift key was held
64 * down during the event.
65 */
66 public static final int SHIFT_MASK = Event.SHIFT_MASK;
67
68 /**
69 * The control modifier. An indicator that the control key was held
70 * down during the event.
71 */
72 public static final int CTRL_MASK = Event.CTRL_MASK;
73
74 /**
75 * The meta modifier. An indicator that the meta key was held
76 * down during the event.
77 */
78 public static final int META_MASK = Event.META_MASK;
79
80 /**
81 * The alt modifier. An indicator that the alt key was held
82 * down during the event.
83 */
84 public static final int ALT_MASK = Event.ALT_MASK;
85
86
87 /**
88 * The first number in the range of ids used for action events.
89 */
90 public static final int ACTION_FIRST = 1001;
91
92 /**
93 * The last number in the range of ids used for action events.
94 */
95 public static final int ACTION_LAST = 1001;
96
97 /**
98 * This event id indicates that a meaningful action occured.
99 */
100 @Native public static final int ACTION_PERFORMED = ACTION_FIRST; //Event.ACTION_EVENT
101
102 /**
103 * The nonlocalized string that gives more details
104 * of what actually caused the event.
105 * This information is very specific to the component
106 * that fired it.
107
108 * @serial
109 * @see #getActionCommand
110 */
111 String actionCommand;
112
113 /**
114 * Timestamp of when this event occurred. Because an ActionEvent is a high-
115 * level, semantic event, the timestamp is typically the same as an
116 * underlying InputEvent.
117 *
118 * @serial
119 * @see #getWhen
120 */
121 long when;
122
123 /**
124 * This represents the key modifier that was selected,
125 * and is used to determine the state of the selected key.
126 * If no modifier has been selected it will default to
127 * zero.
128 *
129 * @serial
130 * @see #getModifiers
131 */
132 int modifiers;
133
134 /*
135 * JDK 1.1 serialVersionUID
136 */
137 private static final long serialVersionUID = -7671078796273832149L;
138
139 /**
140 * Constructs an <code>ActionEvent</code> object.
141 * <p>
142 * This method throws an
143 * <code>IllegalArgumentException</code> if <code>source</code>
144 * is <code>null</code>.
145 * A <code>null</code> <code>command</code> string is legal,
146 * but not recommended.
147 *
148 * @param source The object that originated the event
149 * @param id An integer that identifies the event.
150 * For information on allowable values, see
151 * the class description for {@link ActionEvent}
152 * @param command A string that may specify a command (possibly one
153 * of several) associated with the event
154 * @throws IllegalArgumentException if <code>source</code> is null
155 * @see #getSource()
156 * @see #getID()
157 * @see #getActionCommand()
158 */
159 public ActionEvent(Object source, int id, String command) {
160 this(source, id, command, 0);
161 }
162
163 /**
164 * Constructs an <code>ActionEvent</code> object with modifier keys.
165 * <p>
166 * This method throws an
167 * <code>IllegalArgumentException</code> if <code>source</code>
168 * is <code>null</code>.
169 * A <code>null</code> <code>command</code> string is legal,
170 * but not recommended.
171 *
172 * @param source The object that originated the event
173 * @param id An integer that identifies the event.
174 * For information on allowable values, see
175 * the class description for {@link ActionEvent}
176 * @param command A string that may specify a command (possibly one
177 * of several) associated with the event
178 * @param modifiers The modifier keys down during event
179 * (shift, ctrl, alt, meta).
180 * Passing negative parameter is not recommended.
181 * Zero value means that no modifiers were passed
182 * @throws IllegalArgumentException if <code>source</code> is null
183 * @see #getSource()
184 * @see #getID()
185 * @see #getActionCommand()
186 * @see #getModifiers()
187 */
188 public ActionEvent(Object source, int id, String command, int modifiers) {
189 this(source, id, command, 0, modifiers);
190 }
191
192 /**
193 * Constructs an <code>ActionEvent</code> object with the specified
194 * modifier keys and timestamp.
195 * <p>
196 * This method throws an
197 * <code>IllegalArgumentException</code> if <code>source</code>
198 * is <code>null</code>.
199 * A <code>null</code> <code>command</code> string is legal,
200 * but not recommended.
201 *
202 * @param source The object that originated the event
203 * @param id An integer that identifies the event.
204 * For information on allowable values, see
205 * the class description for {@link ActionEvent}
206 * @param command A string that may specify a command (possibly one
207 * of several) associated with the event
208 * @param modifiers The modifier keys down during event
209 * (shift, ctrl, alt, meta).
210 * Passing negative parameter is not recommended.
211 * Zero value means that no modifiers were passed
212 * @param when A long that gives the time the event occurred.
213 * Passing negative or zero value
214 * is not recommended
215 * @throws IllegalArgumentException if <code>source</code> is null
216 * @see #getSource()
217 * @see #getID()
218 * @see #getActionCommand()
219 * @see #getModifiers()
220 * @see #getWhen()
221 *
222 * @since 1.4
223 */
224 public ActionEvent(Object source, int id, String command, long when,
225 int modifiers) {
226 super(source, id);
227 this.actionCommand = command;
228 this.when = when;
229 this.modifiers = modifiers;
230 }
231
232 /**
233 * Returns the command string associated with this action.
234 * This string allows a "modal" component to specify one of several
235 * commands, depending on its state. For example, a single button might
236 * toggle between "show details" and "hide details". The source object
237 * and the event would be the same in each case, but the command string
238 * would identify the intended action.
239 * <p>
240 * Note that if a <code>null</code> command string was passed
241 * to the constructor for this <code>ActionEvent</code>, this
242 * this method returns <code>null</code>.
243 *
244 * @return the string identifying the command for this event
245 */
246 public String getActionCommand() {
247 return actionCommand;
248 }
249
250 /**
251 * Returns the timestamp of when this event occurred. Because an
252 * ActionEvent is a high-level, semantic event, the timestamp is typically
253 * the same as an underlying InputEvent.
254 *
255 * @return this event's timestamp
256 * @since 1.4
257 */
258 public long getWhen() {
259 return when;
260 }
261
262 /**
263 * Returns the modifier keys held down during this action event.
264 *
265 * @return the bitwise-or of the modifier constants
266 */
267 public int getModifiers() {
268 return modifiers;
269 }
270
271 /**
272 * Returns a parameter string identifying this action event.
273 * This method is useful for event-logging and for debugging.
274 *
275 * @return a string identifying the event and its associated command
276 */
277 public String paramString() {
278 String typeStr;
279 switch(id) {
280 case ACTION_PERFORMED:
281 typeStr = "ACTION_PERFORMED";
282 break;
283 default:
284 typeStr = "unknown type";
285 }
286 return typeStr + ",cmd="+actionCommand+",when="+when+",modifiers="+
287 KeyEvent.getKeyModifiersText(modifiers);
288 }
289 }