libjava/classpath/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., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 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 gnu.java.lang.CPStringBuilder;
  42
  43 import java.awt.AWTEvent;
  44 import java.awt.EventQueue;
  45
  46 /**
  47  * This event is generated when an action on a component (such as a
  48  * button press) occurs.
  49  *
  50  * @author Aaron M. Renn (arenn@urbanophile.com)
  51  * @see ActionListener
  52  * @since 1.1
  53  * @status updated to 1.4
  54  */
  55 public class ActionEvent extends AWTEvent
  56 {
  57   /**
  58    * Compatible with JDK 1.1+.
  59    */
  60   private static final long serialVersionUID = -7671078796273832149L;
  61
  62   /** Bit mask indicating the shift key was pressed. */
  63   public static final int SHIFT_MASK = InputEvent.SHIFT_MASK;
  64
  65   /** Bit mask indicating the control key was pressed. */
  66   public static final int CTRL_MASK = InputEvent.CTRL_MASK;
  67
  68   /** Bit mask indicating the that meta key was pressed. */
  69   public static final int META_MASK = InputEvent.META_MASK;
  70
  71   /** Bit mask indicating that the alt key was pressed. */
  72   public static final int ALT_MASK = InputEvent.ALT_MASK;
  73
  74   /** The first id number in the range of action id's. */
  75   public static final int ACTION_FIRST = 1001;
  76
  77   /** The last id number in the range of action id's. */
  78   public static final int ACTION_LAST = 1001;
  79
  80   /** An event id indicating that an action has occurred. */
  81   public static final int ACTION_PERFORMED = 1001;
  82
  83   /**
  84    * A nonlocalized string that gives more specific details of the event cause.
  85    *
  86    * @see #getActionCommand()
  87    * @serial the command for this event
  88    */
  89   private final String actionCommand;
  90
  91   /**
  92    * The bitmask of the modifiers that were pressed during the action.
  93    *
  94    * @see #getModifiers()
  95    * @serial modifiers for this event
  96    */
  97   private final int modifiers;
  98
  99   /**
 100    * The timestamp of this event; usually the same as the underlying input
 101    * event.
 102    *
 103    * @see #getWhen()
 104    * @serial the timestamp of the event
 105    * @since 1.4
 106    */
 107   private final long when;
 108
 109   /**
 110    * Initializes a new instance of <code>ActionEvent</code> with the
 111    * specified source, id, and command. Note that an invalid id leads to
 112    * unspecified results.
 113    *
 114    * @param source the event source
 115    * @param id the event id
 116    * @param command the command string for this action
 117    * @throws IllegalArgumentException if source is null
 118    */
 119   public ActionEvent(Object source, int id, String command)
 120   {
 121     this(source, id, command, EventQueue.getMostRecentEventTime(), 0);
 122   }
 123
 124   /**
 125    * Initializes a new instance of <code>ActionEvent</code> with the
 126    * specified source, id, command, and modifiers. Note that an invalid id
 127    * leads to unspecified results.
 128    *
 129    * @param source the event source
 130    * @param id the event id
 131    * @param command the command string for this action
 132    * @param modifiers the bitwise or of modifier keys down during the action
 133    * @throws IllegalArgumentException if source is null
 134    */
 135   public ActionEvent(Object source, int id, String command, int modifiers)
 136   {
 137     this(source, id, command, EventQueue.getMostRecentEventTime(), modifiers);
 138   }
 139
 140   /**
 141    * Initializes a new instance of <code>ActionEvent</code> with the
 142    * specified source, id, command, and modifiers, and timestamp. Note that
 143    * an invalid id leads to unspecified results.
 144    *
 145    * @param source the event source
 146    * @param id the event id
 147    * @param command the command string for this action
 148    * @param when the timestamp of the event
 149    * @param modifiers the bitwise or of modifier keys down during the action
 150    * @throws IllegalArgumentException if source is null
 151    * @since 1.4
 152    */
 153   public ActionEvent(Object source, int id, String command, long when,
 154                      int modifiers)
 155   {
 156     super(source, id);
 157     actionCommand = command;
 158     this.when = when;
 159     this.modifiers = modifiers;
 160   }
 161
 162   /**
 163    * Returns the command string associated with this action.
 164    *
 165    * @return the command string associated with this action
 166    */
 167   public String getActionCommand()
 168   {
 169     return actionCommand;
 170   }
 171
 172   /**
 173    * Gets the timestamp of when this action took place. Usually, this
 174    * corresponds to the timestamp of the underlying InputEvent.
 175    *
 176    * @return the timestamp of this action
 177    * @since 1.4
 178    */
 179   public long getWhen()
 180   {
 181     return when;
 182   }
 183
 184   /**
 185    * Returns the keys held down during the action.  This value will be a
 186    * combination of the bit mask constants defined in this class, or 0 if no
 187    * modifiers were pressed.
 188    *
 189    * @return the modifier bits
 190    */
 191   public int getModifiers()
 192   {
 193     return modifiers;
 194   }
 195
 196   /**
 197    * Returns a string that identifies the action event. This is in the format
 198    * <code>"ACTION_PERFORMED,cmd=" + getActionCommand() + ",when=" + getWhen()
 199    * + ",modifiers=" + &lt;modifier string&gt;</code>, where the modifier
 200    * string is in the order "Meta", "Ctrl", "Alt", "Shift", "Alt Graph", and
 201    * "Button1", separated by '+', according to the bits set in getModifiers().
 202    *
 203    * @return a string identifying the event
 204    */
 205   public String paramString()
 206   {
 207     CPStringBuilder s = new CPStringBuilder(id == ACTION_PERFORMED
 208                                             ? "ACTION_PERFORMED,cmd="
 209                                             : "unknown type,cmd=");
 210     s.append(actionCommand).append(",when=").append(when).append(",modifiers");
 211     int len = s.length();
 212     s.setLength(len + 1);
 213     if ((modifiers & META_MASK) != 0)
 214       s.append("+Meta");
 215     if ((modifiers & CTRL_MASK) != 0)
 216       s.append("+Ctrl");
 217     if ((modifiers & ALT_MASK) != 0)
 218       s.append("+Alt");
 219     if ((modifiers & SHIFT_MASK) != 0)
 220       s.append("+Shift");
 221     if ((modifiers & InputEvent.ALT_GRAPH_MASK) != 0)
 222       s.append("+Alt Graph");
 223     if ((modifiers & InputEvent.BUTTON1_MASK) != 0)
 224       s.append("+Button1");
 225     s.setCharAt(len, '=');
 226     return s.toString();
 227   }
 228 } // class ActionEvent