MouseWheelEvent


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