001/* MouseEvent.java -- a mouse event
002   Copyright (C) 1999, 2002, 2004, 2005  Free Software Foundation, Inc.
003
004This file is part of GNU Classpath.
005
006GNU Classpath is free software; you can redistribute it and/or modify
007it under the terms of the GNU General Public License as published by
008the Free Software Foundation; either version 2, or (at your option)
009any later version.
010
011GNU Classpath is distributed in the hope that it will be useful, but
012WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014General Public License for more details.
015
016You should have received a copy of the GNU General Public License
017along with GNU Classpath; see the file COPYING.  If not, write to the
018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
01902110-1301 USA.
020
021Linking this library statically or dynamically with other modules is
022making a combined work based on this library.  Thus, the terms and
023conditions of the GNU General Public License cover the whole
024combination.
025
026As a special exception, the copyright holders of this library give you
027permission to link this library with independent modules to produce an
028executable, regardless of the license terms of these independent
029modules, and to copy and distribute the resulting executable under
030terms of your choice, provided that you also meet, for each linked
031independent module, the terms and conditions of the license of that
032module.  An independent module is a module which is not derived from
033or based on this library.  If you modify this library, you may extend
034this exception to your version of the library, but you are not
035obligated to do so.  If you do not wish to do so, delete this
036exception statement from your version. */
037
038
039package java.awt.event;
040
041import gnu.java.awt.EventModifier;
042import gnu.java.lang.CPStringBuilder;
043
044import java.awt.Component;
045import java.awt.Point;
046import java.awt.PopupMenu;
047import java.io.IOException;
048import java.io.ObjectInputStream;
049
050/**
051 * This event is generated for a mouse event. There are three main categories
052 * of mouse events: Regular events include pressing, releasing, and clicking
053 * buttons, as well as moving over the boundary of the unobscured portion of
054 * a component. Motion events include movement and dragging. Wheel events are
055 * covered separately by the subclass MouseWheelEvent.
056 *
057 * <p>A mouse event is tied to the unobstructed visible component that the
058 * mouse cursor was over at the time of the action. The button that was
059 * most recently pressed is the only one that shows up in
060 * <code>getModifiers</code>, and is returned by <code>getButton</code>,
061 * while all buttons that are down show up in <code>getModifiersEx</code>.
062 *
063 * <p>Drag events may be cut short if native drag-and-drop operations steal
064 * the event. Likewise, if a mouse drag exceeds the bounds of a window or
065 * virtual device, some platforms may clip the path to fit in the bounds of
066 * the component.
067 *
068 * @author Aaron M. Renn (arenn@urbanophile.com)
069 * @author Eric Blake (ebb9@email.byu.edu)
070 * @see MouseAdapter
071 * @see MouseListener
072 * @see MouseMotionAdapter
073 * @see MouseMotionListener
074 * @see MouseWheelListener
075 * @since 1.1
076 * @status updated to 1.4
077 */
078public class MouseEvent extends InputEvent
079{
080  /**
081   * Compatible with JDK 1.1+.
082   */
083  private static final long serialVersionUID = -991214153494842848L;
084
085  /** This is the first id in the range of event ids used by this class. */
086  public static final int MOUSE_FIRST = 500;
087
088  /** This is the last id in the range of event ids used by this class. */
089  public static final int MOUSE_LAST = 507;
090
091  /** This event id indicates that the mouse was clicked. */
092  public static final int MOUSE_CLICKED = 500;
093
094  /** This event id indicates that the mouse was pressed. */
095  public static final int MOUSE_PRESSED = 501;
096
097  /** This event id indicates that the mouse was released. */
098  public static final int MOUSE_RELEASED = 502;
099
100  /** This event id indicates that the mouse was moved. */
101  public static final int MOUSE_MOVED = 503;
102
103  /** This event id indicates that the mouse entered a component. */
104  public static final int MOUSE_ENTERED = 504;
105
106  /** This event id indicates that the mouse exited a component. */
107  public static final int MOUSE_EXITED = 505;
108
109  /**
110   * This indicates that no button changed state.
111   *
112   * @see #getButton()
113   * @since 1.4
114   */
115  public static final int NOBUTTON = 0;
116
117  /**
118   * This indicates that button 1 changed state.
119   *
120   * @see #getButton()
121   * @since 1.4
122   */
123  public static final int BUTTON1 = 1;
124
125  /**
126   * This indicates that button 2 changed state.
127   *
128   * @see #getButton()
129   * @since 1.4
130   */
131  public static final int BUTTON2 = 2;
132
133  /**
134   * This indicates that button 3 changed state.
135   *
136   * @see #getButton()
137   * @since 1.4
138   */
139  public static final int BUTTON3 = 3;
140
141  /** This event id indicates that the mouse was dragged over a component. */
142  public static final int MOUSE_DRAGGED = 506;
143
144  /**
145   * This event id indicates that the mouse wheel was rotated.
146   *
147   * @since 1.4
148   */
149  public static final int MOUSE_WHEEL = 507;
150
151  /**
152   * The X coordinate of the mouse cursor at the time of the event.
153   *
154   * @see #getX()
155   * @serial the x coordinate
156  */
157  private int x;
158
159  /**
160   * The Y coordinate of the mouse cursor at the time of the event.
161   *
162   * @see #getY()
163   * @serial the y coordinate
164   */
165  private int y;
166
167  /**
168   * The screen position of that mouse event, X coordinate.
169   */
170  private int absX;
171
172  /**
173   * The screen position of that mouse event, Y coordinate.
174   */
175  private int absY;
176
177  /**
178   * The number of clicks that took place. For MOUSE_CLICKED, MOUSE_PRESSED,
179   * and MOUSE_RELEASED, this will be at least 1; otherwise it is 0.
180   *
181   * see #getClickCount()
182   * @serial the number of clicks
183   */
184  private final int clickCount;
185
186  /**
187   * Indicates which mouse button changed state. Can only be one of
188   * {@link #NOBUTTON}, {@link #BUTTON1}, {@link #BUTTON2}, or
189   * {@link #BUTTON3}.
190   *
191   * @see #getButton()
192   * @since 1.4
193   */
194  private int button;
195
196  /**
197   * Whether or not this event should trigger a popup menu.
198   *
199   * @see PopupMenu
200   * @see #isPopupTrigger()
201   * @serial true if this is a popup trigger
202   */
203  private final boolean popupTrigger;
204
205  /**
206   * Initializes a new instance of <code>MouseEvent</code> with the specified
207   * information. Note that an invalid id leads to unspecified results.
208   *
209   * @param source the source of the event
210   * @param id the event id
211   * @param when the timestamp of when the event occurred
212   * @param modifiers the modifier keys during the event, in old or new style
213   * @param x the X coordinate of the mouse point
214   * @param y the Y coordinate of the mouse point
215   * @param clickCount the number of mouse clicks for this event
216   * @param popupTrigger true if this event triggers a popup menu
217   * @param button the most recent mouse button to change state
218   * @throws IllegalArgumentException if source is null or button is invalid
219   * @since 1.4
220   */
221  public MouseEvent(Component source, int id, long when, int modifiers,
222                    int x, int y, int clickCount, boolean popupTrigger,
223                    int button)
224  {
225    this(source, id, when, modifiers, x, y, 0, 0, clickCount, popupTrigger,
226         button);
227  }
228
229  /**
230   * Initializes a new instance of <code>MouseEvent</code> with the specified
231   * information. Note that an invalid id leads to unspecified results.
232   *
233   * @param source the source of the event
234   * @param id the event id
235   * @param when the timestamp of when the event occurred
236   * @param modifiers the modifier keys during the event, in old or new style
237   * @param x the X coordinate of the mouse point
238   * @param y the Y coordinate of the mouse point
239   * @param clickCount the number of mouse clicks for this event
240   * @param popupTrigger true if this event triggers a popup menu
241   * @throws IllegalArgumentException if source is null
242   */
243  public MouseEvent(Component source, int id, long when, int modifiers,
244                    int x, int y, int clickCount, boolean popupTrigger)
245  {
246    this(source, id, when, modifiers, x, y, clickCount, popupTrigger,
247         NOBUTTON);
248  }
249
250  /**
251   * Creates a new MouseEvent. This is like the other constructors and adds
252   * specific absolute coordinates.
253   *
254   * @param source the source of the event
255   * @param id the event id
256   * @param when the timestamp of when the event occurred
257   * @param modifiers the modifier keys during the event, in old or new style
258   * @param x the X coordinate of the mouse point
259   * @param y the Y coordinate of the mouse point
260   * @param absX the absolute X screen coordinate of this event
261   * @param absY the absolute Y screen coordinate of this event
262   * @param clickCount the number of mouse clicks for this event
263   * @param popupTrigger true if this event triggers a popup menu
264   * @param button the most recent mouse button to change state
265   *
266   * @throws IllegalArgumentException if source is null or button is invalid
267   *
268   * @since 1.6
269   */
270  public MouseEvent(Component source, int id, long when, int modifiers,
271                    int x, int y, int absX, int absY, int clickCount,
272                    boolean popupTrigger, int button)
273  {
274    super(source, id, when, modifiers);
275
276    this.x = x;
277    this.y = y;
278    this.clickCount = clickCount;
279    this.popupTrigger = popupTrigger;
280    this.button = button;
281    if (button < NOBUTTON || button > BUTTON3)
282      throw new IllegalArgumentException();
283    if ((modifiers & EventModifier.OLD_MASK) != 0)
284      {
285        if ((modifiers & BUTTON1_MASK) != 0)
286          this.button = BUTTON1;
287        else if ((modifiers & BUTTON2_MASK) != 0)
288          this.button = BUTTON2;
289        else if ((modifiers & BUTTON3_MASK) != 0)
290          this.button = BUTTON3;
291      }
292    // clear the mouse button modifier masks if this is a button
293    // release event.
294    if (id == MOUSE_RELEASED)
295      this.modifiersEx &= ~(BUTTON1_DOWN_MASK
296                            | BUTTON2_DOWN_MASK
297                            | BUTTON3_DOWN_MASK);
298
299    this.absX = absX;
300    this.absY = absY;
301  }
302
303  /**
304   * This method returns the X coordinate of the mouse position. This is
305   * relative to the source component.
306   *
307   * @return the x coordinate
308   */
309  public int getX()
310  {
311    return x;
312  }
313
314  /**
315   * This method returns the Y coordinate of the mouse position. This is
316   * relative to the source component.
317   *
318   * @return the y coordinate
319   */
320  public int getY()
321  {
322    return y;
323  }
324
325  /**
326   * @since 1.6
327   */
328  public Point getLocationOnScreen()
329  {
330    return new Point(absX, absY);
331  }
332
333  /**
334   * @since 1.6
335   */
336  public int getXOnScreen()
337  {
338    return absX;
339  }
340
341  /**
342   * @since 1.6
343   */
344  public int getYOnScreen()
345  {
346    return absY;
347  }
348
349  /**
350   * This method returns a <code>Point</code> for the x,y position of
351   * the mouse pointer. This is relative to the source component.
352   *
353   * @return a <code>Point</code> for the event position
354   */
355  public Point getPoint()
356  {
357    return new Point(x, y);
358  }
359
360  /**
361   * Translates the event coordinates by the specified x and y offsets.
362   *
363   * @param dx the value to add to the X coordinate of this event
364   * @param dy the value to add to the Y coordiante of this event
365   */
366  public void translatePoint(int dx, int dy)
367  {
368    x += dx;
369    y += dy;
370  }
371
372  /**
373   * This method returns the number of mouse clicks associated with this
374   * event.
375   *
376   * @return the number of mouse clicks for this event
377   */
378  public int getClickCount()
379  {
380    return clickCount;
381  }
382
383  /**
384   * Returns which button, if any, was the most recent to change state. This
385   * will be one of {@link #NOBUTTON}, {@link #BUTTON1}, {@link #BUTTON2}, or
386   * {@link #BUTTON3}.
387   *
388   * @return the button that changed state
389   * @since 1.4
390   */
391  public int getButton()
392  {
393    return button;
394  }
395
396  /**
397   * This method tests whether or not the event is a popup menu trigger. This
398   * should be checked in both MousePressed and MouseReleased to be
399   * cross-platform compatible, as different systems have different popup
400   * triggers.
401   *
402   * @return true if the event is a popup menu trigger
403   */
404  public boolean isPopupTrigger()
405  {
406    return popupTrigger;
407  }
408
409  /**
410   * Returns a string describing the modifiers, such as "Shift" or
411   * "Ctrl+Button1".
412   *
413   * XXX Sun claims this can be localized via the awt.properties file - how
414   * do we implement that?
415   *
416   * @param modifiers the old-style modifiers to convert to text
417   * @return a string representation of the modifiers in this bitmask
418   */
419  public static String getMouseModifiersText(int modifiers)
420  {
421    modifiers &= EventModifier.OLD_MASK;
422    if ((modifiers & BUTTON2_MASK) != 0)
423      modifiers |= BUTTON2_DOWN_MASK;
424    if ((modifiers & BUTTON3_MASK) != 0)
425      modifiers |= BUTTON3_DOWN_MASK;
426    return getModifiersExText(EventModifier.extend(modifiers));
427  }
428
429  /**
430   * Returns a string identifying this event. This is formatted as the field
431   * name of the id type, followed by the (x,y) point, the most recent button
432   * changed, modifiers (if any), extModifiers (if any), and clickCount.
433   *
434   * @return a string identifying this event
435   */
436  public String paramString()
437  {
438    CPStringBuilder s = new CPStringBuilder();
439    switch (id)
440      {
441      case MOUSE_CLICKED:
442        s.append("MOUSE_CLICKED,(");
443        break;
444      case MOUSE_PRESSED:
445        s.append("MOUSE_PRESSED,(");
446        break;
447      case MOUSE_RELEASED:
448        s.append("MOUSE_RELEASED,(");
449        break;
450      case MOUSE_MOVED:
451        s.append("MOUSE_MOVED,(");
452        break;
453      case MOUSE_ENTERED:
454        s.append("MOUSE_ENTERED,(");
455        break;
456      case MOUSE_EXITED:
457        s.append("MOUSE_EXITED,(");
458        break;
459      case MOUSE_DRAGGED:
460        s.append("MOUSE_DRAGGED,(");
461        break;
462      case MOUSE_WHEEL:
463        s.append("MOUSE_WHEEL,(");
464        break;
465      default:
466        s.append("unknown type,(");
467      }
468    s.append(x).append(',').append(y).append("),button=").append(button);
469    // FIXME: need a mauve test for this method
470    if (modifiersEx != 0)
471      s.append(",extModifiers=").append(getModifiersExText(modifiersEx));
472
473    s.append(",clickCount=").append(clickCount);
474    s.append(",consumed=").append(consumed);
475
476    return s.toString();
477  }
478
479  /**
480   * Reads in the object from a serial stream.
481   *
482   * @param s the stream to read from
483   * @throws IOException if deserialization fails
484   * @throws ClassNotFoundException if deserialization fails
485   * @serialData default, except that the modifiers are converted to new style
486   */
487  private void readObject(ObjectInputStream s)
488    throws IOException, ClassNotFoundException
489  {
490    s.defaultReadObject();
491    if ((modifiers & EventModifier.OLD_MASK) != 0)
492      {
493        if ((modifiers & BUTTON1_MASK) != 0)
494          button = BUTTON1;
495        else if ((modifiers & BUTTON2_MASK) != 0)
496          button = BUTTON2;
497        else if ((modifiers & BUTTON3_MASK) != 0)
498          button = BUTTON3;
499        modifiersEx = EventModifier.extend(modifiers) & EventModifier.NEW_MASK;
500      }
501  }
502} // class MouseEvent