1. /*
  2. * @(#)MouseWheelEvent.java 1.9 03/12/19
  3. *
  4. * Copyright 2004 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 sun.awt.DebugHelper;
  10. /**
  11. * An event which indicates that the mouse wheel was rotated in a component.
  12. * <P>
  13. * A wheel mouse is a mouse which has a wheel in place of the middle button.
  14. * This wheel can be rotated towards or away from the user. Mouse wheels are
  15. * most often used for scrolling, though other uses are possible.
  16. * <P>
  17. * A MouseWheelEvent object is passed to every <code>MouseWheelListener</code>
  18. * object which registered to receive the "interesting" mouse events using the
  19. * component's <code>addMouseWheelListener</code> method. Each such listener
  20. * object gets a <code>MouseEvent</code> containing the mouse event.
  21. * <P>
  22. * Due to the mouse wheel's special relationship to scrolling Components,
  23. * MouseWheelEvents are delivered somewhat differently than other MouseEvents.
  24. * This is because while other MouseEvents usually affect a change on
  25. * the Component directly under the mouse
  26. * cursor (for instance, when clicking a button), MouseWheelEvents often have
  27. * an effect away from the mouse cursor (moving the wheel while
  28. * over a Component inside a ScrollPane should scroll one of the
  29. * Scrollbars on the ScrollPane).
  30. * <P>
  31. * MouseWheelEvents start delivery from the Component underneath the
  32. * mouse cursor. If MouseWheelEvents are not enabled on the
  33. * Component, the event is delivered to the first ancestor
  34. * Container with MouseWheelEvents enabled. This will usually be
  35. * a ScrollPane with wheel scrolling enabled. The source
  36. * Component and x,y coordinates will be relative to the event's
  37. * final destination (the ScrollPane). This allows a complex
  38. * GUI to be installed without modification into a ScrollPane, and
  39. * for all MouseWheelEvents to be delivered to the ScrollPane for
  40. * scrolling.
  41. * <P>
  42. * Some AWT Components are implemented using native widgets which
  43. * display their own scrollbars and handle their own scrolling.
  44. * The particular Components for which this is true will vary from
  45. * platform to platform. When the mouse wheel is
  46. * moved over one of these Components, the event is delivered straight to
  47. * the native widget, and not propagated to ancestors.
  48. * <P>
  49. * Platforms offer customization of the amount of scrolling that
  50. * should take place when the mouse wheel is moved. The two most
  51. * common settings are to scroll a certain number of "units"
  52. * (commonly lines of text in a text-based component) or an entire "block"
  53. * (similar to page-up/page-down). The MouseWheelEvent offers
  54. * methods for conforming to the underlying platform settings. These
  55. * platform settings can be changed at any time by the user. MouseWheelEvents
  56. * reflect the most recent settings.
  57. *
  58. * @author Brent Christian
  59. * @version 1.9 12/19/03
  60. * @see MouseWheelListener
  61. * @see java.awt.ScrollPane
  62. * @see java.awt.ScrollPane#setWheelScrollingEnabled(boolean)
  63. * @see javax.swing.JScrollPane
  64. * @see javax.swing.JScrollPane#setWheelScrollingEnabled(boolean)
  65. * @since 1.4
  66. */
  67. public class MouseWheelEvent extends MouseEvent {
  68. private static final DebugHelper dbg = DebugHelper.create(MouseWheelEvent.class);
  69. /**
  70. * Constant representing scrolling by "units" (like scrolling with the
  71. * arrow keys)
  72. *
  73. * @see #getScrollType
  74. */
  75. public static final int WHEEL_UNIT_SCROLL = 0;
  76. /**
  77. * Constant representing scrolling by a "block" (like scrolling
  78. * with page-up, page-down keys)
  79. *
  80. * @see #getScrollType
  81. */
  82. public static final int WHEEL_BLOCK_SCROLL = 1;
  83. /**
  84. * Indicates what sort of scrolling should take place in response to this
  85. * event, based on platform settings. Legal values are:
  86. * <ul>
  87. * <li> WHEEL_UNIT_SCROLL
  88. * <li> WHEEL_BLOCK_SCROLL
  89. * </ul>
  90. *
  91. * @see #getScrollType
  92. */
  93. int scrollType;
  94. /**
  95. * Only valid for scrollType WHEEL_UNIT_SCROLL.
  96. * Indicates number of units that should be scrolled per
  97. * click of mouse wheel rotation, based on platform settings.
  98. *
  99. * @see #getScrollAmount
  100. * @see #getScrollType
  101. */
  102. int scrollAmount;
  103. /**
  104. * Indicates how far the mouse wheel was rotated.
  105. *
  106. * @see #getWheelRotation
  107. */
  108. int wheelRotation;
  109. // serial version id?
  110. /**
  111. * Constructs a <code>MouseWheelEvent</code> object with the
  112. * specified source component, type, modifiers, coordinates,
  113. * scroll type, scroll amount, and wheel rotation.
  114. * <p>Note that passing in an invalid <code>id</code> results in
  115. * unspecified behavior. This method throws an
  116. * <code>IllegalArgumentException</code> if <code>source</code>
  117. * is <code>null</code>.
  118. *
  119. * @param source the <code>Component</code> that originated
  120. * the event
  121. * @param id the integer that identifies the event
  122. * @param when a long that gives the time the event occurred
  123. * @param modifiers the modifier keys down during event
  124. * (shift, ctrl, alt, meta)
  125. * @param x the horizontal x coordinate for the mouse location
  126. * @param y the vertical y coordinate for the mouse location
  127. * @param clickCount the number of mouse clicks associated with event
  128. * @param popupTrigger a boolean, true if this event is a trigger for a
  129. * popup-menu
  130. * @param scrollType the type of scrolling which should take place in
  131. * response to this event; valid values are
  132. * <code>WHEEL_UNIT_SCROLL</code> and
  133. * <code>WHEEL_BLOCK_SCROLL</code>
  134. * @param scrollAmount for scrollType <code>WHEEL_UNIT_SCROLL</code>,
  135. * the number of units to be scrolled
  136. * @param wheelRotation the amount that the mouse wheel was rotated (the
  137. * number of "clicks")
  138. *
  139. * @throws IllegalArgumentException if <code>source</code> is null
  140. * @see MouseEvent#MouseEvent(java.awt.Component, int, long, int, int, int, int, boolean)
  141. */
  142. public MouseWheelEvent (Component source, int id, long when, int modifiers,
  143. int x, int y, int clickCount, boolean popupTrigger,
  144. int scrollType, int scrollAmount, int wheelRotation) {
  145. super(source, id, when, modifiers, x, y, clickCount, popupTrigger);
  146. this.scrollType = scrollType;
  147. this.scrollAmount = scrollAmount;
  148. this.wheelRotation = wheelRotation;
  149. if (dbg.on) {
  150. dbg.println("MouseWheelEvent constructor");
  151. // Thread.dumpStack();
  152. }
  153. }
  154. /**
  155. * Returns the type of scrolling that should take place in response to this
  156. * event. This is determined by the native platform. Legal values are:
  157. * <ul>
  158. * <li> MouseWheelEvent.WHEEL_UNIT_SCROLL
  159. * <li> MouseWheelEvent.WHEEL_BLOCK_SCROLL
  160. * </ul>
  161. *
  162. * @return either MouseWheelEvent.WHEEL_UNIT_SCROLL or
  163. * MouseWheelEvent.WHEEL_BLOCK_SCROLL, depending on the configuration of
  164. * the native platform.
  165. * @see java.awt.Adjustable#getUnitIncrement
  166. * @see java.awt.Adjustable#getBlockIncrement
  167. * @see javax.swing.Scrollable#getScrollableUnitIncrement
  168. * @see javax.swing.Scrollable#getScrollableBlockIncrement
  169. */
  170. public int getScrollType() {
  171. return scrollType;
  172. }
  173. /**
  174. * Returns the number of units that should be scrolled in response to this
  175. * event. Only valid if <code>getScrollType</code> returns
  176. * <code>MouseWheelEvent.WHEEL_UNIT_SCROLL</code>
  177. *
  178. * @return number of units to scroll, or an undefined value if
  179. * <code>getScrollType</code> returns
  180. * <code>MouseWheelEvent.WHEEL_BLOCK_SCROLL</code>
  181. * @see #getScrollType
  182. */
  183. public int getScrollAmount() {
  184. return scrollAmount;
  185. }
  186. /**
  187. * Returns the number of "clicks" the mouse wheel was rotated.
  188. *
  189. * @return negative values if the mouse wheel was rotated up/away from
  190. * the user, and positive values if the mouse wheel was rotated down/
  191. * towards the user
  192. */
  193. public int getWheelRotation() {
  194. return wheelRotation;
  195. }
  196. /**
  197. * This is a convenience method to aid in the implementation of
  198. * the common-case MouseWheelListener - to scroll a ScrollPane or
  199. * JScrollPane by an amount which conforms to the platform settings.
  200. * (Note, however, that <code>ScrollPane</code> and
  201. * <code>JScrollPane</code> already have this functionality built in.)
  202. * <P>
  203. * This method returns the number of units to scroll when scroll type is
  204. * MouseWheelEvent.WHEEL_UNIT_SCROLL, and should only be called if
  205. * <code>getScrollType</code> returns MouseWheelEvent.WHEEL_UNIT_SCROLL.
  206. * <P>
  207. * Direction of scroll, amount of wheel movement,
  208. * and platform settings for wheel scrolling are all accounted for.
  209. * This method does not and cannot take into account value of the
  210. * Adjustable/Scrollable unit increment, as this will vary among
  211. * scrolling components.
  212. * <P>
  213. * A simplified example of how this method might be used in a
  214. * listener:
  215. * <pre>
  216. * mouseWheelMoved(MouseWheelEvent event) {
  217. * ScrollPane sp = getScrollPaneFromSomewhere();
  218. * Adjustable adj = sp.getVAdjustable()
  219. * if (MouseWheelEvent.getScrollType() == WHEEL_UNIT_SCROLL) {
  220. * int totalScrollAmount =
  221. * event.getUnitsToScroll() *
  222. * adj.getUnitIncrement();
  223. * adj.setValue(adj.getValue() + totalScrollAmount);
  224. * }
  225. * }
  226. * </pre>
  227. *
  228. * @return the number of units to scroll based on the direction and amount
  229. * of mouse wheel rotation, and on the wheel scrolling settings of the
  230. * native platform
  231. * @see #getScrollType
  232. * @see #getScrollAmount
  233. * @see MouseWheelListener
  234. * @see java.awt.Adjustable
  235. * @see java.awt.Adjustable#getUnitIncrement
  236. * @see javax.swing.Scrollable
  237. * @see javax.swing.Scrollable#getScrollableUnitIncrement
  238. * @see java.awt.ScrollPane
  239. * @see java.awt.ScrollPane#setWheelScrollingEnabled
  240. * @see javax.swing.JScrollPane
  241. * @see javax.swing.JScrollPane#setWheelScrollingEnabled
  242. */
  243. public int getUnitsToScroll() {
  244. return scrollAmount * wheelRotation;
  245. }
  246. /**
  247. * Returns a parameter string identifying this event.
  248. * This method is useful for event-logging and for debugging.
  249. *
  250. * @return a string identifying the event and its attributes
  251. */
  252. public String paramString() {
  253. String scrollTypeStr = null;
  254. if (getScrollType() == WHEEL_UNIT_SCROLL) {
  255. scrollTypeStr = "WHEEL_UNIT_SCROLL";
  256. }
  257. else if (getScrollType() == WHEEL_BLOCK_SCROLL) {
  258. scrollTypeStr = "WHEEL_BLOCK_SCROLL";
  259. }
  260. else {
  261. scrollTypeStr = "unknown scroll type";
  262. }
  263. return super.paramString()+",scrollType="+scrollTypeStr+
  264. ",scrollAmount="+getScrollAmount()+",wheelRotation="+
  265. getWheelRotation();
  266. }
  267. }