Source for java.awt.event.InputEvent

   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: 
  43: import java.awt.Component;
  44: 
  45: /**
  46:  * This is the common superclass for all component input classes. These are
  47:  * passed to listeners before the component, so that listeners can consume
  48:  * the event before it does its default behavior.
  49:  *
  50:  * @author Aaron M. Renn (arenn@urbanophile.com)
  51:  * @see KeyEvent
  52:  * @see KeyAdapter
  53:  * @see MouseEvent
  54:  * @see MouseAdapter
  55:  * @see MouseMotionAdapter
  56:  * @see MouseWheelEvent
  57:  * @since 1.1
  58:  * @status updated to 1.4
  59:  */
  60: public abstract class InputEvent extends ComponentEvent
  61: {
  62:   /**
  63:    * Compatible with JDK 1.1+.
  64:    */
  65:   private static final long serialVersionUID = -2482525981698309786L;
  66: 
  67:   /**
  68:    * This is the bit mask which indicates the shift key is down. It is
  69:    * recommended that SHIFT_DOWN_MASK be used instead.
  70:    *
  71:    * @see #SHIFT_DOWN_MASK
  72:    */
  73:   public static final int SHIFT_MASK = 1;
  74: 
  75:   /**
  76:    * This is the bit mask which indicates the control key is down. It is
  77:    * recommended that CTRL_DOWN_MASK be used instead.
  78:    *
  79:    * @see #CTRL_DOWN_MASK
  80:    */
  81:   public static final int CTRL_MASK = 2;
  82: 
  83:   /**
  84:    * This is the bit mask which indicates the meta key is down. It is
  85:    * recommended that META_DOWN_MASK be used instead.
  86:    *
  87:    * @see #META_DOWN_MASK
  88:    */
  89:   public static final int META_MASK = 4;
  90: 
  91:   /**
  92:    * This is the bit mask which indicates the alt key is down. It is
  93:    * recommended that ALT_DOWN_MASK be used instead.
  94:    *
  95:    * @see #ALT_DOWN_MASK
  96:    */
  97:   public static final int ALT_MASK = 8;
  98: 
  99:   /**
 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 modifiers in effect for this event. Package visible for use by
 201:    * subclasses. The old style (bitmask 0x3f) should not be mixed with the
 202:    * new style (bitmasks 0xffffffc0).
 203:    *
 204:    * @see #getModifiers()
 205:    * @see MouseEvent
 206:    * @serial the modifier state, stored in the new style
 207:    */
 208:   int modifiers;
 209: 
 210:   /**
 211:    * Initializes a new instance of <code>InputEvent</code> with the specified
 212:    * source, id, timestamp, and modifiers. Note that an invalid id leads to
 213:    * unspecified results.
 214:    *
 215:    * @param source the source of the event
 216:    * @param id the event id
 217:    * @param when the timestamp when the event occurred
 218:    * @param modifiers the modifiers in effect for this event, old or new style
 219:    * @throws IllegalArgumentException if source is null
 220:    */
 221:   InputEvent(Component source, int id, long when, int modifiers)
 222:   {
 223:     super(source, id);
 224:     this.when = when;
 225:     this.modifiers = EventModifier.extend(modifiers);
 226:   }
 227: 
 228:   /**
 229:    * This method tests whether or not the shift key was down during the event.
 230:    *
 231:    * @return true if the shift key is down
 232:    */
 233:   public boolean isShiftDown()
 234:   {
 235:     return (modifiers & SHIFT_DOWN_MASK) != 0;
 236:   }
 237: 
 238:   /**
 239:    * This method tests whether or not the control key was down during the
 240:    * event.
 241:    *
 242:    * @return true if the control key is down
 243:    */
 244:   public boolean isControlDown()
 245:   {
 246:     return (modifiers & CTRL_DOWN_MASK) != 0;
 247:   }
 248: 
 249:   /**
 250:    * This method tests whether or not the meta key was down during the event.
 251:    *
 252:    * @return true if the meta key is down
 253:    */
 254:   public boolean isMetaDown()
 255:   {
 256:     return (modifiers & META_DOWN_MASK) != 0;
 257:   }
 258: 
 259:   /**
 260:    * This method tests whether or not the alt key was down during the event.
 261:    *
 262:    * @return true if the alt key is down
 263:    */
 264:   public boolean isAltDown()
 265:   {
 266:     return (modifiers & ALT_DOWN_MASK) != 0;
 267:   }
 268: 
 269:   /**
 270:    * This method tests whether or not the alt-graph modifier was in effect
 271:    * during the event.
 272:    *
 273:    * @return true if the alt-graph modifier is down
 274:    */
 275:   public boolean isAltGraphDown()
 276:   {
 277:     return (modifiers & ALT_GRAPH_DOWN_MASK) != 0;
 278:   }
 279: 
 280:   /**
 281:    * This method returns the timestamp when this event occurred.
 282:    *
 283:    * @return the timestamp when this event occurred
 284:    */
 285:   public long getWhen()
 286:   {
 287:     return when;
 288:   }
 289: 
 290:   /**
 291:    * This method returns the old-style modifiers in effect for this event. 
 292:    * Note that this is ambiguous between button2 and alt, and between
 293:    * button3 and meta. Also, code which generated these modifiers tends to
 294:    * only list the modifier that just changed, even if others were down at
 295:    * the time. Consider using getModifiersEx instead. This will be a union
 296:    * of the bit masks defined in this class that are applicable to the event.
 297:    *
 298:    * @return the modifiers in effect for this event
 299:    * @see #getModifiersEx()
 300:    */
 301:   public int getModifiers()
 302:   {
 303:     return EventModifier.revert(modifiers);
 304:   }
 305: 
 306:   /**
 307:    * Returns the extended modifiers (new-style) for this event. This represents
 308:    * the state of all modal keys and mouse buttons at the time of the event,
 309:    * and does not suffer from the problems mentioned in getModifiers.
 310:    *
 311:    * <p>For an example of checking multiple modifiers, this code will return
 312:    * true only if SHIFT and BUTTON1 were pressed and CTRL was not:
 313:    * <pre>
 314:    * int onmask = InputEvent.SHIFT_DOWN_MASK | InputEvent.BUTTON1_DOWN_MASK;
 315:    * int offmask = InputEvent.CTRL_DOWN_MASK;
 316:    * return (event.getModifiersEx() & (onmask | offmask)) == onmask;
 317:    * </pre>
 318:    *
 319:    * @return the bitwise or of all modifiers pressed during the event
 320:    * @since 1.4
 321:    */
 322:   public int getModifiersEx()
 323:   {
 324:     return modifiers;
 325:   }
 326: 
 327:   /**
 328:    * Consumes this event.  A consumed event is not processed further by the AWT
 329:    * system.
 330:    */
 331:   public void consume()
 332:   {
 333:     consumed = true;
 334:   }
 335: 
 336:   /**
 337:    * This method tests whether or not this event has been consumed.
 338:    *
 339:    * @return true if this event has been consumed
 340:    */
 341:   public boolean isConsumed()
 342:   {
 343:     return consumed;
 344:   }
 345: 
 346:   /**
 347:    * Convert the extended modifier bitmask into a String, such as "Shift" or
 348:    * "Ctrl+Button1".
 349:    *
 350:    * XXX Sun claims this can be localized via the awt.properties file - how
 351:    * do we implement that?
 352:    *
 353:    * @param modifiers the modifiers
 354:    * @return a string representation of the modifiers in this bitmask
 355:    * @since 1.4
 356:    */
 357:   public static String getModifiersExText(int modifiers)
 358:   {
 359:     modifiers &= EventModifier.NEW_MASK;
 360:     if (modifiers == 0)
 361:       return "";
 362:     StringBuffer s = new StringBuffer();
 363:     if ((modifiers & META_DOWN_MASK) != 0)
 364:       s.append("Meta+");
 365:     if ((modifiers & CTRL_DOWN_MASK) != 0)
 366:       s.append("Ctrl+");
 367:     if ((modifiers & ALT_DOWN_MASK) != 0)
 368:       s.append("Alt+");
 369:     if ((modifiers & SHIFT_DOWN_MASK) != 0)
 370:       s.append("Shift+");
 371:     if ((modifiers & ALT_GRAPH_DOWN_MASK) != 0)
 372:       s.append("Alt Graph+");
 373:     if ((modifiers & BUTTON1_DOWN_MASK) != 0)
 374:       s.append("Button1+");
 375:     if ((modifiers & BUTTON2_DOWN_MASK) != 0)
 376:       s.append("Button2+");
 377:     if ((modifiers & BUTTON3_DOWN_MASK) != 0)
 378:       s.append("Button3+");
 379:     return s.substring(0, s.length() - 1);
 380:   }
 381: } // class InputEvent