KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*
2  * @(#)InputEvent.java 1.34 04/06/02
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.Event JavaDoc;
11 import java.awt.Component JavaDoc;
12 import java.awt.GraphicsEnvironment JavaDoc;
13 import java.awt.Toolkit JavaDoc;
14
15 /**
16  * The root event class for all component-level input events.
17  *
18  * Input events are delivered to listeners before they are
19  * processed normally by the source where they originated.
20  * This allows listeners and component subclasses to "consume"
21  * the event so that the source will not process them in their
22  * default manner. For example, consuming mousePressed events
23  * on a Button component will prevent the Button from being
24  * activated.
25  *
26  * @author Carl Quinn
27  * @version 1.34 06/02/04
28  *
29  * @see KeyEvent
30  * @see KeyAdapter
31  * @see MouseEvent
32  * @see MouseAdapter
33  * @see MouseMotionAdapter
34  *
35  * @since 1.1
36  */

37 public abstract class InputEvent extends ComponentEvent JavaDoc {
38
39     /**
40      * The Shift key modifier constant.
41      * It is recommended that SHIFT_DOWN_MASK be used instead.
42      */

43     public static final int SHIFT_MASK = Event.SHIFT_MASK;
44
45     /**
46      * The Control key modifier constant.
47      * It is recommended that CTRL_DOWN_MASK be used instead.
48      */

49     public static final int CTRL_MASK = Event.CTRL_MASK;
50
51     /**
52      * The Meta key modifier constant.
53      * It is recommended that META_DOWN_MASK be used instead.
54      */

55     public static final int META_MASK = Event.META_MASK;
56
57     /**
58      * The Alt key modifier constant.
59      * It is recommended that ALT_DOWN_MASK be used instead.
60      */

61     public static final int ALT_MASK = Event.ALT_MASK;
62
63     /**
64      * The AltGraph key modifier constant.
65      */

66     public static final int ALT_GRAPH_MASK = 1 << 5;
67
68     /**
69      * The Mouse Button1 modifier constant.
70      * It is recommended that BUTTON1_DOWN_MASK be used instead.
71      */

72     public static final int BUTTON1_MASK = 1 << 4;
73
74     /**
75      * The Mouse Button2 modifier constant.
76      * It is recommended that BUTTON2_DOWN_MASK be used instead.
77      * Note that BUTTON2_MASK has the same value as ALT_MASK.
78      */

79     public static final int BUTTON2_MASK = Event.ALT_MASK;
80
81     /**
82      * The Mouse Button3 modifier constant.
83      * It is recommended that BUTTON3_DOWN_MASK be used instead.
84      * Note that BUTTON3_MASK has the same value as META_MASK.
85      */

86     public static final int BUTTON3_MASK = Event.META_MASK;
87
88     /**
89      * The Shift key extended modifier constant.
90      * @since 1.4
91      */

92     public static final int SHIFT_DOWN_MASK = 1 << 6;
93
94     /**
95      * The Control key extended modifier constant.
96      * @since 1.4
97      */

98     public static final int CTRL_DOWN_MASK = 1 << 7;
99
100     /**
101      * The Meta key extended modifier constant.
102      * @since 1.4
103      */

104     public static final int META_DOWN_MASK = 1 << 8;
105
106     /**
107      * The Alt key extended modifier constant.
108      * @since 1.4
109      */

110     public static final int ALT_DOWN_MASK = 1 << 9;
111
112     /**
113      * The Mouse Button1 extended modifier constant.
114      * @since 1.4
115      */

116     public static final int BUTTON1_DOWN_MASK = 1 << 10;
117
118     /**
119      * The Mouse Button2 extended modifier constant.
120      * @since 1.4
121      */

122     public static final int BUTTON2_DOWN_MASK = 1 << 11;
123
124     /**
125      * The Mouse Button3 extended modifier constant.
126      * @since 1.4
127      */

128     public static final int BUTTON3_DOWN_MASK = 1 << 12;
129
130     /**
131      * The AltGraph key extended modifier constant.
132      * @since 1.4
133      */

134     public static final int ALT_GRAPH_DOWN_MASK = 1 << 13;
135
136
137     static final int JDK_1_3_MODIFIERS = SHIFT_DOWN_MASK - 1;
138
139     /**
140      * The input event's Time stamp in UTC format. The time stamp
141      * indicates when the input event was created.
142      *
143      * @serial
144      * @see #getWhen()
145      */

146     long when;
147
148     /**
149      * The state of the modifier mask at the time the input
150      * event was fired.
151      *
152      * @serial
153      * @see #getModifiers()
154      * @see #getModifiersEx()
155      * @see java.awt.event.KeyEvent
156      * @see java.awt.event.MouseEvent
157      */

158     int modifiers;
159
160     /*
161      * A flag that indicates that this instance can be used to access
162      * the system clipboard.
163      */

164     private transient boolean canAccessSystemClipboard;
165
166     static {
167         /* ensure that the necessary native libraries are loaded */
168     NativeLibLoader.loadLibraries();
169         if (!GraphicsEnvironment.isHeadless()) {
170             initIDs();
171         }
172     }
173
174     /**
175      * Initialize JNI field and method IDs for fields that may be
176        accessed from C.
177      */

178     private static native void initIDs();
179
180     /**
181      * Constructs an InputEvent object with the specified source component,
182      * modifiers, and type.
183      * <p>Note that passing in an invalid <code>id</code> results in
184      * unspecified behavior. This method throws an
185      * <code>IllegalArgumentException</code> if <code>source</code>
186      * is <code>null</code>.
187      *
188      * @param source the object where the event originated
189      * @param id the event type
190      * @param when the time the event occurred
191      * @param modifiers represents the modifier keys and mouse buttons down
192      * while the event occurred
193      * @throws IllegalArgumentException if <code>source</code> is null
194      */

195     InputEvent(Component JavaDoc source, int id, long when, int modifiers) {
196         super(source, id);
197         this.when = when;
198         this.modifiers = modifiers;
199         canAccessSystemClipboard = canAccessSystemClipboard();
200     }
201
202     private boolean canAccessSystemClipboard() {
203         boolean b = false;
204
205         if (!GraphicsEnvironment.isHeadless()) {
206             SecurityManager JavaDoc sm = System.getSecurityManager();
207             if (sm != null) {
208                 try {
209                     sm.checkSystemClipboardAccess();
210                     b = true;
211                 } catch (SecurityException JavaDoc se) {
212                 }
213             } else {
214                 b = true;
215             }
216         }
217
218         return b;
219     }
220
221     /**
222      * Returns whether or not the Shift modifier is down on this event.
223      */

224     public boolean isShiftDown() {
225         return (modifiers & SHIFT_MASK) != 0;
226     }
227
228     /**
229      * Returns whether or not the Control modifier is down on this event.
230      */

231     public boolean isControlDown() {
232         return (modifiers & CTRL_MASK) != 0;
233     }
234
235     /**
236      * Returns whether or not the Meta modifier is down on this event.
237      */

238     public boolean isMetaDown() {
239         return (modifiers & META_MASK) != 0;
240     }
241
242     /**
243      * Returns whether or not the Alt modifier is down on this event.
244      */

245     public boolean isAltDown() {
246         return (modifiers & ALT_MASK) != 0;
247     }
248
249     /**
250      * Returns whether or not the AltGraph modifier is down on this event.
251      */

252     public boolean isAltGraphDown() {
253         return (modifiers & ALT_GRAPH_MASK) != 0;
254     }
255
256     /**
257      * Returns the timestamp of when this event occurred.
258      */

259     public long getWhen() {
260         return when;
261     }
262
263     /**
264      * Returns the modifier mask for this event.
265      */

266     public int getModifiers() {
267         return modifiers & JDK_1_3_MODIFIERS;
268     }
269
270     /**
271      * Returns the extended modifier mask for this event.
272      * Extended modifiers represent the state of all modal keys,
273      * such as ALT, CTRL, META, and the mouse buttons just after
274      * the event occurred
275      * <P>
276      * For example, if the user presses <b>button 1</b> followed by
277      * <b>button 2</b>, and then releases them in the same order,
278      * the following sequence of events is generated:
279      * <PRE>
280      * <code>MOUSE_PRESSED</code>: <code>BUTTON1_DOWN_MASK</code>
281      * <code>MOUSE_PRESSED</code>: <code>BUTTON1_DOWN_MASK | BUTTON2_DOWN_MASK</code>
282      * <code>MOUSE_RELEASED</code>: <code>BUTTON2_DOWN_MASK</code>
283      * <code>MOUSE_CLICKED</code>: <code>BUTTON2_DOWN_MASK</code>
284      * <code>MOUSE_RELEASED</code>:
285      * <code>MOUSE_CLICKED</code>:
286      * </PRE>
287      * <P>
288      * It is not recommended to compare the return value of this method
289      * using <code>==</code> because new modifiers can be added in the future.
290      * For example, the appropriate way to check that SHIFT and BUTTON1 are
291      * down, but CTRL is up is demonstrated by the following code:
292      * <PRE>
293      * int onmask = SHIFT_DOWN_MASK | BUTTON1_DOWN_MASK;
294      * int offmask = CTRL_DOWN_MASK;
295      * if (event.getModifiersEx() & (onmask | offmask) == onmask) {
296      * ...
297      * }
298      * </PRE>
299      * The above code will work even if new modifiers are added.
300      *
301      * @since 1.4
302      */

303     public int getModifiersEx() {
304         return modifiers & ~JDK_1_3_MODIFIERS;
305     }
306
307     /**
308      * Consumes this event so that it will not be processed
309      * in the default manner by the source which originated it.
310      */

311     public void consume() {
312         consumed = true;
313     }
314
315     /**
316      * Returns whether or not this event has been consumed.
317      * @see #consume
318      */

319     public boolean isConsumed() {
320         return consumed;
321     }
322
323     // state serialization compatibility with JDK 1.1
324
static final long serialVersionUID = -2482525981698309786L;
325
326     /**
327      * Returns a String describing the extended modifier keys and
328      * mouse buttons, such as "Shift", "Button1", or "Ctrl+Shift".
329      * These strings can be localized by changing the
330      * awt.properties file.
331      *
332      * @param modifiers a modifier mask describing the extended
333        * modifier keys and mouse buttons for the event
334      * @return a text description of the combination of extended
335      * modifier keys and mouse buttons that were held down
336      * during the event.
337      * @since 1.4
338      */

339     public static String JavaDoc getModifiersExText(int modifiers) {
340         StringBuffer JavaDoc buf = new StringBuffer JavaDoc();
341         if ((modifiers & InputEvent.META_DOWN_MASK) != 0) {
342             buf.append(Toolkit.getProperty("AWT.meta", "Meta"));
343             buf.append("+");
344         }
345         if ((modifiers & InputEvent.CTRL_DOWN_MASK) != 0) {
346             buf.append(Toolkit.getProperty("AWT.control", "Ctrl"));
347             buf.append("+");
348         }
349         if ((modifiers & InputEvent.ALT_DOWN_MASK) != 0) {
350             buf.append(Toolkit.getProperty("AWT.alt", "Alt"));
351             buf.append("+");
352         }
353         if ((modifiers & InputEvent.SHIFT_DOWN_MASK) != 0) {
354             buf.append(Toolkit.getProperty("AWT.shift", "Shift"));
355             buf.append("+");
356         }
357         if ((modifiers & InputEvent.ALT_GRAPH_DOWN_MASK) != 0) {
358             buf.append(Toolkit.getProperty("AWT.altGraph", "Alt Graph"));
359             buf.append("+");
360         }
361         if ((modifiers & InputEvent.BUTTON1_DOWN_MASK) != 0) {
362             buf.append(Toolkit.getProperty("AWT.button1", "Button1"));
363             buf.append("+");
364         }
365         if ((modifiers & InputEvent.BUTTON2_DOWN_MASK) != 0) {
366             buf.append(Toolkit.getProperty("AWT.button2", "Button2"));
367             buf.append("+");
368         }
369         if ((modifiers & InputEvent.BUTTON3_DOWN_MASK) != 0) {
370             buf.append(Toolkit.getProperty("AWT.button3", "Button3"));
371             buf.append("+");
372         }
373         if (buf.length() > 0) {
374             buf.setLength(buf.length()-1); // remove trailing '+'
375
}
376         return buf.toString();
377     }
378 }
379
380
Popular Tags