001 /*
002 * Copyright 1996-2007 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.awt.event;
027
028 import java.awt.Event;
029 import java.awt.Component;
030 import java.awt.GraphicsEnvironment;
031 import java.awt.Toolkit;
032 import java.util.logging.Logger;
033 import java.util.logging.Level;
034
035 /**
036 * The root event class for all component-level input events.
037 *
038 * Input events are delivered to listeners before they are
039 * processed normally by the source where they originated.
040 * This allows listeners and component subclasses to "consume"
041 * the event so that the source will not process them in their
042 * default manner. For example, consuming mousePressed events
043 * on a Button component will prevent the Button from being
044 * activated.
045 *
046 * @author Carl Quinn
047 * @version 1.46 06/05/07
048 *
049 * @see KeyEvent
050 * @see KeyAdapter
051 * @see MouseEvent
052 * @see MouseAdapter
053 * @see MouseMotionAdapter
054 *
055 * @since 1.1
056 */
057 public abstract class InputEvent extends ComponentEvent {
058 private static final Logger log = Logger
059 .getLogger("java.awt.event.InputEvent");
060
061 /**
062 * The Shift key modifier constant.
063 * It is recommended that SHIFT_DOWN_MASK be used instead.
064 */
065 public static final int SHIFT_MASK = Event.SHIFT_MASK;
066
067 /**
068 * The Control key modifier constant.
069 * It is recommended that CTRL_DOWN_MASK be used instead.
070 */
071 public static final int CTRL_MASK = Event.CTRL_MASK;
072
073 /**
074 * The Meta key modifier constant.
075 * It is recommended that META_DOWN_MASK be used instead.
076 */
077 public static final int META_MASK = Event.META_MASK;
078
079 /**
080 * The Alt key modifier constant.
081 * It is recommended that ALT_DOWN_MASK be used instead.
082 */
083 public static final int ALT_MASK = Event.ALT_MASK;
084
085 /**
086 * The AltGraph key modifier constant.
087 */
088 public static final int ALT_GRAPH_MASK = 1 << 5;
089
090 /**
091 * The Mouse Button1 modifier constant.
092 * It is recommended that BUTTON1_DOWN_MASK be used instead.
093 */
094 public static final int BUTTON1_MASK = 1 << 4;
095
096 /**
097 * The Mouse Button2 modifier constant.
098 * It is recommended that BUTTON2_DOWN_MASK be used instead.
099 * Note that BUTTON2_MASK has the same value as ALT_MASK.
100 */
101 public static final int BUTTON2_MASK = Event.ALT_MASK;
102
103 /**
104 * The Mouse Button3 modifier constant.
105 * It is recommended that BUTTON3_DOWN_MASK be used instead.
106 * Note that BUTTON3_MASK has the same value as META_MASK.
107 */
108 public static final int BUTTON3_MASK = Event.META_MASK;
109
110 /**
111 * The Shift key extended modifier constant.
112 * @since 1.4
113 */
114 public static final int SHIFT_DOWN_MASK = 1 << 6;
115
116 /**
117 * The Control key extended modifier constant.
118 * @since 1.4
119 */
120 public static final int CTRL_DOWN_MASK = 1 << 7;
121
122 /**
123 * The Meta key extended modifier constant.
124 * @since 1.4
125 */
126 public static final int META_DOWN_MASK = 1 << 8;
127
128 /**
129 * The Alt key extended modifier constant.
130 * @since 1.4
131 */
132 public static final int ALT_DOWN_MASK = 1 << 9;
133
134 /**
135 * The Mouse Button1 extended modifier constant.
136 * @since 1.4
137 */
138 public static final int BUTTON1_DOWN_MASK = 1 << 10;
139
140 /**
141 * The Mouse Button2 extended modifier constant.
142 * @since 1.4
143 */
144 public static final int BUTTON2_DOWN_MASK = 1 << 11;
145
146 /**
147 * The Mouse Button3 extended modifier constant.
148 * @since 1.4
149 */
150 public static final int BUTTON3_DOWN_MASK = 1 << 12;
151
152 /**
153 * The AltGraph key extended modifier constant.
154 * @since 1.4
155 */
156 public static final int ALT_GRAPH_DOWN_MASK = 1 << 13;
157
158 // the constant below MUST be updated if any extra modifier
159 // bits are to be added!
160 // in fact, it is undesirable to add modifier bits
161 // to the same field as this may break applications
162 // see bug# 5066958
163
164 static final int FIRST_HIGH_BIT = 1 << 14;
165
166 static final int JDK_1_3_MODIFIERS = SHIFT_DOWN_MASK - 1;
167 static final int HIGH_MODIFIERS = ~(FIRST_HIGH_BIT - 1);
168
169 /**
170 * The input event's Time stamp in UTC format. The time stamp
171 * indicates when the input event was created.
172 *
173 * @serial
174 * @see #getWhen()
175 */
176 long when;
177
178 /**
179 * The state of the modifier mask at the time the input
180 * event was fired.
181 *
182 * @serial
183 * @see #getModifiers()
184 * @see #getModifiersEx()
185 * @see java.awt.event.KeyEvent
186 * @see java.awt.event.MouseEvent
187 */
188 int modifiers;
189
190 /*
191 * A flag that indicates that this instance can be used to access
192 * the system clipboard.
193 */
194 private transient boolean canAccessSystemClipboard;
195
196 static {
197 /* ensure that the necessary native libraries are loaded */
198 NativeLibLoader.loadLibraries();
199 if (!GraphicsEnvironment.isHeadless()) {
200 initIDs();
201 }
202 }
203
204 /**
205 * Initialize JNI field and method IDs for fields that may be
206 accessed from C.
207 */
208 private static native void initIDs();
209
210 /**
211 * Constructs an InputEvent object with the specified source component,
212 * modifiers, and type.
213 * <p>Note that passing in an invalid <code>id</code> results in
214 * unspecified behavior. This method throws an
215 * <code>IllegalArgumentException</code> if <code>source</code>
216 * is <code>null</code>.
217 *
218 * @param source the object where the event originated
219 * @param id the event type
220 * @param when the time the event occurred
221 * @param modifiers represents the modifier keys and mouse buttons down
222 * while the event occurred
223 * @throws IllegalArgumentException if <code>source</code> is null
224 */
225 InputEvent(Component source, int id, long when, int modifiers) {
226 super (source, id);
227 this .when = when;
228 this .modifiers = modifiers;
229 canAccessSystemClipboard = canAccessSystemClipboard();
230 }
231
232 private boolean canAccessSystemClipboard() {
233 boolean b = false;
234
235 if (!GraphicsEnvironment.isHeadless()) {
236 SecurityManager sm = System.getSecurityManager();
237 if (sm != null) {
238 try {
239 sm.checkSystemClipboardAccess();
240 b = true;
241 } catch (SecurityException se) {
242 if (log.isLoggable(Level.FINE)) {
243 log
244 .log(
245 Level.FINE,
246 "InputEvent.canAccessSystemClipboard() got SecurityException ",
247 se);
248 }
249 }
250 } else {
251 b = true;
252 }
253 }
254
255 return b;
256 }
257
258 /**
259 * Returns whether or not the Shift modifier is down on this event.
260 */
261 public boolean isShiftDown() {
262 return (modifiers & SHIFT_MASK) != 0;
263 }
264
265 /**
266 * Returns whether or not the Control modifier is down on this event.
267 */
268 public boolean isControlDown() {
269 return (modifiers & CTRL_MASK) != 0;
270 }
271
272 /**
273 * Returns whether or not the Meta modifier is down on this event.
274 */
275 public boolean isMetaDown() {
276 return (modifiers & META_MASK) != 0;
277 }
278
279 /**
280 * Returns whether or not the Alt modifier is down on this event.
281 */
282 public boolean isAltDown() {
283 return (modifiers & ALT_MASK) != 0;
284 }
285
286 /**
287 * Returns whether or not the AltGraph modifier is down on this event.
288 */
289 public boolean isAltGraphDown() {
290 return (modifiers & ALT_GRAPH_MASK) != 0;
291 }
292
293 /**
294 * Returns the timestamp of when this event occurred.
295 */
296 public long getWhen() {
297 return when;
298 }
299
300 /**
301 * Returns the modifier mask for this event.
302 */
303 public int getModifiers() {
304 return modifiers & (JDK_1_3_MODIFIERS | HIGH_MODIFIERS);
305 }
306
307 /**
308 * Returns the extended modifier mask for this event.
309 * Extended modifiers represent the state of all modal keys,
310 * such as ALT, CTRL, META, and the mouse buttons just after
311 * the event occurred
312 * <P>
313 * For example, if the user presses <b>button 1</b> followed by
314 * <b>button 2</b>, and then releases them in the same order,
315 * the following sequence of events is generated:
316 * <PRE>
317 * <code>MOUSE_PRESSED</code>: <code>BUTTON1_DOWN_MASK</code>
318 * <code>MOUSE_PRESSED</code>: <code>BUTTON1_DOWN_MASK | BUTTON2_DOWN_MASK</code>
319 * <code>MOUSE_RELEASED</code>: <code>BUTTON2_DOWN_MASK</code>
320 * <code>MOUSE_CLICKED</code>: <code>BUTTON2_DOWN_MASK</code>
321 * <code>MOUSE_RELEASED</code>:
322 * <code>MOUSE_CLICKED</code>:
323 * </PRE>
324 * <P>
325 * It is not recommended to compare the return value of this method
326 * using <code>==</code> because new modifiers can be added in the future.
327 * For example, the appropriate way to check that SHIFT and BUTTON1 are
328 * down, but CTRL is up is demonstrated by the following code:
329 * <PRE>
330 * int onmask = SHIFT_DOWN_MASK | BUTTON1_DOWN_MASK;
331 * int offmask = CTRL_DOWN_MASK;
332 * if ((event.getModifiersEx() & (onmask | offmask)) == onmask) {
333 * ...
334 * }
335 * </PRE>
336 * The above code will work even if new modifiers are added.
337 *
338 * @since 1.4
339 */
340 public int getModifiersEx() {
341 return modifiers & ~JDK_1_3_MODIFIERS;
342 }
343
344 /**
345 * Consumes this event so that it will not be processed
346 * in the default manner by the source which originated it.
347 */
348 public void consume() {
349 consumed = true;
350 }
351
352 /**
353 * Returns whether or not this event has been consumed.
354 * @see #consume
355 */
356 public boolean isConsumed() {
357 return consumed;
358 }
359
360 // state serialization compatibility with JDK 1.1
361 static final long serialVersionUID = -2482525981698309786L;
362
363 /**
364 * Returns a String describing the extended modifier keys and
365 * mouse buttons, such as "Shift", "Button1", or "Ctrl+Shift".
366 * These strings can be localized by changing the
367 * awt.properties file.
368 *
369 * @param modifiers a modifier mask describing the extended
370 * modifier keys and mouse buttons for the event
371 * @return a text description of the combination of extended
372 * modifier keys and mouse buttons that were held down
373 * during the event.
374 * @since 1.4
375 */
376 public static String getModifiersExText(int modifiers) {
377 StringBuilder buf = new StringBuilder();
378 if ((modifiers & InputEvent.META_DOWN_MASK) != 0) {
379 buf.append(Toolkit.getProperty("AWT.meta", "Meta"));
380 buf.append("+");
381 }
382 if ((modifiers & InputEvent.CTRL_DOWN_MASK) != 0) {
383 buf.append(Toolkit.getProperty("AWT.control", "Ctrl"));
384 buf.append("+");
385 }
386 if ((modifiers & InputEvent.ALT_DOWN_MASK) != 0) {
387 buf.append(Toolkit.getProperty("AWT.alt", "Alt"));
388 buf.append("+");
389 }
390 if ((modifiers & InputEvent.SHIFT_DOWN_MASK) != 0) {
391 buf.append(Toolkit.getProperty("AWT.shift", "Shift"));
392 buf.append("+");
393 }
394 if ((modifiers & InputEvent.ALT_GRAPH_DOWN_MASK) != 0) {
395 buf
396 .append(Toolkit.getProperty("AWT.altGraph",
397 "Alt Graph"));
398 buf.append("+");
399 }
400 if ((modifiers & InputEvent.BUTTON1_DOWN_MASK) != 0) {
401 buf.append(Toolkit.getProperty("AWT.button1", "Button1"));
402 buf.append("+");
403 }
404 if ((modifiers & InputEvent.BUTTON2_DOWN_MASK) != 0) {
405 buf.append(Toolkit.getProperty("AWT.button2", "Button2"));
406 buf.append("+");
407 }
408 if ((modifiers & InputEvent.BUTTON3_DOWN_MASK) != 0) {
409 buf.append(Toolkit.getProperty("AWT.button3", "Button3"));
410 buf.append("+");
411 }
412 if (buf.length() > 0) {
413 buf.setLength(buf.length() - 1); // remove trailing '+'
414 }
415 return buf.toString();
416 }
417 }
|