libjava/java/awt/event/ActionEvent.java

   1 /* ActionEvent.java -- an action has been triggered
   2    Copyright (C) 1999, 2002, 2005  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.awt.event;
  40
  41 import java.awt.AWTEvent;
  42 import java.awt.EventQueue;
  43
  44 /**
  45  * This event is generated when an action on a component (such as a
  46  * button press) occurs.
  47  *
  48  * @author Aaron M. Renn (arenn@urbanophile.com)
  49  * @see ActionListener
  50  * @since 1.1
  51  * @status updated to 1.4
  52  */
  53 public class ActionEvent extends AWTEvent
  54 {
  55   /**
  56    * Compatible with JDK 1.1+.
  57    */
  58   private static final long serialVersionUID = -7671078796273832149L;
  59
  60   /** Bit mask indicating the shift key was pressed. */
  61   public static final int SHIFT_MASK = InputEvent.SHIFT_MASK;
  62
  63   /** Bit mask indicating the control key was pressed. */
  64   public static final int CTRL_MASK = InputEvent.CTRL_MASK;
  65
  66   /** Bit mask indicating the that meta key was pressed. */
  67   public static final int META_MASK = InputEvent.META_MASK;
  68
  69   /** Bit mask indicating that the alt key was pressed. */
  70   public static final int ALT_MASK = InputEvent.ALT_MASK;
  71
  72   /** The first id number in the range of action id's. */
  73   public static final int ACTION_FIRST = 1001;
  74
  75   /** The last id number in the range of action id's. */
  76   public static final int ACTION_LAST = 1001;
  77
  78   /** An event id indicating that an action has occurred. */
  79   public static final int ACTION_PERFORMED = 1001;
  80
  81   /**
  82    * A nonlocalized string that gives more specific details of the event cause.
  83    *
  84    * @see #getActionCommand()
  85    * @serial the command for this event
  86    */
  87   private final String actionCommand;
  88
  89   /**
  90    * The bitmask of the modifiers that were pressed during the action.
  91    *
  92    * @see #getModifiers()
  93    * @serial modifiers for this event
  94    */
  95   private final int modifiers;
  96
  97   /**
  98    * The timestamp of this event; usually the same as the underlying input
  99    * event.
 100    *
 101    * @see #getWhen()
 102    * @serial the timestamp of the event
 103    * @since 1.4
 104    */
 105   private final long when;
 106
 107   /**
 108    * Initializes a new instance of <code>ActionEvent</code> with the
 109    * specified source, id, and command. Note that an invalid id leads to
 110    * unspecified results.
 111    *
 112    * @param source the event source
 113    * @param id the event id
 114    * @param command the command string for this action
 115    * @throws IllegalArgumentException if source is null
 116    */
 117   public ActionEvent(Object source, int id, String command)
 118   {
 119     this(source, id, command, EventQueue.getMostRecentEventTime(), 0);
 120   }
 121
 122   /**
 123    * Initializes a new instance of <code>ActionEvent</code> with the
 124    * specified source, id, command, and modifiers. Note that an invalid id
 125    * leads to unspecified results.
 126    *
 127    * @param source the event source
 128    * @param id the event id
 129    * @param command the command string for this action
 130    * @param modifiers the bitwise or of modifier keys down during the action
 131    * @throws IllegalArgumentException if source is null
 132    */
 133   public ActionEvent(Object source, int id, String command, int modifiers)
 134   {
 135     this(source, id, command, EventQueue.getMostRecentEventTime(), modifiers);
 136   }
 137
 138   /**
 139    * Initializes a new instance of <code>ActionEvent</code> with the
 140    * specified source, id, command, and modifiers, and timestamp. Note that
 141    * an invalid id leads to unspecified results.
 142    *
 143    * @param source the event source
 144    * @param id the event id
 145    * @param command the command string for this action
 146    * @param when the timestamp of the event
 147    * @param modifiers the bitwise or of modifier keys down during the action
 148    * @throws IllegalArgumentException if source is null
 149    * @since 1.4
 150    */
 151   public ActionEvent(Object source, int id, String command, long when,
 152                      int modifiers)
 153   {
 154     super(source, id);
 155     actionCommand = command;
 156     this.when = when;
 157     this.modifiers = modifiers;
 158   }
 159
 160   /**
 161    * Returns the command string associated with this action.
 162    *
 163    * @return the command string associated with this action
 164    */
 165   public String getActionCommand()
 166   {
 167     return actionCommand;
 168   }
 169
 170   /**
 171    * Gets the timestamp of when this action took place. Usually, this
 172    * corresponds to the timestamp of the underlying InputEvent.
 173    *
 174    * @return the timestamp of this action
 175    * @since 1.4
 176    */
 177   public long getWhen()
 178   {
 179     return when;
 180   }
 181
 182   /**
 183    * Returns the keys held down during the action.  This value will be a
 184    * combination of the bit mask constants defined in this class, or 0 if no
 185    * modifiers were pressed.
 186    *
 187    * @return the modifier bits
 188    */
 189   public int getModifiers()
 190   {
 191     return modifiers;
 192   }
 193
 194   /**
 195    * Returns a string that identifies the action event. This is in the format
 196    * <code>"ACTION_PERFORMED,cmd=" + getActionCommand() + ",when=" + getWhen()
 197    * + ",modifiers=" + &lt;modifier string&gt;</code>, where the modifier
 198    * string is in the order "Meta", "Ctrl", "Alt", "Shift", "Alt Graph", and
 199    * "Button1", separated by '+', according to the bits set in getModifiers().
 200    *
 201    * @return a string identifying the event
 202    */
 203   public String paramString()
 204   {
 205     StringBuffer s = new StringBuffer(id == ACTION_PERFORMED
 206                                       ? "ACTION_PERFORMED,cmd="
 207                                       : "unknown type,cmd=");
 208     s.append(actionCommand).append(",when=").append(when).append(",modifiers");
 209     int len = s.length();
 210     s.setLength(len + 1);
 211     if ((modifiers & META_MASK) != 0)
 212       s.append("+Meta");
 213     if ((modifiers & CTRL_MASK) != 0)
 214       s.append("+Ctrl");
 215     if ((modifiers & ALT_MASK) != 0)
 216       s.append("+Alt");
 217     if ((modifiers & SHIFT_MASK) != 0)
 218       s.append("+Shift");
 219     if ((modifiers & InputEvent.ALT_GRAPH_MASK) != 0)
 220       s.append("+Alt Graph");
 221     if ((modifiers & InputEvent.BUTTON1_MASK) != 0)
 222       s.append("+Button1");
 223     s.setCharAt(len, '=');
 224     return s.toString();
 225   }
 226 } // class ActionEvent