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=" + <modifier string></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