KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > java > awt > event > ActionEvent


1 /*
2  * @(#)ActionEvent.java 1.29 04/01/28
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */

7
8 package java.awt.event;
9
10 import java.awt.AWTEvent JavaDoc;
11 import java.awt.Event JavaDoc;
12
13 /**
14  * A semantic event which indicates that a component-defined action occurred.
15  * This high-level event is generated by a component (such as a
16  * <code>Button</code>) when
17  * the component-specific action occurs (such as being pressed).
18  * The event is passed to every every <code>ActionListener</code> object
19  * that registered to receive such events using the component's
20  * <code>addActionListener</code> method.
21  * <p>
22  * <b>Note:</b> To invoke an <code>ActionEvent</code> on a
23  * <code>Button</code> using the keyboard, use the Space bar.
24  * <P>
25  * The object that implements the <code>ActionListener</code> interface
26  * gets this <code>ActionEvent</code> when the event occurs. The listener
27  * is therefore spared the details of processing individual mouse movements
28  * and mouse clicks, and can instead process a "meaningful" (semantic)
29  * event like "button pressed".
30  *
31  * @see ActionListener
32  * @see <a HREF="http://java.sun.com/docs/books/tutorial/post1.0/ui/eventmodel.html">Tutorial: Java 1.1 Event Model</a>
33  * @see <a HREF="http://www.awl.com/cp/javaseries/jcl1_2.html">Reference: The Java Class Libraries (update file)</a>
34  *
35  * @author Carl Quinn
36  * @version 1.29 01/28/04
37  * @since 1.1
38  */

