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 import javax.tools.annotation.GenerateNativeHeader; 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 /* No native methods here, but the constants are needed in the supporting JNI code */ 61 @GenerateNativeHeader 62 public class ActionEvent extends AWTEvent { 63 64 /** 65 * The shift modifier. An indicator that the shift key was held 66 * down during the event. 67 */ 68 public static final int SHIFT_MASK = Event.SHIFT_MASK; 69 70 /** 71 * The control modifier. An indicator that the control key was held 72 * down during the event. 73 */ 74 public static final int CTRL_MASK = Event.CTRL_MASK; 75 76 /** 77 * The meta modifier. An indicator that the meta key was held 78 * down during the event. 79 */ 80 public static final int META_MASK = Event.META_MASK; 81 82 /** 83 * The alt modifier. An indicator that the alt key was held 84 * down during the event. 85 */ 86 public static final int ALT_MASK = Event.ALT_MASK; 87 88 89 /** 90 * The first number in the range of ids used for action events. 91 */ 92 public static final int ACTION_FIRST = 1001; 93 94 /** 95 * The last number in the range of ids used for action events. 96 */ 97 public static final int ACTION_LAST = 1001; 98 99 /** 100 * This event id indicates that a meaningful action occured. 101 */ 102 public static final int ACTION_PERFORMED = ACTION_FIRST; //Event.ACTION_EVENT 103 104 /** 105 * The nonlocalized string that gives more details 106 * of what actually caused the event. 107 * This information is very specific to the component 108 * that fired it. 109 110 * @serial 111 * @see #getActionCommand 112 */ 113 String actionCommand; 114 115 /** 116 * Timestamp of when this event occurred. Because an ActionEvent is a high- 117 * level, semantic event, the timestamp is typically the same as an 118 * underlying InputEvent. 119 * 120 * @serial 121 * @see #getWhen 122 */ 123 long when; 124 125 /** 126 * This represents the key modifier that was selected, 127 * and is used to determine the state of the selected key. 128 * If no modifier has been selected it will default to 129 * zero. 130 * 131 * @serial 132 * @see #getModifiers 133 */ 134 int modifiers; 135 136 /* 137 * JDK 1.1 serialVersionUID 138 */ 139 private static final long serialVersionUID = -7671078796273832149L; 140 141 /** 142 * Constructs an <code>ActionEvent</code> object. 143 * <p> 144 * This method throws an 145 * <code>IllegalArgumentException</code> if <code>source</code> 146 * is <code>null</code>. 147 * A <code>null</code> <code>command</code> string is legal, 148 * but not recommended. 149 * 150 * @param source The object that originated the event 151 * @param id An integer that identifies the event. 152 * For information on allowable values, see 153 * the class description for {@link ActionEvent} 154 * @param command A string that may specify a command (possibly one 155 * of several) associated with the event 156 * @throws IllegalArgumentException if <code>source</code> is null 157 * @see #getSource() 158 * @see #getID() 159 * @see #getActionCommand() 160 */ 161 public ActionEvent(Object source, int id, String command) { 162 this(source, id, command, 0); 163 } 164 165 /** 166 * Constructs an <code>ActionEvent</code> object with modifier keys. 167 * <p> 168 * This method throws an 169 * <code>IllegalArgumentException</code> if <code>source</code> 170 * is <code>null</code>. 171 * A <code>null</code> <code>command</code> string is legal, 172 * but not recommended. 173 * 174 * @param source The object that originated the event 175 * @param id An integer that identifies the event. 176 * For information on allowable values, see 177 * the class description for {@link ActionEvent} 178 * @param command A string that may specify a command (possibly one 179 * of several) associated with the event 180 * @param modifiers The modifier keys down during event 181 * (shift, ctrl, alt, meta). 182 * Passing negative parameter is not recommended. 183 * Zero value means that no modifiers were passed 184 * @throws IllegalArgumentException if <code>source</code> is null 185 * @see #getSource() 186 * @see #getID() 187 * @see #getActionCommand() 188 * @see #getModifiers() 189 */ 190 public ActionEvent(Object source, int id, String command, int modifiers) { 191 this(source, id, command, 0, modifiers); 192 } 193 194 /** 195 * Constructs an <code>ActionEvent</code> object with the specified 196 * modifier keys and timestamp. 197 * <p> 198 * This method throws an 199 * <code>IllegalArgumentException</code> if <code>source</code> 200 * is <code>null</code>. 201 * A <code>null</code> <code>command</code> string is legal, 202 * but not recommended. 203 * 204 * @param source The object that originated the event 205 * @param id An integer that identifies the event. 206 * For information on allowable values, see 207 * the class description for {@link ActionEvent} 208 * @param command A string that may specify a command (possibly one 209 * of several) associated with the event 210 * @param modifiers The modifier keys down during event 211 * (shift, ctrl, alt, meta). 212 * Passing negative parameter is not recommended. 213 * Zero value means that no modifiers were passed 214 * @param when A long that gives the time the event occurred. 215 * Passing negative or zero value 216 * is not recommended 217 * @throws IllegalArgumentException if <code>source</code> is null 218 * @see #getSource() 219 * @see #getID() 220 * @see #getActionCommand() 221 * @see #getModifiers() 222 * @see #getWhen() 223 * 224 * @since 1.4 225 */ 226 public ActionEvent(Object source, int id, String command, long when, 227 int modifiers) { 228 super(source, id); 229 this.actionCommand = command; 230 this.when = when; 231 this.modifiers = modifiers; 232 } 233 234 /** 235 * Returns the command string associated with this action. 236 * This string allows a "modal" component to specify one of several 237 * commands, depending on its state. For example, a single button might 238 * toggle between "show details" and "hide details". The source object 239 * and the event would be the same in each case, but the command string 240 * would identify the intended action. 241 * <p> 242 * Note that if a <code>null</code> command string was passed 243 * to the constructor for this <code>ActionEvent</code>, this 244 * this method returns <code>null</code>. 245 * 246 * @return the string identifying the command for this event 247 */ 248 public String getActionCommand() { 249 return actionCommand; 250 } 251 252 /** 253 * Returns the timestamp of when this event occurred. Because an 254 * ActionEvent is a high-level, semantic event, the timestamp is typically 255 * the same as an underlying InputEvent. 256 * 257 * @return this event's timestamp 258 * @since 1.4 259 */ 260 public long getWhen() { 261 return when; 262 } 263 264 /** 265 * Returns the modifier keys held down during this action event. 266 * 267 * @return the bitwise-or of the modifier constants 268 */ 269 public int getModifiers() { 270 return modifiers; 271 } 272 273 /** 274 * Returns a parameter string identifying this action event. 275 * This method is useful for event-logging and for debugging. 276 * 277 * @return a string identifying the event and its associated command 278 */ 279 public String paramString() { 280 String typeStr; 281 switch(id) { 282 case ACTION_PERFORMED: 283 typeStr = "ACTION_PERFORMED"; 284 break; 285 default: 286 typeStr = "unknown type"; 287 } 288 return typeStr + ",cmd="+actionCommand+",when="+when+",modifiers="+ 289 KeyEvent.getKeyModifiersText(modifiers); 290 } 291 }