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 }