39 public class ActionEvent extends AWTEvent JavaDoc {
40
41     /**
42      * The shift modifier. An indicator that the shift key was held
43      * down during the event.
44      */

45     public static final int SHIFT_MASK = Event.SHIFT_MASK;
46
47     /**
48      * The control modifier. An indicator that the control key was held
49      * down during the event.
50      */

51     public static final int CTRL_MASK = Event.CTRL_MASK;
52
53     /**
54      * The meta modifier. An indicator that the meta key was held
55      * down during the event.
56      */

57     public static final int META_MASK = Event.META_MASK;
58
59     /**
60      * The alt modifier. An indicator that the alt key was held
61      * down during the event.
62      */

63     public static final int ALT_MASK = Event.ALT_MASK;
64
65
66     /**
67      * The first number in the range of ids used for action events.
68      */

69     public static final int ACTION_FIRST = 1001;
70
71     /**
72      * The last number in the range of ids used for action events.
73      */

74     public static final int ACTION_LAST = 1001;
75
76     /**
77      * This event id indicates that a meaningful action occured.
78      */

79     public static final int ACTION_PERFORMED = ACTION_FIRST; //Event.ACTION_EVENT
80

81     /**
82      * The nonlocalized string that gives more details
83      * of what actually caused the event.
84      * This information is very specific to the component
85      * that fired it.
86
87      * @serial
88      * @see #getActionCommand
89      */

90     String JavaDoc actionCommand;
91
92     /**
93      * Timestamp of when this event occurred. Because an ActionEvent is a high-
94      * level, semantic event, the timestamp is typically the same as an
95      * underlying InputEvent.
96      *
97      * @serial
98      * @see #getWhen
99      */

100     long when;
101
102     /**
103      * This represents the key modifier that was selected,
104      * and is used to determine the state of the selected key.
105      * If no modifier has been selected it will default to
106      * zero.
107      *
108      * @serial
109      * @see #getModifiers
110      */

111     int modifiers;
112
113     /*
114      * JDK 1.1 serialVersionUID
115      */

116     private static final long serialVersionUID = -7671078796273832149L;
117
118     /**
119      * Constructs an <code>ActionEvent</code> object.
120      * <p>
121      * Note that passing in an invalid <code>id</code> results in
122      * unspecified behavior. This method throws an
123      * <code>IllegalArgumentException</code> if <code>source</code>
124      * is <code>null</code>.
125      * A <code>null</code> <code>command</code> string is legal,
126      * but not recommended.
127      *
128      * @param source the object that originated the event
129      * @param id an integer that identifies the event
130      * @param command a string that may specify a command (possibly one
131      * of several) associated with the event
132      * @throws IllegalArgumentException if <code>source</code> is null
133      */

134     public ActionEvent(Object JavaDoc source, int id, String JavaDoc command) {
135         this(source, id, command, 0);
136     }
137
138     /**
139      * Constructs an <code>ActionEvent</code> object with modifier keys.
140      * <p>
141      * Note that passing in an invalid <code>id</code> results in
142      * unspecified behavior. 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      * @param command a string that may specify a command (possibly one
151      * of several) associated with the event
152      * @param modifiers the modifier keys held down during this action
153      * @throws IllegalArgumentException if <code>source</code> is null
154      */

155     public ActionEvent(Object JavaDoc source, int id, String JavaDoc command, int modifiers) {
156         this(source, id, command, 0, modifiers);
157     }
158
159     /**
160      * Constructs an <code>ActionEvent</code> object with the specified
161      * modifier keys and timestamp.
162      * <p>
163      * Note that passing in an invalid <code>id</code> results in
164      * unspecified behavior. This method throws an
165      * <code>IllegalArgumentException</code> if <code>source</code>
166      * is <code>null</code>.
167      * A <code>null</code> <code>command</code> string is legal,
168      * but not recommended.
169      *
170      * @param source the object that originated the event
171      * @param id an integer that identifies the event
172      * @param command a string that may specify a command (possibly one
173      * of several) associated with the event
174      * @param when the time the event occurred
175      * @param modifiers the modifier keys held down during this action
176      * @throws IllegalArgumentException if <code>source</code> is null
177      *
178      * @since 1.4
179      */

180     public ActionEvent(Object JavaDoc source, int id, String JavaDoc command, long when,
181                        int modifiers) {
182         super(source, id);
183         this.actionCommand = command;
184         this.when = when;
185         this.modifiers = modifiers;
186     }
187         
188     /**
189      * Returns the command string associated with this action.
190      * This string allows a "modal" component to specify one of several
191      * commands, depending on its state. For example, a single button might
192      * toggle between "show details" and "hide details". The source object
193      * and the event would be the same in each case, but the command string
194      * would identify the intended action.
195      * <p>
196      * Note that if a <code>null</code> command string was passed
197      * to the constructor for this <code>ActionEvent</code>, this
198      * this method returns <code>null</code>.
199      *
200      * @return the string identifying the command for this event
201      */

202     public String JavaDoc getActionCommand() {
203         return actionCommand;
204     }
205
206     /**
207      * Returns the timestamp of when this event occurred. Because an
208      * ActionEvent is a high-level, semantic event, the timestamp is typically
209      * the same as an underlying InputEvent.
210      *
211      * @return this event's timestamp
212      * @since 1.4
213      */

214     public long getWhen() {
215         return when;
216     }
217
218     /**
219      * Returns the modifier keys held down during this action event.
220      *
221      * @return the bitwise-or of the modifier constants
222      */

223     public int getModifiers() {
224         return modifiers;
225     }
226
227     /**
228      * Returns a parameter string identifying this action event.
229      * This method is useful for event-logging and for debugging.
230      *
231      * @return a string identifying the event and its associated command
232      */

233     public String JavaDoc paramString() {
234         String JavaDoc typeStr;
235         switch(id) {
236           case ACTION_PERFORMED:
237               typeStr = "ACTION_PERFORMED";
238               break;
239           default:
240               typeStr = "unknown type";
241         }
242         return typeStr + ",cmd="+actionCommand+",when="+when+",modifiers="+
243             KeyEvent.getKeyModifiersText(modifiers);
244     }
245 }
246
Popular Tags