libjava/classpath/java/awt/event/InputEvent.java

   1 /* InputEvent.java -- common superclass of component input events
   2    Copyright (C) 1999, 2002, 2004, 2005  Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38
  39 package java.awt.event;
  40
  41 import gnu.java.awt.EventModifier;
  42 import gnu.java.lang.CPStringBuilder;
  43
  44 import java.awt.Component;
  45
  46 /**
  47  * This is the common superclass for all component input classes. These are
  48  * passed to listeners before the component, so that listeners can consume
  49  * the event before it does its default behavior.
  50  *
  51  * @author Aaron M. Renn (arenn@urbanophile.com)
  52  * @see KeyEvent
  53  * @see KeyAdapter
  54  * @see MouseEvent
  55  * @see MouseAdapter
  56  * @see MouseMotionAdapter
  57  * @see MouseWheelEvent
  58  * @since 1.1
  59  * @status updated to 1.4
  60  */
  61 public abstract class InputEvent extends ComponentEvent
  62 {
  63   /**
  64    * Compatible with JDK 1.1+.
  65    */
  66   private static final long serialVersionUID = -2482525981698309786L;
  67
  68   /**
  69    * This is the bit mask which indicates the shift key is down. It is
  70    * recommended that SHIFT_DOWN_MASK be used instead.
  71    *
  72    * @see #SHIFT_DOWN_MASK
  73    */
  74   public static final int SHIFT_MASK = 1;
  75
  76   /**
  77    * This is the bit mask which indicates the control key is down. It is
  78    * recommended that CTRL_DOWN_MASK be used instead.
  79    *
  80    * @see #CTRL_DOWN_MASK
  81    */
  82   public static final int CTRL_MASK = 2;
  83
  84   /**
  85    * This is the bit mask which indicates the meta key is down. It is
  86    * recommended that META_DOWN_MASK be used instead.
  87    *
  88    * @see #META_DOWN_MASK
  89    */
  90   public static final int META_MASK = 4;
  91
  92   /**
  93    * This is the bit mask which indicates the alt key is down. It is
  94    * recommended that ALT_DOWN_MASK be used instead.
  95    *
  96    * @see #ALT_DOWN_MASK
  97    */
  98   public static final int ALT_MASK = 8;
  99
 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