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