001: /*
002: * @(#)InputEvent.java 1.28 05/01/04
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: *
026: */
027:
028: package java.awt.event;
029:
030: import java.awt.Component;
031: import java.awt.GraphicsEnvironment;
032: import java.awt.Toolkit;
033:
034: /**
035: * The root event class for all component-level input events.
036: *
037: * Input events are delivered to listeners before they are
038: * processed normally by the source where they originated.
039: * This allows listeners and component subclasses to "consume"
040: * the event so that the source will not process them in their
041: * default manner. For example, consuming mousePressed events
042: * on a Button component will prevent the Button from being
043: * activated.
044: *
045: * @author Carl Quinn
046: * @version 1.22, 08/19/02
047: *
048: * @see KeyEvent
049: * @see KeyAdapter
050: * @see MouseEvent
051: * @see MouseAdapter
052: * @see MouseMotionAdapter
053: *
054: * @since 1.1
055: */
056: public abstract class InputEvent extends ComponentEvent {
057: /**
058: * The shift key modifier constant.
059: * It is recommended that SHIFT_DOWN_MASK to be used instead.
060: */
061: public static final int SHIFT_MASK = 1 << 0;
062: /**
063: * The control key modifier constant.
064: * It is recommended that CTRL_DOWN_MASK to be used instead.
065: */
066: public static final int CTRL_MASK = 1 << 1;
067: /**
068: * The meta key modifier constant.
069: * It is recommended that META_DOWN_MASK to be used instead.
070: */
071: public static final int META_MASK = 1 << 2;
072: /**
073: * The alt key modifier constant.
074: * It is recommended that ALT_DOWN_MASK to be used instead.
075: */
076: public static final int ALT_MASK = 1 << 3;
077: /**
078: * The alt-graph key modifier constant.
079: */
080: public static final int ALT_GRAPH_MASK = 1 << 5;
081: /**
082: * The mouse button1 modifier constant.
083: * It is recommended that BUTTON1_DOWN_MASK to be used instead.
084: */
085: public static final int BUTTON1_MASK = 1 << 4;
086: /**
087: * The mouse button2 modifier constant.
088: * It is recommended that BUTTON2_DOWN_MASK to be used instead.
089: */
090: public static final int BUTTON2_MASK = ALT_MASK;
091: /**
092: * The mouse button3 modifier constant.
093: * It is recommended that BUTTON3_DOWN_MASK to be used instead.
094: */
095: public static final int BUTTON3_MASK = META_MASK;
096: /**
097: * The SHIFT key extended modifier constant.
098: * @since 1.4
099: */
100: public static final int SHIFT_DOWN_MASK = 1 << 6;
101:
102: /**
103: * The CTRL key extended modifier constant.
104: * @since 1.4
105: */
106: public static final int CTRL_DOWN_MASK = 1 << 7;
107:
108: /**
109: * The META key extended modifier constant.
110: * @since 1.4
111: */
112: public static final int META_DOWN_MASK = 1 << 8;
113:
114: /**
115: * The ALT key extended modifier constant.
116: * @since 1.4
117: */
118: public static final int ALT_DOWN_MASK = 1 << 9;
119:
120: /**
121: * The mouse button1 extended modifier constant.
122: * @since 1.4
123: */
124: public static final int BUTTON1_DOWN_MASK = 1 << 10;
125:
126: /**
127: * The mouse button2 extended modifier constant.
128: * @since 1.4
129: */
130: public static final int BUTTON2_DOWN_MASK = 1 << 11;
131:
132: /**
133: * The mouse button3 extended modifier constant.
134: * @since 1.4
135: */
136: public static final int BUTTON3_DOWN_MASK = 1 << 12;
137:
138: /**
139: * The alt-graph key extended modifier constant.
140: * @since 1.4
141: */
142: public static final int ALT_GRAPH_DOWN_MASK = 1 << 13;
143:
144: static final int JDK_1_3_MODIFIERS = SHIFT_DOWN_MASK - 1;
145:
146: /**
147: * The input events Time stamp. The time stamp is in
148: * UTC format that indicates when the input event was
149: * created.
150: *
151: * @serial
152: * @see getWhen()
153: */
154: long when;
155: /**
156: * The state of the modifier key at the time the input
157: * event was fired.
158: *
159: * @serial
160: * @see getModifiers()
161: * @see java.awt.event.MouseEvent
162: */
163: int modifiers;
164:
165: /**
166: * Constructs an InputEvent object with the specified source component,
167: * modifiers, and type.
168: * @param source the object where the event originated
169: * @id the event type
170: * @when the time the event occurred
171: * @modifiers the modifier keys down while event occurred
172: */
173: InputEvent(Component source, int id, long when, int modifiers) {
174: super (source, id);
175: this .when = when;
176: this .modifiers = modifiers;
177: }
178:
179: /**
180: * Returns whether or not the Shift modifier is down on this event.
181: */
182: public boolean isShiftDown() {
183: return (modifiers & SHIFT_MASK) != 0;
184: }
185:
186: /**
187: * Returns whether or not the Control modifier is down on this event.
188: */
189: public boolean isControlDown() {
190: return (modifiers & CTRL_MASK) != 0;
191: }
192:
193: /**
194: * Returns whether or not the Meta modifier is down on this event.
195: */
196: public boolean isMetaDown() {
197: return (modifiers & META_MASK) != 0;
198: }
199:
200: /**
201: * Returns whether or not the Alt modifier is down on this event.
202: */
203: public boolean isAltDown() {
204: return (modifiers & ALT_MASK) != 0;
205: }
206:
207: /**
208: * Returns whether or not the Alt-Graph modifier is down on this event.
209: */
210: public boolean isAltGraphDown() {
211: return (modifiers & ALT_GRAPH_MASK) != 0;
212: }
213:
214: /**
215: * Returns the timestamp of when this event occurred.
216: */
217: public long getWhen() {
218: return when;
219: }
220:
221: /**
222: * Returns the modifiers flag for this event.
223: */
224: public int getModifiers() {
225: return modifiers & JDK_1_3_MODIFIERS;
226: }
227:
228: /**
229: * Returns the extended modifiers flag for this event.
230: * Extended modifiers represent state of all modal keys,
231: * such of ALT, CTRL, META and mouse buttons just after event occured
232: * <P>
233: * For example, if the user presses <b>button 1</b> followed by
234: * <b>button 2</b>, and then releases them in the same order,
235: * the following sequence of events is generated:
236: * <PRE>
237: * <code>MOUSE_PRESSED</code>: <code>BUTTON1_DOWN_MASK</code>
238: * <code>MOUSE_PRESSED</code>: <code>BUTTON1_DOWN_MASK | BUTTON2_DOWN_MASK</code>
239: * <code>MOUSE_RELEASED</code>: <code>BUTTON2_DOWN_MASK</code>
240: * <code>MOUSE_CLICKED</code>: <code>BUTTON2_DOWN_MASK</code>
241: * <code>MOUSE_RELEASED</code>:
242: * <code>MOUSE_CLICKED</code>:
243: * </PRE>
244: * <P>
245: * It is not recommended to compare the return value of this method
246: * via <code>==</code> because new modifiers can be added in the future.
247: * For example, the appropriate way to check that SHIFT and BUTTON1 are
248: * down, but CTRL is up is demonstrated by the following code:
249: * <PRE>
250: * int onmask = SHIFT_DOWN_MASK | BUTTON1_DOWN_MASK;
251: * int offmask = CTRL_DOWN_MASK;
252: * if (event.getModifiersEx() & (onmask | offmask) == onmask) {
253: * ...
254: * }
255: * </PRE>
256: * The above code will work even if new modifiers are added.
257: * @since 1.4
258: */
259:
260: public int getModifiersEx() {
261: return modifiers & ~JDK_1_3_MODIFIERS;
262: }
263:
264: /**
265: * Consumes this event so that it will not be processed
266: * in the default manner by the source which originated it.
267: */
268: public void consume() {
269: consumed = true;
270: }
271:
272: /**
273: * Returns whether or not this event has been consumed.
274: * @see #consume
275: */
276: public boolean isConsumed() {
277: return consumed;
278: }
279:
280: // state serialization compatibility with JDK 1.1
281: static final long serialVersionUID = -2482525981698309786L;
282:
283: /**
284: * Returns a String describing the extended modifier key(s), such as "Shift",
285: * "Button1" or "Ctrl+Shift" . These strings can be localized by changing the
286: * awt.properties file.
287: *
288: * @return string a text description of the combination of extended
289: * modifier keys that were held down during the event
290: * @since 1.4
291: */
292:
293: public static String getModifiersExText(int modifiers) {
294: StringBuffer buf = new StringBuffer();
295: if ((modifiers & InputEvent.META_DOWN_MASK) != 0) {
296: buf.append(Toolkit.getProperty("AWT.meta", "Meta"));
297: buf.append("+");
298: }
299: if ((modifiers & InputEvent.CTRL_DOWN_MASK) != 0) {
300: buf.append(Toolkit.getProperty("AWT.control", "Ctrl"));
301: buf.append("+");
302: }
303: if ((modifiers & InputEvent.ALT_DOWN_MASK) != 0) {
304: buf.append(Toolkit.getProperty("AWT.alt", "Alt"));
305: buf.append("+");
306: }
307: if ((modifiers & InputEvent.SHIFT_DOWN_MASK) != 0) {
308: buf.append(Toolkit.getProperty("AWT.shift", "Shift"));
309: buf.append("+");
310: }
311: if ((modifiers & InputEvent.ALT_GRAPH_DOWN_MASK) != 0) {
312: buf
313: .append(Toolkit.getProperty("AWT.altGraph",
314: "Alt Graph"));
315: buf.append("+");
316: }
317: if ((modifiers & InputEvent.BUTTON1_DOWN_MASK) != 0) {
318: buf.append(Toolkit.getProperty("AWT.button1", "Button1"));
319: buf.append("+");
320: }
321: if ((modifiers & InputEvent.BUTTON2_DOWN_MASK) != 0) {
322: buf.append(Toolkit.getProperty("AWT.button2", "Button2"));
323: buf.append("+");
324: }
325: if ((modifiers & InputEvent.BUTTON3_DOWN_MASK) != 0) {
326: buf.append(Toolkit.getProperty("AWT.button3", "Button3"));
327: buf.append("+");
328: }
329: if (buf.length() > 0) {
330: buf.setLength(buf.length() - 1); // remove trailing '+'
331: }
332: return buf.toString();
333: }
334: }
|