1. /*
  2. * @(#)MouseEvent.java 1.23 01/11/29
  3. *
  4. * Copyright 2002 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package java.awt.event;
  8. import java.awt.Component;
  9. import java.awt.Event;
  10. import java.awt.Point;
  11. /**
  12. /**
  13. * An event which indicates that a mouse action occurred in a component.
  14. * This event is used both for mouse events (click, enter, exit) and mouse
  15. * motion events (moves and drags).
  16. * <P>
  17. * This low-level event is generated by a component object for:
  18. * <ul>
  19. * <li>Mouse Events
  20. * <ul>
  21. * <li>a mouse button is pressed
  22. * <li>a mouse button is released
  23. * <li>a mouse button is clicked (pressed and released)
  24. * <li>the mouse cursor enters a component
  25. * <li>the mouse cursor exits a component
  26. * </ul>
  27. * <li> Mouse Motion Events
  28. * <ul>
  29. * <li>the mouse is moved
  30. * <li>the mouse is dragged
  31. * </ul>
  32. * </ul>
  33. * <P>
  34. * A MouseEvent object is passed to every <code>MouseListener</code>
  35. * or <code>MouseAdapter</code> object which registered to receive
  36. * the "interesting" mouse events using the component's
  37. * <code>addMouseListener</code> method.
  38. * (<code>MouseAdapter</code> objects implement the
  39. * <code>MouseListener</code> interface.) Each such listener object
  40. * gets a <code>MouseEvent</code> containing the mouse event.
  41. * <P>
  42. * A MouseEvent object is also passed to every <code>MouseMotionListener</code>
  43. * or <code>MouseMotionAdapter</code> object which registered to receive
  44. * mouse motion events using the component's <code>addMouseMotionListener</code>
  45. * method. (<code>MouseMotionAdapter</code> objects implement the
  46. * <code>MouseMotionListener</code> interface.) Each such listener object
  47. * gets a <code>MouseEvent</code> containing the mouse motion event.
  48. * <P>
  49. * When a mouse button is clicked, events are generated and sent to the
  50. * registered MouseListeners, with the button mask set in the modifier field.
  51. * For example, if the first mouse button is pressed, events are sent in the
  52. * following order:
  53. * <PRE>
  54. * MOUSE_PRESSED: BUTTON1_MASK
  55. * MOUSE_RELEASED: BUTTON1_MASK
  56. * MOUSE_CLICKED: BUTTON1_MASK
  57. * </PRE>
  58. * When multiple mouse buttons are pressed, each press, release, and click
  59. * results in a separate event. The button mask in the modifier field reflects
  60. * only the button that changed state, not the current state of all buttons.
  61. * <P>
  62. * For example, if the user presses button 1 followed by button 2 and
  63. * releases them in the same order, the following sequence of events is
  64. * generated:
  65. * <PRE>
  66. * MOUSE_PRESSED: BUTTON1_MASK
  67. * MOUSE_PRESSED: BUTTON2_MASK
  68. * MOUSE_RELEASED: BUTTON1_MASK
  69. * MOUSE_CLICKED: BUTTON1_MASK
  70. * MOUSE_RELEASED: BUTTON2_MASK
  71. * MOUSE_CLICKED: BUTTON2_MASK
  72. * </PRE>
  73. * If button2 is released first, the MOUSE_RELEASED/MOUSE_CLICKED pair
  74. * for BUTTON2_MASK arrives first, followed by the pair for BUTTON1_MASK.
  75. *
  76. * @see MouseAdapter
  77. * @see MouseListener
  78. * @see MouseMotionAdapter
  79. * @see MouseMotionListner
  80. * @see <a href="http://java.sun.com/docs/books/tutorial/post1.0/ui/mouselistener.html">Tutorial: Writing a Mouse Listener</a>
  81. * @see <a href="http://java.sun.com/docs/books/tutorial/post1.0/ui/mousemotionlistener.html">Tutorial: Writing a Mouse Motion Listener</a>
  82. * @see <a href="http://www.awl.com/cp/javaseries/jcl1_2.html">Reference: The Java Class Libraries (update file)</a>
  83. *
  84. * @version 1.23 11/29/01
  85. * @author Carl Quinn
  86. */
  87. public class MouseEvent extends InputEvent {
  88. /**
  89. * The first number in the range of ids used for mouse events.
  90. */
  91. public static final int MOUSE_FIRST = 500;
  92. /**
  93. * The last number in the range of ids used for mouse events.
  94. */
  95. public static final int MOUSE_LAST = 506;
  96. /**
  97. * The "mouse clicked" event. This MouseEvent occurs when a mouse
  98. * button is pressed and released.
  99. */
  100. public static final int MOUSE_CLICKED = MOUSE_FIRST;
  101. /**
  102. * The "mouse pressed" event. This MouseEvent occurs when a mouse
  103. * button is pushed down.
  104. */
  105. public static final int MOUSE_PRESSED = 1 + MOUSE_FIRST; //Event.MOUSE_DOWN
  106. /**
  107. * The "mouse released" event. This MouseEvent occurs when a mouse
  108. * button is let up.
  109. */
  110. public static final int MOUSE_RELEASED = 2 + MOUSE_FIRST; //Event.MOUSE_UP
  111. /**
  112. * The "mouse moved" event. This MouseMotionEvent occurs when the mouse
  113. * position changes.
  114. */
  115. public static final int MOUSE_MOVED = 3 + MOUSE_FIRST; //Event.MOUSE_MOVE
  116. /**
  117. * The "mouse entered" event. This MouseEvent occurs when the mouse
  118. * cursor enters a component's area.
  119. */
  120. public static final int MOUSE_ENTERED = 4 + MOUSE_FIRST; //Event.MOUSE_ENTER
  121. /**
  122. * The "mouse exited" event. This MouseEvent occurs when the mouse
  123. * cursor leaves a component's area.
  124. */
  125. public static final int MOUSE_EXITED = 5 + MOUSE_FIRST; //Event.MOUSE_EXIT
  126. /**
  127. * The "mouse dragged" event. This MouseMotionEvent occurs when the mouse
  128. * position changes while the "drag" modifier is active (for example, the
  129. * shift key).
  130. */
  131. public static final int MOUSE_DRAGGED = 6 + MOUSE_FIRST; //Event.MOUSE_DRAG
  132. /**
  133. * The mouse events x coordinate.
  134. * The x value is relative to the component
  135. * that fired the event.
  136. *
  137. * @serial
  138. * @see getX()
  139. */
  140. int x;
  141. /**
  142. * The mouse events y coordinate.
  143. * The y value is relative to the component
  144. * that fired the event.
  145. *
  146. * @serial
  147. * @see getY()
  148. */
  149. int y;
  150. /**
  151. * Indicates the number of quick consecutive clicks of
  152. * a mouse button.
  153. * clickCount will be valid for only three mouse events :<BR>
  154. * <code>MOUSE_CLICKED</code>,
  155. * <code>MOUSE_PRESSED</code> and
  156. * <code>MOUSE_RELEASED</code>.
  157. * For the above, the clickCount will be at least 1. For all
  158. * other events the count will be 0.
  159. *
  160. * @serial
  161. * @see getClickCount().
  162. */
  163. int clickCount;
  164. /**
  165. * A property used to indicate whether a Popup Menu
  166. * should appear with a certain gestures.
  167. * If <code>popupTrigger</code> = <code>false</code> no popup menu
  168. * should appear. If it is <code>true</code> then a popup menu should appear
  169. .
  170. *
  171. * @serial
  172. * @see java.awt.PopupMenu
  173. * @see isPopupTrigger()
  174. */
  175. boolean popupTrigger = false;
  176. /*
  177. * JDK 1.1 serialVersionUID
  178. */
  179. private static final long serialVersionUID = -991214153494842848L;
  180. static {
  181. /* ensure that the necessary native libraries are loaded */
  182. NativeLibLoader.loadLibraries();
  183. initIDs();
  184. }
  185. /**
  186. * Initialize JNI field and method IDs for fields that may be
  187. accessed from C.
  188. */
  189. private static native void initIDs();
  190. /**
  191. * Constructs a MouseEvent object with the specified source component,
  192. * type, modifiers, coordinates, and click count.
  193. *
  194. * @param source the Component that originated the event
  195. * @param id the integer that identifies the event
  196. * @param when a long int that gives the time the event occurred
  197. * @param modifiers the modifier keys down during event
  198. * (shift, ctrl, alt, meta)
  199. * @param x the horizontal x coordinate for the mouse location
  200. * @param y the vertical y coordinate for the mouse location
  201. * @param clickCount the number of mouse clicks associated with event
  202. * @param popupTrigger a boolean, true if this event is a trigger for a
  203. * popup-menu
  204. */
  205. public MouseEvent(Component source, int id, long when, int modifiers,
  206. int x, int y, int clickCount, boolean popupTrigger) {
  207. super(source, id, when, modifiers);
  208. this.x = x;
  209. this.y = y;
  210. this.clickCount = clickCount;
  211. this.popupTrigger = popupTrigger;
  212. }
  213. /**
  214. * Returns the horizontal x position of the event relative to the
  215. * source component.
  216. *
  217. * @return x an integer indicating horizontal position relative to
  218. * the component
  219. */
  220. public int getX() {
  221. return x;
  222. }
  223. /**
  224. * Returns the vertical y position of the event relative to the
  225. * source component.
  226. *
  227. * @return y an integer indicating vertical position relative to
  228. * the component
  229. */
  230. public int getY() {
  231. return y;
  232. }
  233. /**
  234. * Returns the x,y position of the event relative to the source component.
  235. *
  236. * @return a Point object containing the x and y coordinates
  237. * relative to the source component
  238. *
  239. */
  240. public Point getPoint() {
  241. int x;
  242. int y;
  243. synchronized (this) {
  244. x = this.x;
  245. y = this.y;
  246. }
  247. return new Point(x, y);
  248. }
  249. /**
  250. * Translates the event's coordinates to a new position
  251. * by adding specified x (horizontal) and y (veritcal) offsets.
  252. *
  253. * @param x the horizontal x value to add to the current x coordinate position
  254. * @param y the vertical y value to add to the current y coordinate position
  255. */
  256. public synchronized void translatePoint(int x, int y) {
  257. this.x += x;
  258. this.y += y;
  259. }
  260. /**
  261. * Return the number of mouse clicks associated with this event.
  262. *
  263. * @return integer value for the number of clicks
  264. */
  265. public int getClickCount() {
  266. return clickCount;
  267. }
  268. /**
  269. * Returns whether or not this mouse event is the popup-menu
  270. * trigger event for the platform.
  271. *
  272. * @return boolean, true if this event is the popup-menu trigger
  273. * for this platform
  274. */
  275. public boolean isPopupTrigger() {
  276. return popupTrigger;
  277. }
  278. /**
  279. * Returns a parameter string identifying this event.
  280. * This method is useful for event-logging and for debugging.
  281. *
  282. * @return a string identifying the event and its attributes
  283. */
  284. public String paramString() {
  285. String typeStr;
  286. switch(id) {
  287. case MOUSE_PRESSED:
  288. typeStr = "MOUSE_PRESSED";
  289. break;
  290. case MOUSE_RELEASED:
  291. typeStr = "MOUSE_RELEASED";
  292. break;
  293. case MOUSE_CLICKED:
  294. typeStr = "MOUSE_CLICKED";
  295. break;
  296. case MOUSE_ENTERED:
  297. typeStr = "MOUSE_ENTERED";
  298. break;
  299. case MOUSE_EXITED:
  300. typeStr = "MOUSE_EXITED";
  301. break;
  302. case MOUSE_MOVED:
  303. typeStr = "MOUSE_MOVED";
  304. break;
  305. case MOUSE_DRAGGED:
  306. typeStr = "MOUSE_DRAGGED";
  307. break;
  308. default:
  309. typeStr = "unknown type";
  310. }
  311. return typeStr + ",("+x+","+y+")"+ ",mods="+getModifiers()+
  312. ",clickCount="+clickCount;
  313. }
  314. }