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  ;
11  import java.awt.Component  ;
12  import java.awt.GraphicsEnvironment  ;
13  import java.awt.Toolkit  ;
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   {
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   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   sm = System.getSecurityManager();
207             if (sm != null) {
208                 try {
209                     sm.checkSystemClipboardAccess();
210                     b = true;
211                 } catch (SecurityException   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   getModifiersExText(int modifiers) {
340         StringBuffer   buf = new StringBuffer  ();
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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags