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