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 gnu.java.lang.CPStringBuilder;
042    
043    import java.awt.AWTEvent;
044    import 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     */
055    public 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