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  ;
11  import java.awt.Event  ;
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   {
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   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   source, int id, String   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   source, int id, String   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   source, int id, String   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   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   paramString() {
234         String   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags