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