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