View Javadoc
1   /*
2    * Copyright (c) 1996, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package java.awt.event;
27  
28  import java.awt.AWTEvent;
29  import java.awt.Event;
30  import java.lang.annotation.Native;
31  
32  /**
33   * A semantic event which indicates that a component-defined action occurred.
34   * This high-level event is generated by a component (such as a
35   * <code>Button</code>) when
36   * the component-specific action occurs (such as being pressed).
37   * The event is passed to every <code>ActionListener</code> object
38   * that registered to receive such events using the component's
39   * <code>addActionListener</code> method.
40   * <p>
41   * <b>Note:</b> To invoke an <code>ActionEvent</code> on a
42   * <code>Button</code> using the keyboard, use the Space bar.
43   * <P>
44   * The object that implements the <code>ActionListener</code> interface
45   * gets this <code>ActionEvent</code> when the event occurs. The listener
46   * is therefore spared the details of processing individual mouse movements
47   * and mouse clicks, and can instead process a "meaningful" (semantic)
48   * event like "button pressed".
49   * <p>
50   * An unspecified behavior will be caused if the {@code id} parameter
51   * of any particular {@code ActionEvent} instance is not
52   * in the range from {@code ACTION_FIRST} to {@code ACTION_LAST}.
53   *
54   * @see ActionListener
55   * @see <a href="http://docs.oracle.com/javase/tutorial/uiswing/events/actionlistener.html">Tutorial: How to Write an Action Listener</a>
56   *
57   * @author Carl Quinn
58   * @since 1.1
59   */
60  public class ActionEvent extends AWTEvent {
61  
62      /**
63       * The shift modifier. An indicator that the shift key was held
64       * down during the event.
65       */
66      public static final int SHIFT_MASK          = Event.SHIFT_MASK;
67  
68      /**
69       * The control modifier. An indicator that the control key was held
70       * down during the event.
71       */
72      public static final int CTRL_MASK           = Event.CTRL_MASK;
73  
74      /**
75       * The meta modifier. An indicator that the meta key was held
76       * down during the event.
77       */
78      public static final int META_MASK           = Event.META_MASK;
79  
80      /**
81       * The alt modifier. An indicator that the alt key was held
82       * down during the event.
83       */
84      public static final int ALT_MASK            = Event.ALT_MASK;
85  
86  
87      /**
88       * The first number in the range of ids used for action events.
89       */
90      public static final int ACTION_FIRST                = 1001;
91  
92      /**
93       * The last number in the range of ids used for action events.
94       */
95      public static final int ACTION_LAST                 = 1001;
96  
97      /**
98       * This event id indicates that a meaningful action occurred.
99       */
100     @Native public static final int ACTION_PERFORMED    = ACTION_FIRST; //Event.ACTION_EVENT
101 
102     /**
103      * The nonlocalized string that gives more details
104      * of what actually caused the event.
105      * This information is very specific to the component
106      * that fired it.
107 
108      * @serial
109      * @see #getActionCommand
110      */
111     String actionCommand;
112 
113     /**
114      * Timestamp of when this event occurred. Because an ActionEvent is a high-
115      * level, semantic event, the timestamp is typically the same as an
116      * underlying InputEvent.
117      *
118      * @serial
119      * @see #getWhen
120      */
121     long when;
122 
123     /**
124      * This represents the key modifier that was selected,
125      * and is used to determine the state of the selected key.
126      * If no modifier has been selected it will default to
127      * zero.
128      *
129      * @serial
130      * @see #getModifiers
131      */
132     int modifiers;
133 
134     /*
135      * JDK 1.1 serialVersionUID
136      */
137     private static final long serialVersionUID = -7671078796273832149L;
138 
139     /**
140      * Constructs an <code>ActionEvent</code> object.
141      * <p>
142      * This method throws an
143      * <code>IllegalArgumentException</code> if <code>source</code>
144      * is <code>null</code>.
145      * A <code>null</code> <code>command</code> string is legal,
146      * but not recommended.
147      *
148      * @param source  The object that originated the event
149      * @param id      An integer that identifies the event.
150      *                     For information on allowable values, see
151      *                     the class description for {@link ActionEvent}
152      * @param command A string that may specify a command (possibly one
153      *                of several) associated with the event
154      * @throws IllegalArgumentException if <code>source</code> is null
155      * @see #getSource()
156      * @see #getID()
157      * @see #getActionCommand()
158      */
159     public ActionEvent(Object source, int id, String command) {
160         this(source, id, command, 0);
161     }
162 
163     /**
164      * Constructs an <code>ActionEvent</code> object with modifier keys.
165      * <p>
166      * This method throws an
167      * <code>IllegalArgumentException</code> if <code>source</code>
168      * is <code>null</code>.
169      * A <code>null</code> <code>command</code> string is legal,
170      * but not recommended.
171      *
172      * @param source  The object that originated the event
173      * @param id      An integer that identifies the event.
174      *                     For information on allowable values, see
175      *                     the class description for {@link ActionEvent}
176      * @param command A string that may specify a command (possibly one
177      *                of several) associated with the event
178      * @param modifiers The modifier keys down during event
179      *                  (shift, ctrl, alt, meta).
180      *                  Passing negative parameter is not recommended.
181      *                  Zero value means that no modifiers were passed
182      * @throws IllegalArgumentException if <code>source</code> is null
183      * @see #getSource()
184      * @see #getID()
185      * @see #getActionCommand()
186      * @see #getModifiers()
187      */
188     public ActionEvent(Object source, int id, String command, int modifiers) {
189         this(source, id, command, 0, modifiers);
190     }
191 
192     /**
193      * Constructs an <code>ActionEvent</code> object with the specified
194      * modifier keys and timestamp.
195      * <p>
196      * This method throws an
197      * <code>IllegalArgumentException</code> if <code>source</code>
198      * is <code>null</code>.
199      * A <code>null</code> <code>command</code> string is legal,
200      * but not recommended.
201      *
202      * @param source    The object that originated the event
203      * @param id      An integer that identifies the event.
204      *                     For information on allowable values, see
205      *                     the class description for {@link ActionEvent}
206      * @param command A string that may specify a command (possibly one
207      *                of several) associated with the event
208      * @param modifiers The modifier keys down during event
209      *                  (shift, ctrl, alt, meta).
210      *                  Passing negative parameter is not recommended.
211      *                  Zero value means that no modifiers were passed
212      * @param when   A long that gives the time the event occurred.
213      *               Passing negative or zero value
214      *               is not recommended
215      * @throws IllegalArgumentException if <code>source</code> is null
216      * @see #getSource()
217      * @see #getID()
218      * @see #getActionCommand()
219      * @see #getModifiers()
220      * @see #getWhen()
221      *
222      * @since 1.4
223      */
224     public ActionEvent(Object source, int id, String command, long when,
225                        int modifiers) {
226         super(source, id);
227         this.actionCommand = command;
228         this.when = when;
229         this.modifiers = modifiers;
230     }
231 
232     /**
233      * Returns the command string associated with this action.
234      * This string allows a "modal" component to specify one of several
235      * commands, depending on its state. For example, a single button might
236      * toggle between "show details" and "hide details". The source object
237      * and the event would be the same in each case, but the command string
238      * would identify the intended action.
239      * <p>
240      * Note that if a <code>null</code> command string was passed
241      * to the constructor for this <code>ActionEvent</code>, this
242      * this method returns <code>null</code>.
243      *
244      * @return the string identifying the command for this event
245      */
246     public String getActionCommand() {
247         return actionCommand;
248     }
249 
250     /**
251      * Returns the timestamp of when this event occurred. Because an
252      * ActionEvent is a high-level, semantic event, the timestamp is typically
253      * the same as an underlying InputEvent.
254      *
255      * @return this event's timestamp
256      * @since 1.4
257      */
258     public long getWhen() {
259         return when;
260     }
261 
262     /**
263      * Returns the modifier keys held down during this action event.
264      *
265      * @return the bitwise-or of the modifier constants
266      */
267     public int getModifiers() {
268         return modifiers;
269     }
270 
271     /**
272      * Returns a parameter string identifying this action event.
273      * This method is useful for event-logging and for debugging.
274      *
275      * @return a string identifying the event and its associated command
276      */
277     public String paramString() {
278         String typeStr;
279         switch(id) {
280           case ACTION_PERFORMED:
281               typeStr = "ACTION_PERFORMED";
282               break;
283           default:
284               typeStr = "unknown type";
285         }
286         return typeStr + ",cmd="+actionCommand+",when="+when+",modifiers="+
287             KeyEvent.getKeyModifiersText(modifiers);
288     }
289 }