001: /*
002: * @(#)MouseWheelEvent.java 1.7 03/01/23
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package java.awt.event;
028:
029: import java.awt.Component;
030:
031: /**
032: * An event which indicates that the mouse wheel was rotated in a component.
033: * <P>
034: * A wheel mouse is a mouse which has a wheel in place of the middle button.
035: * This wheel can be rotated towards or away from the user. Mouse wheels are
036: * most often used for scrolling, though other uses are possible.
037: * <P>
038: * A MouseWheelEvent object is passed to every <code>MouseWheelListener</code>
039: * object which registered to receive the "interesting" mouse events using the
040: * component's <code>addMouseWheelListener</code> method. Each such listener
041: * object gets a <code>MouseEvent</code> containing the mouse event.
042: * <P>
043: * Due to the mouse wheel's special relationship to scrolling Components,
044: * MouseWheelEvents are delivered somewhat differently than other MouseEvents.
045: * This is because while other MouseEvents usually affect a change on
046: * the Component directly under the mouse
047: * cursor (for instance, when clicking a button), MouseWheelEvents often have
048: * an effect away from the mouse cursor (moving the wheel while
049: * over a Component inside a ScrollPane should scroll one of the
050: * Scrollbars on the ScrollPane).
051: * <P>
052: * MouseWheelEvents start delivery from the Component underneath the
053: * mouse cursor. If MouseWheelEvents are not enabled on the
054: * Component, the event is delivered to the first ancestor
055: * Container with MouseWheelEvents enabled. This will usually be
056: * a ScrollPane with wheel scrolling enabled. The source
057: * Component and x,y coordinates will be relative to the event's
058: * final destination (the ScrollPane). This allows a complex
059: * GUI to be installed without modification into a ScrollPane, and
060: * for all MouseWheelEvents to be delivered to the ScrollPane for
061: * scrolling.
062: * <P>
063: * Some AWT Components are implemented using native widgets which
064: * display their own scrollbars and handle their own scrolling.
065: * The particular Components for which this is true will vary from
066: * platform to platform. When the mouse wheel is
067: * moved over one of these Components, the event is delivered straight to
068: * the native widget, and not propagated to ancestors.
069: * <P>
070: * Platforms offer customization of the amount of scrolling that
071: * should take place when the mouse wheel is moved. The two most
072: * common settings are to scroll a certain number of "units"
073: * (commonly lines of text in a text-based component) or an entire "block"
074: * (similar to page-up/page-down). The MouseWheelEvent offers
075: * methods for conforming to the underlying platform settings. These
076: * platform settings can be changed at any time by the user. MouseWheelEvents
077: * reflect the most recent settings.
078: *
079: * @author Brent Christian
080: * @version 1.7 01/23/03
081: * @see MouseWheelListener
082: * @see java.awt.ScrollPane
083: * @see java.awt.ScrollPane#setWheelScrollingEnabled(boolean)
084: * @see javax.swing.JScrollPane
085: * @see javax.swing.JScrollPane#setWheelScrollingEnabled(boolean)
086: * @since 1.4
087: */
088:
089: public class MouseWheelEvent extends MouseEvent {
090:
091: /**
092: * Constant representing scrolling by "units" (like scrolling with the
093: * arrow keys)
094: *
095: * @see #getScrollType
096: */
097: public static final int WHEEL_UNIT_SCROLL = 0;
098:
099: /**
100: * Constant representing scrolling by a "block" (like scrolling
101: * with page-up, page-down keys)
102: *
103: * @see #getScrollType
104: */
105: public static final int WHEEL_BLOCK_SCROLL = 1;
106:
107: /**
108: * Indicates what sort of scrolling should take place in response to this
109: * event, based on platform settings. Legal values are:
110: * <ul>
111: * <li> WHEEL_UNIT_SCROLL
112: * <li> WHEEL_BLOCK_SCROLL
113: * </ul>
114: *
115: * @see #getScrollType
116: */
117: int scrollType;
118:
119: /**
120: * Only valid for scrollType WHEEL_UNIT_SCROLL.
121: * Indicates number of units that should be scrolled per
122: * click of mouse wheel rotation, based on platform settings.
123: *
124: * @see #getScrollAmount
125: * @see #getScrollType
126: */
127: int scrollAmount;
128:
129: /**
130: * Indicates how far the mouse wheel was rotated.
131: *
132: * @see #getWheelRotation
133: */
134: int wheelRotation;
135:
136: // serial version id?
137:
138: /**
139: * Constructs a <code>MouseWheelEvent</code> object with the
140: * specified source component, type, modifiers, coordinates,
141: * scroll type, scroll amount, and wheel rotation.
142: * <p>Note that passing in an invalid <code>id</code> results in
143: * unspecified behavior.
144: *
145: * @param source the <code>Component</code> that originated
146: * the event
147: * @param id the integer that identifies the event
148: * @param when a long that gives the time the event occurred
149: * @param modifiers the modifier keys down during event
150: * (shift, ctrl, alt, meta)
151: * @param x the horizontal x coordinate for the mouse location
152: * @param y the vertical y coordinate for the mouse location
153: * @param clickCount the number of mouse clicks associated with event
154: * @param popupTrigger a boolean, true if this event is a trigger for a
155: * popup-menu
156: * @param scrollType the type of scrolling which should take place in
157: * response to this event; valid values are
158: * <code>WHEEL_UNIT_SCROLL</code> and
159: * <code>WHEEL_BLOCK_SCROLL</code>
160: * @param scrollAmount for scrollType <code>WHEEL_UNIT_SCROLL</code>,
161: * the number of units to be scrolled
162: * @param wheelRotation the amount that the mouse wheel was rotated (the
163: * number of "clicks")
164: *
165: * @see MouseEvent#MouseEvent(java.awt.Component, int, long, int, int, int, int, boolean)
166: */
167: public MouseWheelEvent(Component source, int id, long when,
168: int modifiers, int x, int y, int clickCount,
169: boolean popupTrigger, int scrollType, int scrollAmount,
170: int wheelRotation) {
171:
172: super (source, id, when, modifiers, x, y, clickCount,
173: popupTrigger);
174:
175: this .scrollType = scrollType;
176: this .scrollAmount = scrollAmount;
177: this .wheelRotation = wheelRotation;
178:
179: }
180:
181: /**
182: * Returns the type of scrolling that should take place in response to this
183: * event. This is determined by the native platform. Legal values are:
184: * <ul>
185: * <li> MouseWheelEvent.WHEEL_UNIT_SCROLL
186: * <li> MouseWheelEvent.WHEEL_BLOCK_SCROLL
187: * </ul>
188: *
189: * @return either MouseWheelEvent.WHEEL_UNIT_SCROLL or
190: * MouseWheelEvent.WHEEL_BLOCK_SCROLL, depending on the configuration of
191: * the native platform.
192: * @see java.awt.Adjustable#getUnitIncrement
193: * @see java.awt.Adjustable#getBlockIncrement
194: * @see javax.swing.Scrollable#getScrollableUnitIncrement
195: * @see javax.swing.Scrollable#getScrollableBlockIncrement
196: */
197: public int getScrollType() {
198: return scrollType;
199: }
200:
201: /**
202: * Returns the number of units that should be scrolled in response to this
203: * event. Only valid if <code>getScrollType</code> returns
204: * <code>MouseWheelEvent.WHEEL_UNIT_SCROLL</code>
205: *
206: * @return number of units to scroll, or an undefined value if
207: * <code>getScrollType</code> returns
208: * <code>MouseWheelEvent.WHEEL_BLOCK_SCROLL</code>
209: * @see #getScrollType
210: */
211: public int getScrollAmount() {
212: return scrollAmount;
213: }
214:
215: /**
216: * Returns the number of "clicks" the mouse wheel was rotated.
217: *
218: * @return negative values if the mouse wheel was rotated up/away from
219: * the user, and positive values if the mouse wheel was rotated down/
220: * towards the user
221: */
222: public int getWheelRotation() {
223: return wheelRotation;
224: }
225:
226: /**
227: * This is a convenience method to aid in the implementation of
228: * the common-case MouseWheelListener - to scroll a ScrollPane or
229: * JScrollPane by an amount which conforms to the platform settings.
230: * (Note, however, that <code>ScrollPane</code> and
231: * <code>JScrollPane</code> already have this functionality built in.)
232: * <P>
233: * This method returns the number of units to scroll when scroll type is
234: * MouseWheelEvent.WHEEL_UNIT_SCROLL, and should only be called if
235: * <code>getScrollType</code> returns MouseWheelEvent.WHEEL_UNIT_SCROLL.
236: * <P>
237: * Direction of scroll, amount of wheel movement,
238: * and platform settings for wheel scrolling are all accounted for.
239: * This method does not and cannot take into account value of the
240: * Adjustable/Scrollable unit increment, as this will vary among
241: * scrolling components.
242: * <P>
243: * A simplified example of how this method might be used in a
244: * listener:
245: * <pre>
246: * mouseWheelMoved(MouseWheelEvent event) {
247: * ScrollPane sp = getScrollPaneFromSomewhere();
248: * Adjustable adj = sp.getVAdjustable()
249: * if (MouseWheelEvent.getScrollType() == WHEEL_UNIT_SCROLL) {
250: * int totalScrollAmount =
251: * event.getUnitsToScroll() *
252: * adj.getUnitIncrement();
253: * adj.setValue(adj.getValue() + totalScrollAmount);
254: * }
255: * }
256: * </pre>
257: *
258: * @return the number of units to scroll based on the direction and amount
259: * of mouse wheel rotation, and on the wheel scrolling settings of the
260: * native platform
261: * @see #getScrollType
262: * @see #getScrollAmount
263: * @see MouseWheelListener
264: * @see java.awt.Adjustable
265: * @see java.awt.Adjustable#getUnitIncrement
266: * @see javax.swing.Scrollable
267: * @see javax.swing.Scrollable#getScrollableUnitIncrement
268: * @see java.awt.ScrollPane
269: * @see java.awt.ScrollPane#setWheelScrollingEnabled
270: * @see javax.swing.JScrollPane
271: * @see javax.swing.JScrollPane#setWheelScrollingEnabled
272: */
273: public int getUnitsToScroll() {
274: return scrollAmount * wheelRotation;
275: }
276:
277: /**
278: * Returns a parameter string identifying this event.
279: * This method is useful for event-logging and for debugging.
280: *
281: * @return a string identifying the event and its attributes
282: */
283: public String paramString() {
284: String scrollTypeStr = null;
285:
286: if (getScrollType() == WHEEL_UNIT_SCROLL) {
287: scrollTypeStr = "WHEEL_UNIT_SCROLL";
288: } else if (getScrollType() == WHEEL_BLOCK_SCROLL) {
289: scrollTypeStr = "WHEEL_BLOCK_SCROLL";
290: } else {
291: scrollTypeStr = "unknown scroll type";
292: }
293: return super .paramString() + ",scrollType=" + scrollTypeStr
294: + ",scrollAmount=" + getScrollAmount()
295: + ",wheelRotation=" + getWheelRotation();
296: }
297: }
|