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 26package java.awt.event; 27 28import java.awt.AWTEvent; 29import java.lang.annotation.Native; 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}) when 35 * the component-specific action occurs (such as being pressed). 36 * The event is passed to every {@code ActionListener} object 37 * that registered to receive such events using the component's 38 * {@code addActionListener} method. 39 * <p> 40 * <b>Note:</b> To invoke an {@code ActionEvent} on a 41 * {@code Button} using the keyboard, use the Space bar. 42 * <P> 43 * The object that implements the {@code ActionListener} interface 44 * gets this {@code ActionEvent} 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://docs.oracle.com/javase/tutorial/uiswing/events/actionlistener.html">Tutorial: How to Write an Action Listener</a> 55 * 56 * @author Carl Quinn 57 * @since 1.1 58 */ 59public 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 = 1 << 0; 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 = 1 << 1; 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 = 1 << 2; 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 = 1 << 3; 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 occurred. 98 */ 99 @Native 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} object. 140 * <p> 141 * This method throws an 142 * {@code IllegalArgumentException} if {@code source} 143 * is {@code null}. 144 * A {@code null command} 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} 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} object with modifier keys. 164 * <p> 165 * This method throws an 166 * {@code IllegalArgumentException} if {@code source} 167 * is {@code null}. 168 * A {@code null command} 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} 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} object with the specified 193 * modifier keys and timestamp. 194 * <p> 195 * This method throws an 196 * {@code IllegalArgumentException} if {@code source} 197 * is {@code null}. 198 * A {@code null command} 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} 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} command string was passed 240 * to the constructor for this {@code ActionEvent}, this 241 * this method returns {@code null}. 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 @SuppressWarnings("deprecation") 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} 290