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 }