1 /*
2 * Copyright (c) 1996, 2010, 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
216 * If a mouse has three enabled buttons(see {@link java.awt.MouseInfo#getNumberOfButtons() MouseInfo.getNumberOfButtons()})
217 * then the values from the left column passed into the method will return
218 * corresponding values from the right column:
219 * <PRE>
220 * <b>button </b> <b>returned mask</b>
221 * {@link MouseEvent#BUTTON1 BUTTON1} {@link MouseEvent#BUTTON1_DOWN_MASK BUTTON1_DOWN_MASK}
222 * {@link MouseEvent#BUTTON2 BUTTON2} {@link MouseEvent#BUTTON2_DOWN_MASK BUTTON2_DOWN_MASK}
223 * {@link MouseEvent#BUTTON3 BUTTON3} {@link MouseEvent#BUTTON3_DOWN_MASK BUTTON3_DOWN_MASK}
224 * </PRE>
225 * If a mouse has more than three enabled buttons then more values
226 * are admissible (4, 5, etc.). There is no assigned constants for these extended buttons.
227 * The button masks for the extra buttons returned by this method have no assigned names like the
228 * first three button masks.
229 * <p>
230 * This method has the following implementation restriction.
231 * It returns masks for a limited number of buttons only. The maximum number is
232 * implementation dependent and may vary.
233 * This limit is defined by the relevant number
234 * of buttons that may hypothetically exist on the mouse but it is greater than the
235 * {@link java.awt.MouseInfo#getNumberOfButtons() MouseInfo.getNumberOfButtons()}.
236 * <p>
237 * @throws IllegalArgumentException if {@code button} is less than zero or greater than the number
238 * of button masks reserved for buttons
239 * @since 7.0
240 * @see java.awt.MouseInfo#getNumberOfButtons()
241 * @see Toolkit#areExtraMouseButtonsEnabled()
242 * @see MouseEvent#getModifiers()
243 * @see MouseEvent#getModifiersEx()
244 */
245 public static int getMaskForButton(int button) {
246 if (button <= 0 || button > BUTTON_DOWN_MASK.length) {
247 throw new IllegalArgumentException("button doesn\'t exist " + button);
248 }
249 return BUTTON_DOWN_MASK[button - 1];
250 }
251
252 // the constant below MUST be updated if any extra modifier
253 // bits are to be added!
254 // in fact, it is undesirable to add modifier bits
255 // to the same field as this may break applications
256 // see bug# 5066958
351 SecurityManager sm = System.getSecurityManager();
352 if (sm != null) {
353 try {
354 sm.checkPermission(AWTPermissions.ACCESS_CLIPBOARD_PERMISSION);
355 b = true;
356 } catch (SecurityException se) {
357 if (logger.isLoggable(PlatformLogger.Level.FINE)) {
358 logger.fine("InputEvent.canAccessSystemClipboard() got SecurityException ", se);
359 }
360 }
361 } else {
362 b = true;
363 }
364 }
365
366 return b;
367 }
368
369 /**
370 * Returns whether or not the Shift modifier is down on this event.
371 */
372 public boolean isShiftDown() {
373 return (modifiers & SHIFT_MASK) != 0;
374 }
375
376 /**
377 * Returns whether or not the Control modifier is down on this event.
378 */
379 public boolean isControlDown() {
380 return (modifiers & CTRL_MASK) != 0;
381 }
382
383 /**
384 * Returns whether or not the Meta modifier is down on this event.
385 */
386 public boolean isMetaDown() {
387 return (modifiers & META_MASK) != 0;
388 }
389
390 /**
391 * Returns whether or not the Alt modifier is down on this event.
392 */
393 public boolean isAltDown() {
394 return (modifiers & ALT_MASK) != 0;
395 }
396
397 /**
398 * Returns whether or not the AltGraph modifier is down on this event.
399 */
400 public boolean isAltGraphDown() {
401 return (modifiers & ALT_GRAPH_MASK) != 0;
402 }
403
404 /**
405 * Returns the difference in milliseconds between the timestamp of when this event occurred and
406 * midnight, January 1, 1970 UTC.
407 */
408 public long getWhen() {
409 return when;
410 }
411
412 /**
413 * Returns the modifier mask for this event.
414 */
415 public int getModifiers() {
416 return modifiers & (JDK_1_3_MODIFIERS | HIGH_MODIFIERS);
417 }
418
419 /**
420 * Returns the extended modifier mask for this event.
421 * <P>
422 * Extended modifiers are the modifiers that ends with the _DOWN_MASK suffix,
423 * such as ALT_DOWN_MASK, BUTTON1_DOWN_MASK, and others.
424 * <P>
425 * Extended modifiers represent the state of all modal keys,
426 * such as ALT, CTRL, META, and the mouse buttons just after
427 * the event occurred.
428 * <P>
429 * For example, if the user presses <b>button 1</b> followed by
430 * <b>button 2</b>, and then releases them in the same order,
431 * the following sequence of events is generated:
432 * <PRE>
433 * <code>MOUSE_PRESSED</code>: <code>BUTTON1_DOWN_MASK</code>
434 * <code>MOUSE_PRESSED</code>: <code>BUTTON1_DOWN_MASK | BUTTON2_DOWN_MASK</code>
435 * <code>MOUSE_RELEASED</code>: <code>BUTTON2_DOWN_MASK</code>
436 * <code>MOUSE_CLICKED</code>: <code>BUTTON2_DOWN_MASK</code>
437 * <code>MOUSE_RELEASED</code>:
438 * <code>MOUSE_CLICKED</code>:
439 * </PRE>
440 * <P>
441 * It is not recommended to compare the return value of this method
442 * using <code>==</code> because new modifiers can be added in the future.
443 * For example, the appropriate way to check that SHIFT and BUTTON1 are
444 * down, but CTRL is up is demonstrated by the following code:
445 * <PRE>
446 * int onmask = SHIFT_DOWN_MASK | BUTTON1_DOWN_MASK;
447 * int offmask = CTRL_DOWN_MASK;
448 * if ((event.getModifiersEx() & (onmask | offmask)) == onmask) {
449 * ...
450 * }
451 * </PRE>
452 * The above code will work even if new modifiers are added.
453 *
454 * @since 1.4
455 */
456 public int getModifiersEx() {
457 return modifiers & ~JDK_1_3_MODIFIERS;
458 }
459
460 /**
461 * Consumes this event so that it will not be processed
462 * in the default manner by the source which originated it.
463 */
464 public void consume() {
465 consumed = true;
466 }
467
468 /**
469 * Returns whether or not this event has been consumed.
470 * @see #consume
471 */
472 public boolean isConsumed() {
473 return consumed;
474 }
475
476 // state serialization compatibility with JDK 1.1
477 static final long serialVersionUID = -2482525981698309786L;
478
479 /**
480 * Returns a String describing the extended modifier keys and
481 * mouse buttons, such as "Shift", "Button1", or "Ctrl+Shift".
482 * These strings can be localized by changing the
483 * <code>awt.properties</code> file.
484 * <p>
485 * Note that passing negative parameter is incorrect,
486 * and will cause the returning an unspecified string.
487 * Zero parameter means that no modifiers were passed and will
488 * cause the returning an empty string.
489 *
490 * @param modifiers a modifier mask describing the extended
491 * modifier keys and mouse buttons for the event
492 * @return a text description of the combination of extended
493 * modifier keys and mouse buttons that were held down
494 * during the event.
495 * @since 1.4
496 */
497 public static String getModifiersExText(int modifiers) {
498 StringBuilder buf = new StringBuilder();
499 if ((modifiers & InputEvent.META_DOWN_MASK) != 0) {
500 buf.append(Toolkit.getProperty("AWT.meta", "Meta"));
501 buf.append("+");
502 }
503 if ((modifiers & InputEvent.CTRL_DOWN_MASK) != 0) {
504 buf.append(Toolkit.getProperty("AWT.control", "Ctrl"));
505 buf.append("+");
506 }
507 if ((modifiers & InputEvent.ALT_DOWN_MASK) != 0) {
508 buf.append(Toolkit.getProperty("AWT.alt", "Alt"));
|
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
216 * If a mouse has three enabled buttons(see {@link java.awt.MouseInfo#getNumberOfButtons() MouseInfo.getNumberOfButtons()})
217 * then the values from the left column passed into the method will return
218 * corresponding values from the right column:
219 * <PRE>
220 * <b>button </b> <b>returned mask</b>
221 * {@link MouseEvent#BUTTON1 BUTTON1} {@link MouseEvent#BUTTON1_DOWN_MASK BUTTON1_DOWN_MASK}
222 * {@link MouseEvent#BUTTON2 BUTTON2} {@link MouseEvent#BUTTON2_DOWN_MASK BUTTON2_DOWN_MASK}
223 * {@link MouseEvent#BUTTON3 BUTTON3} {@link MouseEvent#BUTTON3_DOWN_MASK BUTTON3_DOWN_MASK}
224 * </PRE>
225 * If a mouse has more than three enabled buttons then more values
226 * are admissible (4, 5, etc.). There is no assigned constants for these extended buttons.
227 * The button masks for the extra buttons returned by this method have no assigned names like the
228 * first three button masks.
229 * <p>
230 * This method has the following implementation restriction.
231 * It returns masks for a limited number of buttons only. The maximum number is
232 * implementation dependent and may vary.
233 * This limit is defined by the relevant number
234 * of buttons that may hypothetically exist on the mouse but it is greater than the
235 * {@link java.awt.MouseInfo#getNumberOfButtons() MouseInfo.getNumberOfButtons()}.
236 *
237 * @return a mask for an existing mouse button.
238 * @throws IllegalArgumentException if {@code button} is less than zero or greater than the number
239 * of button masks reserved for buttons
240 * @since 7.0
241 * @see java.awt.MouseInfo#getNumberOfButtons()
242 * @see Toolkit#areExtraMouseButtonsEnabled()
243 * @see MouseEvent#getModifiers()
244 * @see MouseEvent#getModifiersEx()
245 */
246 public static int getMaskForButton(int button) {
247 if (button <= 0 || button > BUTTON_DOWN_MASK.length) {
248 throw new IllegalArgumentException("button doesn\'t exist " + button);
249 }
250 return BUTTON_DOWN_MASK[button - 1];
251 }
252
253 // the constant below MUST be updated if any extra modifier
254 // bits are to be added!
255 // in fact, it is undesirable to add modifier bits
256 // to the same field as this may break applications
257 // see bug# 5066958
352 SecurityManager sm = System.getSecurityManager();
353 if (sm != null) {
354 try {
355 sm.checkPermission(AWTPermissions.ACCESS_CLIPBOARD_PERMISSION);
356 b = true;
357 } catch (SecurityException se) {
358 if (logger.isLoggable(PlatformLogger.Level.FINE)) {
359 logger.fine("InputEvent.canAccessSystemClipboard() got SecurityException ", se);
360 }
361 }
362 } else {
363 b = true;
364 }
365 }
366
367 return b;
368 }
369
370 /**
371 * Returns whether or not the Shift modifier is down on this event.
372 * @return whether or not the Shift modifier is down on this event
373 */
374 public boolean isShiftDown() {
375 return (modifiers & SHIFT_MASK) != 0;
376 }
377
378 /**
379 * Returns whether or not the Control modifier is down on this event.
380 * @return whether or not the Control modifier is down on this event
381 */
382 public boolean isControlDown() {
383 return (modifiers & CTRL_MASK) != 0;
384 }
385
386 /**
387 * Returns whether or not the Meta modifier is down on this event.
388 * @return whether or not the Meta modifier is down on this event
389 */
390 public boolean isMetaDown() {
391 return (modifiers & META_MASK) != 0;
392 }
393
394 /**
395 * Returns whether or not the Alt modifier is down on this event.
396 * @return whether or not the Alt modifier is down on this event
397 */
398 public boolean isAltDown() {
399 return (modifiers & ALT_MASK) != 0;
400 }
401
402 /**
403 * Returns whether or not the AltGraph modifier is down on this event.
404 * @return whether or not the AltGraph modifier is down on this event
405 */
406 public boolean isAltGraphDown() {
407 return (modifiers & ALT_GRAPH_MASK) != 0;
408 }
409
410 /**
411 * Returns the difference in milliseconds between the timestamp of when this event occurred and
412 * midnight, January 1, 1970 UTC.
413 * @return the difference in milliseconds between the timestamp and midnight, January 1, 1970 UTC
414 */
415 public long getWhen() {
416 return when;
417 }
418
419 /**
420 * Returns the modifier mask for this event.
421 * @return the modifier mask for this event
422 */
423 public int getModifiers() {
424 return modifiers & (JDK_1_3_MODIFIERS | HIGH_MODIFIERS);
425 }
426
427 /**
428 * Returns the extended modifier mask for this event.
429 * <P>
430 * Extended modifiers are the modifiers that ends with the _DOWN_MASK suffix,
431 * such as ALT_DOWN_MASK, BUTTON1_DOWN_MASK, and others.
432 * <P>
433 * Extended modifiers represent the state of all modal keys,
434 * such as ALT, CTRL, META, and the mouse buttons just after
435 * the event occurred.
436 * <P>
437 * For example, if the user presses <b>button 1</b> followed by
438 * <b>button 2</b>, and then releases them in the same order,
439 * the following sequence of events is generated:
440 * <PRE>
441 * <code>MOUSE_PRESSED</code>: <code>BUTTON1_DOWN_MASK</code>
442 * <code>MOUSE_PRESSED</code>: <code>BUTTON1_DOWN_MASK | BUTTON2_DOWN_MASK</code>
443 * <code>MOUSE_RELEASED</code>: <code>BUTTON2_DOWN_MASK</code>
444 * <code>MOUSE_CLICKED</code>: <code>BUTTON2_DOWN_MASK</code>
445 * <code>MOUSE_RELEASED</code>:
446 * <code>MOUSE_CLICKED</code>:
447 * </PRE>
448 * <P>
449 * It is not recommended to compare the return value of this method
450 * using <code>==</code> because new modifiers can be added in the future.
451 * For example, the appropriate way to check that SHIFT and BUTTON1 are
452 * down, but CTRL is up is demonstrated by the following code:
453 * <PRE>
454 * int onmask = SHIFT_DOWN_MASK | BUTTON1_DOWN_MASK;
455 * int offmask = CTRL_DOWN_MASK;
456 * if ((event.getModifiersEx() & (onmask | offmask)) == onmask) {
457 * ...
458 * }
459 * </PRE>
460 * The above code will work even if new modifiers are added.
461 *
462 * @return the extended modifier mask for this event
463 * @since 1.4
464 */
465 public int getModifiersEx() {
466 return modifiers & ~JDK_1_3_MODIFIERS;
467 }
468
469 /**
470 * Consumes this event so that it will not be processed
471 * in the default manner by the source which originated it.
472 */
473 public void consume() {
474 consumed = true;
475 }
476
477 /**
478 * Returns whether or not this event has been consumed.
479 * @return whether or not this event has been consumed
480 * @see #consume
481 */
482 public boolean isConsumed() {
483 return consumed;
484 }
485
486 // state serialization compatibility with JDK 1.1
487 static final long serialVersionUID = -2482525981698309786L;
488
489 /**
490 * Returns a String describing the extended modifier keys and
491 * mouse buttons, such as "Shift", "Button1", or "Ctrl+Shift".
492 * These strings can be localized by changing the
493 * <code>awt.properties</code> file.
494 * <p>
495 * Note that passing negative parameter is incorrect,
496 * and will cause the returning an unspecified string.
497 * Zero parameter means that no modifiers were passed and will
498 * cause the returning an empty string.
499 *
500 * @return a String describing the extended modifier keys and
501 * mouse buttons
502 *
503 * @param modifiers a modifier mask describing the extended
504 * modifier keys and mouse buttons for the event
505 * @return a text description of the combination of extended
506 * modifier keys and mouse buttons that were held down
507 * during the event.
508 * @since 1.4
509 */
510 public static String getModifiersExText(int modifiers) {
511 StringBuilder buf = new StringBuilder();
512 if ((modifiers & InputEvent.META_DOWN_MASK) != 0) {
513 buf.append(Toolkit.getProperty("AWT.meta", "Meta"));
514 buf.append("+");
515 }
516 if ((modifiers & InputEvent.CTRL_DOWN_MASK) != 0) {
517 buf.append(Toolkit.getProperty("AWT.control", "Ctrl"));
518 buf.append("+");
519 }
520 if ((modifiers & InputEvent.ALT_DOWN_MASK) != 0) {
521 buf.append(Toolkit.getProperty("AWT.alt", "Alt"));
|