001/* ActionEvent.java -- an action has been triggered
002   Copyright (C) 1999, 2002, 2005  Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package java.awt.event;
040
041import gnu.java.lang.CPStringBuilder;
042
043import java.awt.AWTEvent;
044import java.awt.EventQueue;
045
046/**
047 * This event is generated when an action on a component (such as a
048 * button press) occurs.
049 *
050 * @author Aaron M. Renn (arenn@urbanophile.com)
051 * @see ActionListener
052 * @since 1.1
053 * @status updated to 1.4
054 */
055public class ActionEvent extends AWTEvent
056{
057  /**
058   * Compatible with JDK 1.1+.
059   */
060  private static final long serialVersionUID = -7671078796273832149L;
061
062  /** Bit mask indicating the shift key was pressed. */
063  public static final int SHIFT_MASK = InputEvent.SHIFT_MASK;
064
065  /** Bit mask indicating the control key was pressed. */
066  public static final int CTRL_MASK = InputEvent.CTRL_MASK;
067
068  /** Bit mask indicating the that meta key was pressed. */
069  public static final int META_MASK = InputEvent.META_MASK;
070
071  /** Bit mask indicating that the alt key was pressed. */
072  public static final int ALT_MASK = InputEvent.ALT_MASK;
073
074  /** The first id number in the range of action id's. */
075  public static final int ACTION_FIRST = 1001;
076
077  /** The last id number in the range of action id's. */
078  public static final int ACTION_LAST = 1001;
079
080  /** An event id indicating that an action has occurred. */
081  public static final int ACTION_PERFORMED = 1001;
082
083  /**
084   * A nonlocalized string that gives more specific details of the event cause.
085   *
086   * @see #getActionCommand()
087   * @serial the command for this event
088   */
089  private final String actionCommand;
090
091  /**
092   * The bitmask of the modifiers that were pressed during the action.
093   *
094   * @see #getModifiers()
095   * @serial modifiers for this event
096   */
097  private final int modifiers;
098
099  /**
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