Source for java.awt.event.MouseEvent

   1: /* MouseEvent.java -- a mouse event
   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: import java.awt.Point;
  45: import java.awt.PopupMenu;
  46: import java.io.IOException;
  47: import java.io.ObjectInputStream;
  48: 
  49: /**
  50:  * This event is generated for a mouse event. There are three main categories
  51:  * of mouse events: Regular events include pressing, releasing, and clicking
  52:  * buttons, as well as moving over the boundary of the unobscured portion of
  53:  * a component. Motion events include movement and dragging. Wheel events are
  54:  * covered separately by the subclass MouseWheelEvent.
  55:  *
  56:  * <p>A mouse event is tied to the unobstructed visible component that the
  57:  * mouse cursor was over at the time of the action. The button that was
  58:  * most recently pressed is the only one that shows up in
  59:  * <code>getModifiers</code>, and is returned by <code>getButton</code>,
  60:  * while all buttons that are down show up in <code>getModifiersEx</code>.
  61:  *
  62:  * <p>Drag events may be cut short if native drag-and-drop operations steal
  63:  * the event. Likewise, if a mouse drag exceeds the bounds of a window or
  64:  * virtual device, some platforms may clip the path to fit in the bounds of
  65:  * the component.
  66:  *
  67:  * @author Aaron M. Renn (arenn@urbanophile.com)
  68:  * @author Eric Blake (ebb9@email.byu.edu)
  69:  * @see MouseAdapter
  70:  * @see MouseListener
  71:  * @see MouseMotionAdapter
  72:  * @see MouseMotionListener
  73:  * @see MouseWheelListener
  74:  * @since 1.1
  75:  * @status updated to 1.4
  76:  */
  77: public class MouseEvent extends InputEvent
  78: {
  79:   /**
  80:    * Compatible with JDK 1.1+.
  81:    */
  82:   private static final long serialVersionUID = -991214153494842848L;
  83: 
  84:   /** This is the first id in the range of event ids used by this class. */
  85:   public static final int MOUSE_FIRST = 500;
  86: 
  87:   /** This is the last id in the range of event ids used by this class. */
  88:   public static final int MOUSE_LAST = 507;
  89: 
  90:   /** This event id indicates that the mouse was clicked. */
  91:   public static final int MOUSE_CLICKED = 500;
  92: 
  93:   /** This event id indicates that the mouse was pressed. */
  94:   public static final int MOUSE_PRESSED = 501;
  95: 
  96:   /** This event id indicates that the mouse was released. */
  97:   public static final int MOUSE_RELEASED = 502;
  98: 
  99:   /** This event id indicates that the mouse was moved. */
 100:   public static final int MOUSE_MOVED = 503;
 101: 
 102:   /** This event id indicates that the mouse entered a component. */
 103:   public static final int MOUSE_ENTERED = 504;
 104: 
 105:   /** This event id indicates that the mouse exited a component. */
 106:   public static final int MOUSE_EXITED = 505;
 107: 
 108:   /**
 109:    * This indicates that no button changed state.
 110:    *
 111:    * @see #getButton()
 112:    * @since 1.4
 113:    */
 114:   public static final int NOBUTTON = 0;
 115: 
 116:   /**
 117:    * This indicates that button 1 changed state.
 118:    *
 119:    * @see #getButton()
 120:    * @since 1.4
 121:    */
 122:   public static final int BUTTON1 = 1;
 123: 
 124:   /**
 125:    * This indicates that button 2 changed state.
 126:    *
 127:    * @see #getButton()
 128:    * @since 1.4
 129:    */
 130:   public static final int BUTTON2 = 2;
 131: 
 132:   /**
 133:    * This indicates that button 3 changed state.
 134:    *
 135:    * @see #getButton()
 136:    * @since 1.4
 137:    */
 138:   public static final int BUTTON3 = 3;
 139: 
 140:   /** This event id indicates that the mouse was dragged over a component. */
 141:   public static final int MOUSE_DRAGGED = 506;
 142: 
 143:   /**
 144:    * This event id indicates that the mouse wheel was rotated.
 145:    *
 146:    * @since 1.4
 147:    */
 148:   public static final int MOUSE_WHEEL = 507;
 149: 
 150:   /**
 151:    * The X coordinate of the mouse cursor at the time of the event.
 152:    *
 153:    * @see #getX()
 154:    * @serial the x coordinate
 155:   */
 156:   private int x;
 157: 
 158:   /**
 159:    * The Y coordinate of the mouse cursor at the time of the event.
 160:    *
 161:    * @see #getY()
 162:    * @serial the y coordinate
 163:    */
 164:   private int y;
 165: 
 166:   /**
 167:    * The screen position of that mouse event, X coordinate.
 168:    */
 169:   private int absX;
 170: 
 171:   /**
 172:    * The screen position of that mouse event, Y coordinate.
 173:    */
 174:   private int absY;
 175: 
 176:   /**
 177:    * The number of clicks that took place. For MOUSE_CLICKED, MOUSE_PRESSED,
 178:    * and MOUSE_RELEASED, this will be at least 1; otherwise it is 0.
 179:    *
 180:    * see #getClickCount()
 181:    * @serial the number of clicks
 182:    */
 183:   private final int clickCount;
 184: 
 185:   /**
 186:    * Indicates which mouse button changed state. Can only be one of
 187:    * {@link #NOBUTTON}, {@link #BUTTON1}, {@link #BUTTON2}, or
 188:    * {@link #BUTTON3}.
 189:    *
 190:    * @see #getButton()
 191:    * @since 1.4
 192:    */
 193:   private int button;
 194: 
 195:   /**
 196:    * Whether or not this event should trigger a popup menu.
 197:    *
 198:    * @see PopupMenu
 199:    * @see #isPopupTrigger()
 200:    * @serial true if this is a popup trigger
 201:    */
 202:   private final boolean popupTrigger;
 203: 
 204:   /**
 205:    * Initializes a new instance of <code>MouseEvent</code> with the specified
 206:    * information. Note that an invalid id leads to unspecified results.
 207:    *
 208:    * @param source the source of the event
 209:    * @param id the event id
 210:    * @param when the timestamp of when the event occurred
 211:    * @param modifiers the modifier keys during the event, in old or new style
 212:    * @param x the X coordinate of the mouse point
 213:    * @param y the Y coordinate of the mouse point
 214:    * @param clickCount the number of mouse clicks for this event
 215:    * @param popupTrigger true if this event triggers a popup menu
 216:    * @param button the most recent mouse button to change state
 217:    * @throws IllegalArgumentException if source is null or button is invalid
 218:    * @since 1.4
 219:    */
 220:   public MouseEvent(Component source, int id, long when, int modifiers,
 221:                     int x, int y, int clickCount, boolean popupTrigger,
 222:                     int button)
 223:   {
 224:     super(source, id, when, modifiers);
 225: 
 226:     this.x = x;
 227:     this.y = y;
 228:     this.clickCount = clickCount;
 229:     this.popupTrigger = popupTrigger;
 230:     this.button = button;
 231:     if (button < NOBUTTON || button > BUTTON3)
 232:       throw new IllegalArgumentException();
 233:     if ((modifiers & EventModifier.OLD_MASK) != 0)
 234:       {
 235:         if ((modifiers & BUTTON1_MASK) != 0)
 236:           this.button = BUTTON1;
 237:         else if ((modifiers & BUTTON2_MASK) != 0)
 238:           this.button = BUTTON2;
 239:         else if ((modifiers & BUTTON3_MASK) != 0)
 240:           this.button = BUTTON3;
 241:       }
 242:     // clear the mouse button modifier masks if this is a button
 243:     // release event.
 244:     if (id == MOUSE_RELEASED)
 245:       this.modifiersEx &= ~(BUTTON1_DOWN_MASK
 246:                 | BUTTON2_DOWN_MASK
 247:                 | BUTTON3_DOWN_MASK);
 248: 
 249:     if (source != null)
 250:       {
 251:         Point screenLoc = source.getLocationOnScreen();
 252:         absX = screenLoc.x + x;
 253:         absY = screenLoc.y + y;
 254:       }
 255:   }
 256: 
 257:   /**
 258:    * Initializes a new instance of <code>MouseEvent</code> with the specified
 259:    * information. Note that an invalid id leads to unspecified results.
 260:    *
 261:    * @param source the source of the event
 262:    * @param id the event id
 263:    * @param when the timestamp of when the event occurred
 264:    * @param modifiers the modifier keys during the event, in old or new style
 265:    * @param x the X coordinate of the mouse point
 266:    * @param y the Y coordinate of the mouse point
 267:    * @param clickCount the number of mouse clicks for this event
 268:    * @param popupTrigger true if this event triggers a popup menu
 269:    * @throws IllegalArgumentException if source is null
 270:    */
 271:   public MouseEvent(Component source, int id, long when, int modifiers,
 272:                     int x, int y, int clickCount, boolean popupTrigger)
 273:   {
 274:     this(source, id, when, modifiers, x, y, clickCount, popupTrigger,
 275:          NOBUTTON);
 276:   }
 277: 
 278:   /**
 279:    * Creates a new MouseEvent. This is like the other constructors and adds
 280:    * specific absolute coordinates.
 281:    *
 282:    * @param source the source of the event
 283:    * @param id the event id
 284:    * @param when the timestamp of when the event occurred
 285:    * @param modifiers the modifier keys during the event, in old or new style
 286:    * @param x the X coordinate of the mouse point
 287:    * @param y the Y coordinate of the mouse point
 288:    * @param absX the absolute X screen coordinate of this event
 289:    * @param absY the absolute Y screen coordinate of this event
 290:    * @param clickCount the number of mouse clicks for this event
 291:    * @param popupTrigger true if this event triggers a popup menu
 292:    * @param button the most recent mouse button to change state
 293:    *
 294:    * @throws IllegalArgumentException if source is null or button is invalid
 295:    *
 296:    * @since 1.6
 297:    */
 298:   public MouseEvent(Component source, int id, long when, int modifiers,
 299:                     int x, int y, int absX, int absY, int clickCount,
 300:                     boolean popupTrigger, int button)
 301:   {
 302:     super(source, id, when, modifiers);
 303: 
 304:     this.x = x;
 305:     this.y = y;
 306:     this.clickCount = clickCount;
 307:     this.popupTrigger = popupTrigger;
 308:     this.button = button;
 309:     if (button < NOBUTTON || button > BUTTON3)
 310:       throw new IllegalArgumentException();
 311:     if ((modifiers & EventModifier.OLD_MASK) != 0)
 312:       {
 313:         if ((modifiers & BUTTON1_MASK) != 0)
 314:           this.button = BUTTON1;
 315:         else if ((modifiers & BUTTON2_MASK) != 0)
 316:           this.button = BUTTON2;
 317:         else if ((modifiers & BUTTON3_MASK) != 0)
 318:           this.button = BUTTON3;
 319:       }
 320:     // clear the mouse button modifier masks if this is a button
 321:     // release event.
 322:     if (id == MOUSE_RELEASED)
 323:       this.modifiersEx &= ~(BUTTON1_DOWN_MASK
 324:                 | BUTTON2_DOWN_MASK
 325:                 | BUTTON3_DOWN_MASK);
 326: 
 327:     this.absX = absX;
 328:     this.absY = absY;
 329:   }
 330: 
 331:   /**
 332:    * This method returns the X coordinate of the mouse position. This is
 333:    * relative to the source component.
 334:    *
 335:    * @return the x coordinate
 336:    */
 337:   public int getX()
 338:   {
 339:     return x;
 340:   }
 341: 
 342:   /**
 343:    * This method returns the Y coordinate of the mouse position. This is
 344:    * relative to the source component.
 345:    *
 346:    * @return the y coordinate
 347:    */
 348:   public int getY()
 349:   {
 350:     return y;
 351:   }
 352: 
 353:   /**
 354:    * @since 1.6
 355:    */
 356:   public Point getLocationOnScreen()
 357:   {
 358:     return new Point(absX, absY);
 359:   }
 360: 
 361:   /**
 362:    * @since 1.6
 363:    */
 364:   public int getXOnScreen()
 365:   {
 366:     return absX;
 367:   }
 368: 
 369:   /**
 370:    * @since 1.6
 371:    */
 372:   public int getYOnScreen()
 373:   {
 374:     return absY;
 375:   }
 376: 
 377:   /**
 378:    * This method returns a <code>Point</code> for the x,y position of
 379:    * the mouse pointer. This is relative to the source component.
 380:    *
 381:    * @return a <code>Point</code> for the event position
 382:    */
 383:   public Point getPoint()
 384:   {
 385:     return new Point(x, y);
 386:   }
 387: 
 388:   /**
 389:    * Translates the event coordinates by the specified x and y offsets.
 390:    *
 391:    * @param dx the value to add to the X coordinate of this event
 392:    * @param dy the value to add to the Y coordiante of this event
 393:    */
 394:   public void translatePoint(int dx, int dy)
 395:   {
 396:     x += dx;
 397:     y += dy;
 398:   }
 399: 
 400:   /**
 401:    * This method returns the number of mouse clicks associated with this
 402:    * event.
 403:    *
 404:    * @return the number of mouse clicks for this event
 405:    */
 406:   public int getClickCount()
 407:   {
 408:     return clickCount;
 409:   }
 410: 
 411:   /**
 412:    * Returns which button, if any, was the most recent to change state. This
 413:    * will be one of {@link #NOBUTTON}, {@link #BUTTON1}, {@link #BUTTON2}, or
 414:    * {@link #BUTTON3}.
 415:    *
 416:    * @return the button that changed state
 417:    * @since 1.4
 418:    */
 419:   public int getButton()
 420:   {
 421:     return button;
 422:   }
 423: 
 424:   /**
 425:    * This method tests whether or not the event is a popup menu trigger. This
 426:    * should be checked in both MousePressed and MouseReleased to be
 427:    * cross-platform compatible, as different systems have different popup
 428:    * triggers.
 429:    *
 430:    * @return true if the event is a popup menu trigger
 431:    */
 432:   public boolean isPopupTrigger()
 433:   {
 434:     return popupTrigger;
 435:   }
 436: 
 437:   /**
 438:    * Returns a string describing the modifiers, such as "Shift" or
 439:    * "Ctrl+Button1".
 440:    *
 441:    * XXX Sun claims this can be localized via the awt.properties file - how
 442:    * do we implement that?
 443:    *
 444:    * @param modifiers the old-style modifiers to convert to text
 445:    * @return a string representation of the modifiers in this bitmask
 446:    */
 447:   public static String getMouseModifiersText(int modifiers)
 448:   {
 449:     modifiers &= EventModifier.OLD_MASK;
 450:     if ((modifiers & BUTTON2_MASK) != 0)
 451:       modifiers |= BUTTON2_DOWN_MASK;
 452:     if ((modifiers & BUTTON3_MASK) != 0)
 453:       modifiers |= BUTTON3_DOWN_MASK;
 454:     return getModifiersExText(EventModifier.extend(modifiers));
 455:   }
 456: 
 457:   /**
 458:    * Returns a string identifying this event. This is formatted as the field
 459:    * name of the id type, followed by the (x,y) point, the most recent button
 460:    * changed, modifiers (if any), extModifiers (if any), and clickCount.
 461:    *
 462:    * @return a string identifying this event
 463:    */
 464:   public String paramString()
 465:   {
 466:     StringBuffer s = new StringBuffer();
 467:     switch (id)
 468:       {
 469:       case MOUSE_CLICKED:
 470:         s.append("MOUSE_CLICKED,(");
 471:         break;
 472:       case MOUSE_PRESSED:
 473:         s.append("MOUSE_PRESSED,(");
 474:         break;
 475:       case MOUSE_RELEASED:
 476:         s.append("MOUSE_RELEASED,(");
 477:         break;
 478:       case MOUSE_MOVED:
 479:         s.append("MOUSE_MOVED,(");
 480:         break;
 481:       case MOUSE_ENTERED:
 482:         s.append("MOUSE_ENTERED,(");
 483:         break;
 484:       case MOUSE_EXITED:
 485:         s.append("MOUSE_EXITED,(");
 486:         break;
 487:       case MOUSE_DRAGGED:
 488:         s.append("MOUSE_DRAGGED,(");
 489:         break;
 490:       case MOUSE_WHEEL:
 491:         s.append("MOUSE_WHEEL,(");
 492:         break;
 493:       default:
 494:         s.append("unknown type,(");
 495:       }
 496:     s.append(x).append(',').append(y).append("),button=").append(button);
 497:     // FIXME: need a mauve test for this method
 498:     if (modifiersEx != 0)
 499:       s.append(",extModifiers=").append(getModifiersExText(modifiersEx));
 500:     
 501:     s.append(",clickCount=").append(clickCount);
 502:     s.append(",consumed=").append(consumed);
 503:     
 504:     return s.toString();
 505:   }
 506: 
 507:   /**
 508:    * Reads in the object from a serial stream.
 509:    *
 510:    * @param s the stream to read from
 511:    * @throws IOException if deserialization fails
 512:    * @throws ClassNotFoundException if deserialization fails
 513:    * @serialData default, except that the modifiers are converted to new style
 514:    */
 515:   private void readObject(ObjectInputStream s)
 516:     throws IOException, ClassNotFoundException
 517:   {
 518:     s.defaultReadObject();
 519:     if ((modifiers & EventModifier.OLD_MASK) != 0)
 520:       {
 521:         if ((modifiers & BUTTON1_MASK) != 0)
 522:           button = BUTTON1;
 523:         else if ((modifiers & BUTTON2_MASK) != 0)
 524:           button = BUTTON2;
 525:         else if ((modifiers & BUTTON3_MASK) != 0)
 526:           button = BUTTON3;
 527:         modifiersEx = EventModifier.extend(modifiers) & EventModifier.NEW_MASK;
 528:       }
 529:   }
 530: } // class MouseEvent