001    /* InputEvent.java -- common superclass of component input events
002       Copyright (C) 1999, 2002, 2004, 2005  Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath 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 for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    
039    package java.awt.event;
040    
041    import gnu.java.awt.EventModifier;
042    
043    import java.awt.Component;
044    
045    /**
046     * This is the common superclass for all component input classes. These are
047     * passed to listeners before the component, so that listeners can consume
048     * the event before it does its default behavior.
049     *
050     * @author Aaron M. Renn (arenn@urbanophile.com)
051     * @see KeyEvent
052     * @see KeyAdapter
053     * @see MouseEvent
054     * @see MouseAdapter
055     * @see MouseMotionAdapter
056     * @see MouseWheelEvent
057     * @since 1.1
058     * @status updated to 1.4
059     */
060    public abstract class InputEvent extends ComponentEvent
061    {
062      /**
063       * Compatible with JDK 1.1+.
064       */
065      private static final long serialVersionUID = -2482525981698309786L;
066    
067      /**
068       * This is the bit mask which indicates the shift key is down. It is
069       * recommended that SHIFT_DOWN_MASK be used instead.
070       *
071       * @see #SHIFT_DOWN_MASK
072       */
073      public static final int SHIFT_MASK = 1;
074    
075      /**
076       * This is the bit mask which indicates the control key is down. It is
077       * recommended that CTRL_DOWN_MASK be used instead.
078       *
079       * @see #CTRL_DOWN_MASK
080       */
081      public static final int CTRL_MASK = 2;
082    
083      /**
084       * This is the bit mask which indicates the meta key is down. It is
085       * recommended that META_DOWN_MASK be used instead.
086       *
087       * @see #META_DOWN_MASK
088       */
089      public static final int META_MASK = 4;
090    
091      /**
092       * This is the bit mask which indicates the alt key is down. It is
093       * recommended that ALT_DOWN_MASK be used instead.
094       *
095       * @see #ALT_DOWN_MASK
096       */
097      public static final int ALT_MASK = 8;
098    
099      /**
100       * This is the bit mask which indicates the alt-graph modifier is in effect.
101       * It is recommended that ALT_GRAPH_DOWN_MASK be used instead.
102       *
103       * @see #ALT_GRAPH_DOWN_MASK
104       */
105      public static final int ALT_GRAPH_MASK = 0x20;
106    
107      /**
108       * This bit mask indicates mouse button one is down. It is recommended that
109       * BUTTON1_DOWN_MASK be used instead.
110       *
111       * @see #BUTTON1_DOWN_MASK
112       */
113      public static final int BUTTON1_MASK = 0x10;
114    
115      /**
116       * This bit mask indicates mouse button two is down. It is recommended that
117       * BUTTON2_DOWN_MASK be used instead.
118       *
119       * @see #BUTTON2_DOWN_MASK
120       */
121      public static final int BUTTON2_MASK = 8;
122    
123      /**
124       * This bit mask indicates mouse button three is down. It is recommended
125       * that BUTTON3_DOWN_MASK be used instead.
126       *
127       * @see #BUTTON3_DOWN_MASK
128       */
129      public static final int BUTTON3_MASK = 4;
130    
131      /**
132       * The SHIFT key extended modifier.
133       *
134       * @since 1.4
135       */
136      public static final int SHIFT_DOWN_MASK = 0x0040;
137    
138      /**
139       * The CTRL key extended modifier.
140       *
141       * @since 1.4
142       */
143      public static final int CTRL_DOWN_MASK = 0x0080;
144    
145      /**
146       * The META key extended modifier.
147       *
148       * @since 1.4
149       */
150      public static final int META_DOWN_MASK = 0x0100;
151    
152      /**
153       * The ALT key extended modifier.
154       *
155       * @since 1.4
156       */
157      public static final int ALT_DOWN_MASK = 0x0200;
158    
159      /**
160       * The mouse button1 key extended modifier.
161       *
162       * @since 1.4
163       */
164      public static final int BUTTON1_DOWN_MASK = 0x0400;
165    
166      /**
167       * The mouse button2 extended modifier.
168       *
169       * @since 1.4
170       */
171      public static final int BUTTON2_DOWN_MASK = 0x0800;
172    
173      /**
174       * The mouse button3 extended modifier.
175       *
176       * @since 1.4
177       */
178      public static final int BUTTON3_DOWN_MASK = 0x1000;
179    
180      /**
181       * The ALT_GRAPH key extended modifier.
182       *
183       * @since 1.4
184       */
185      public static final int ALT_GRAPH_DOWN_MASK = 0x2000;
186    
187      /** The mask to convert new to old, package visible for use in subclasses. */
188      static final int CONVERT_MASK
189        = EventModifier.NEW_MASK & ~(BUTTON2_DOWN_MASK | BUTTON3_DOWN_MASK);
190    
191      /**
192       * The timestamp when this event occurred.
193       *
194       * @see #getWhen()
195       * @serial the timestamp
196       */
197      private final long when;
198    
199      /**
200       * The old-style modifiers in effect for this event. Package visible
201       * for use by subclasses. The old style (bitmask 0x3f) should not be
202       * mixed with the new style (bitmasks 0xffffffc0).
203       *
204       * @see #getModifiers()
205       * @see MouseEvent
206       * @serial the modifier state, stored in the old style
207       */
208      int modifiers;
209    
210      /**
211       * The new-style modifiers in effect for this event. Package visible
212       * for use by subclasses. The old style (bitmask 0x3f) should not be
213       * mixed with the new style (bitmasks 0xffffffc0).
214       *
215       * @see #getModifiersEx()
216       * @see MouseEvent
217       * @serial the modifier state, stored in the new style
218       */
219      int modifiersEx;
220    
221      /**
222       * Initializes a new instance of <code>InputEvent</code> with the specified
223       * source, id, timestamp, and modifiers. Note that an invalid id leads to
224       * unspecified results.
225       *
226       * @param source the source of the event
227       * @param id the event id
228       * @param when the timestamp when the event occurred
229       * @param modifiers the modifiers in effect for this event, old or new style
230       * @throws IllegalArgumentException if source is null
231       */
232      InputEvent(Component source, int id, long when, int modifiers)
233      {
234        super(source, id);
235        this.when = when;
236        this.modifiers = modifiers & EventModifier.OLD_MASK;
237        this.modifiersEx = modifiers & EventModifier.NEW_MASK;
238      }
239    
240      /**
241       * This method tests whether or not the shift key was down during the event.
242       *
243       * @return true if the shift key is down
244       */
245      public boolean isShiftDown()
246      {
247        return ((modifiers & SHIFT_MASK) != 0)
248          || ((modifiersEx & SHIFT_DOWN_MASK) != 0);
249      }
250    
251      /**
252       * This method tests whether or not the control key was down during the
253       * event.
254       *
255       * @return true if the control key is down
256       */
257      public boolean isControlDown()
258      {
259        return ((modifiers & CTRL_MASK) != 0)
260          || ((modifiersEx & CTRL_DOWN_MASK) != 0);
261      }
262    
263      /**
264       * This method tests whether or not the meta key was down during the event.
265       *
266       * @return true if the meta key is down
267       */
268      public boolean isMetaDown()
269      {
270        return ((modifiers & META_MASK) != 0)
271          || ((modifiersEx & META_DOWN_MASK) != 0);
272      }
273    
274      /**
275       * This method tests whether or not the alt key was down during the event.
276       *
277       * @return true if the alt key is down
278       */
279      public boolean isAltDown()
280      {
281        return ((modifiers & ALT_MASK) != 0)
282          || ((modifiersEx & ALT_DOWN_MASK) != 0);
283      }
284    
285      /**
286       * This method tests whether or not the alt-graph modifier was in effect
287       * during the event.
288       *
289       * @return true if the alt-graph modifier is down
290       */
291      public boolean isAltGraphDown()
292      {
293        return ((modifiers & ALT_GRAPH_MASK) != 0)
294          || ((modifiersEx & ALT_GRAPH_DOWN_MASK) != 0);
295      }
296    
297      /**
298       * This method returns the timestamp when this event occurred.
299       *
300       * @return the timestamp when this event occurred
301       */
302      public long getWhen()
303      {
304        return when;
305      }
306    
307      /**
308       * This method returns the old-style modifiers in effect for this event. 
309       * Note that this is ambiguous between button2 and alt, and between
310       * button3 and meta. Also, code which generated these modifiers tends to
311       * only list the modifier that just changed, even if others were down at
312       * the time. Consider using getModifiersEx instead. This will be a union
313       * of the bit masks defined in this class that are applicable to the event.
314       *
315       * @return the modifiers in effect for this event
316       * @see #getModifiersEx()
317       */
318      public int getModifiers()
319      {
320        return modifiers;
321      }
322    
323      /**
324       * Returns the extended modifiers (new-style) for this event. This represents
325       * the state of all modal keys and mouse buttons at the time of the event,
326       * and does not suffer from the problems mentioned in getModifiers.
327       *
328       * <p>For an example of checking multiple modifiers, this code will return
329       * true only if SHIFT and BUTTON1 were pressed and CTRL was not:
330       * <pre>
331       * int onmask = InputEvent.SHIFT_DOWN_MASK | InputEvent.BUTTON1_DOWN_MASK;
332       * int offmask = InputEvent.CTRL_DOWN_MASK;
333       * return (event.getModifiersEx() & (onmask | offmask)) == onmask;
334       * </pre>
335       *
336       * @return the bitwise or of all modifiers pressed during the event
337       * @since 1.4
338       */
339      public int getModifiersEx()
340      {
341        return modifiersEx;
342      }
343    
344      /**
345       * Consumes this event.  A consumed event is not processed further by the AWT
346       * system.
347       */
348      public void consume()
349      {
350        consumed = true;
351      }
352    
353      /**
354       * This method tests whether or not this event has been consumed.
355       *
356       * @return true if this event has been consumed
357       */
358      public boolean isConsumed()
359      {
360        return consumed;
361      }
362    
363      /**
364       * Convert the extended modifier bitmask into a String, such as "Shift" or
365       * "Ctrl+Button1".
366       *
367       * XXX Sun claims this can be localized via the awt.properties file - how
368       * do we implement that?
369       *
370       * @param modifiers the modifiers
371       * @return a string representation of the modifiers in this bitmask
372       * @since 1.4
373       */
374      public static String getModifiersExText(int modifiers)
375      {
376        modifiers &= EventModifier.NEW_MASK;
377        if (modifiers == 0)
378          return "";
379        StringBuffer s = new StringBuffer();
380        if ((modifiers & META_DOWN_MASK) != 0)
381          s.append("Meta+");
382        if ((modifiers & CTRL_DOWN_MASK) != 0)
383          s.append("Ctrl+");
384        if ((modifiers & ALT_DOWN_MASK) != 0)
385          s.append("Alt+");
386        if ((modifiers & SHIFT_DOWN_MASK) != 0)
387          s.append("Shift+");
388        if ((modifiers & ALT_GRAPH_DOWN_MASK) != 0)
389          s.append("Alt Graph+");
390        if ((modifiers & BUTTON1_DOWN_MASK) != 0)
391          s.append("Button1+");
392        if ((modifiers & BUTTON2_DOWN_MASK) != 0)
393          s.append("Button2+");
394        if ((modifiers & BUTTON3_DOWN_MASK) != 0)
395          s.append("Button3+");
396        return s.substring(0, s.length() - 1);
397      }
398    } // class InputEvent