Class MouseWheelEvent
- All Implemented Interfaces:
Serializable
public class MouseWheelEvent extends MouseEvent
A wheel mouse is a mouse which has a wheel in place of the middle button. This wheel can be rotated towards or away from the user. Mouse wheels are most often used for scrolling, though other uses are possible.
A MouseWheelEvent object is passed to every MouseWheelListener object which registered to receive the "interesting" mouse events using the component's addMouseWheelListener method. Each such listener object gets a MouseEvent containing the mouse event.
Due to the mouse wheel's special relationship to scrolling Components, MouseWheelEvents are delivered somewhat differently than other MouseEvents. This is because while other MouseEvents usually affect a change on the Component directly under the mouse cursor (for instance, when clicking a button), MouseWheelEvents often have an effect away from the mouse cursor (moving the wheel while over a Component inside a ScrollPane should scroll one of the Scrollbars on the ScrollPane).
MouseWheelEvents start delivery from the Component underneath the mouse cursor. If MouseWheelEvents are not enabled on the Component, the event is delivered to the first ancestor Container with MouseWheelEvents enabled. This will usually be a ScrollPane with wheel scrolling enabled. The source Component and x,y coordinates will be relative to the event's final destination (the ScrollPane). This allows a complex GUI to be installed without modification into a ScrollPane, and for all MouseWheelEvents to be delivered to the ScrollPane for scrolling.
Some AWT Components are implemented using native widgets which display their own scrollbars and handle their own scrolling. The particular Components for which this is true will vary from platform to platform. When the mouse wheel is moved over one of these Components, the event is delivered straight to the native widget, and not propagated to ancestors.
Platforms offer customization of the amount of scrolling that should take place when the mouse wheel is moved. The two most common settings are to scroll a certain number of "units" (commonly lines of text in a text-based component) or an entire "block" (similar to page-up/page-down). The MouseWheelEvent offers methods for conforming to the underlying platform settings. These platform settings can be changed at any time by the user. MouseWheelEvents reflect the most recent settings.
The MouseWheelEvent class includes methods for getting the number of "clicks" by which the mouse wheel is rotated. The getWheelRotation() method returns the integer number of "clicks" corresponding to the number of notches by which the wheel was rotated. In addition to this method, the MouseWheelEvent class provides the getPreciseWheelRotation() method which returns a double number of "clicks" in case a partial rotation occurred. The getPreciseWheelRotation() method is useful if a mouse supports a high-resolution wheel, such as a freely rotating wheel with no notches. Applications can benefit by using this method to process mouse wheel events more precisely, and thus, making visual perception smoother.
- Since:
- 1.4
- See Also:
Field Summary
| Modifier and Type | Field | Description |
|---|---|---|
static final int |
WHEEL_BLOCK_SCROLL |
Constant representing scrolling by a "block" (like scrolling with page-up, page-down keys) |
static final int |
WHEEL_UNIT_SCROLL |
Constant representing scrolling by "units" (like scrolling with the arrow keys) |
Fields declared in class MouseEvent
BUTTON1, BUTTON2, BUTTON3, MOUSE_CLICKED, MOUSE_DRAGGED, MOUSE_ENTERED, MOUSE_EXITED, MOUSE_FIRST, MOUSE_LAST, MOUSE_MOVED, MOUSE_PRESSED, MOUSE_RELEASED, MOUSE_WHEEL, NOBUTTON | Modifier and Type | Field | Description |
|---|---|---|
static final int |
BUTTON1 |
Indicates mouse button #1; used by MouseEvent.getButton(). |
static final int |
BUTTON2 |
Indicates mouse button #2; used by MouseEvent.getButton(). |
static final int |
BUTTON3 |
Indicates mouse button #3; used by MouseEvent.getButton(). |
static final int |
MOUSE_CLICKED |
The "mouse clicked" event. |
static final int |
MOUSE_DRAGGED |
The "mouse dragged" event. |
static final int |
MOUSE_ENTERED |
The "mouse entered" event. |
static final int |
MOUSE_EXITED |
The "mouse exited" event. |
static final int |
MOUSE_FIRST |
The first number in the range of ids used for mouse events. |
static final int |
MOUSE_LAST |
The last number in the range of ids used for mouse events. |
static final int |
MOUSE_MOVED |
The "mouse moved" event. |
static final int |
MOUSE_PRESSED |
The "mouse pressed" event. |
static final int |
MOUSE_RELEASED |
The "mouse released" event. |
static final int |
MOUSE_WHEEL |
The "mouse wheel" event. |
static final int |
NOBUTTON |
Indicates no mouse buttons; used by MouseEvent.getButton(). |
Fields declared in class InputEvent
ALT_DOWN_MASK, ALT_GRAPH_DOWN_MASK, ALT_GRAPH_MASK, ALT_MASK, BUTTON1_DOWN_MASK, BUTTON1_MASK, BUTTON2_DOWN_MASK, BUTTON2_MASK, BUTTON3_DOWN_MASK, BUTTON3_MASK, CTRL_DOWN_MASK, CTRL_MASK, META_DOWN_MASK, META_MASK, SHIFT_DOWN_MASK, SHIFT_MASK | Modifier and Type | Field | Description |
|---|---|---|
static final int |
ALT_DOWN_MASK |
The Alt key extended modifier constant. |
static final int |
ALT_GRAPH_DOWN_MASK |
The AltGraph key extended modifier constant. |
static final int |
ALT_GRAPH_MASK |
Deprecated. |
static final int |
ALT_MASK |
Deprecated. It is recommended that ALT_DOWN_MASK and InputEvent.getModifiersEx() be used instead |
static final int |
BUTTON1_DOWN_MASK |
The Mouse Button1 extended modifier constant. |
static final int |
BUTTON1_MASK |
Deprecated. It is recommended that BUTTON1_DOWN_MASK and InputEvent.getModifiersEx() be used instead |
static final int |
BUTTON2_DOWN_MASK |
The Mouse Button2 extended modifier constant. |
static final int |
BUTTON2_MASK |
Deprecated. It is recommended that BUTTON2_DOWN_MASK and InputEvent.getModifiersEx() be used instead. |
static final int |
BUTTON3_DOWN_MASK |
The Mouse Button3 extended modifier constant. |
static final int |
BUTTON3_MASK |
Deprecated. It is recommended that BUTTON3_DOWN_MASK and InputEvent.getModifiersEx() be used instead. |
static final int |
CTRL_DOWN_MASK |
The Control key extended modifier constant. |
static final int |
CTRL_MASK |
Deprecated. It is recommended that CTRL_DOWN_MASK and InputEvent.getModifiersEx() be used instead |
static final int |
META_DOWN_MASK |
The Meta key extended modifier constant. |
static final int |
META_MASK |
Deprecated. It is recommended that META_DOWN_MASK and InputEvent.getModifiersEx() be used instead |
static final int |
SHIFT_DOWN_MASK |
The Shift key extended modifier constant. |
static final int |
SHIFT_MASK |
Deprecated. It is recommended that SHIFT_DOWN_MASK and InputEvent.getModifiersEx() be used instead |
Fields declared in class ComponentEvent
COMPONENT_FIRST, COMPONENT_HIDDEN, COMPONENT_LAST, COMPONENT_MOVED, COMPONENT_RESIZED, COMPONENT_SHOWN | Modifier and Type | Field | Description |
|---|---|---|
static final int |
COMPONENT_FIRST |
The first number in the range of ids used for component events. |
static final int |
COMPONENT_HIDDEN |
This event indicates that the component was rendered invisible. |
static final int |
COMPONENT_LAST |
The last number in the range of ids used for component events. |
static final int |
COMPONENT_MOVED |
This event indicates that the component's position changed. |
static final int |
COMPONENT_RESIZED |
This event indicates that the component's size changed. |
static final int |
COMPONENT_SHOWN |
This event indicates that the component was made visible. |
Fields declared in class AWTEvent
ACTION_EVENT_MASK, ADJUSTMENT_EVENT_MASK, COMPONENT_EVENT_MASK, consumed, CONTAINER_EVENT_MASK, FOCUS_EVENT_MASK, HIERARCHY_BOUNDS_EVENT_MASK, HIERARCHY_EVENT_MASK, id, INPUT_METHOD_EVENT_MASK, INVOCATION_EVENT_MASK, ITEM_EVENT_MASK, KEY_EVENT_MASK, MOUSE_EVENT_MASK, MOUSE_MOTION_EVENT_MASK, MOUSE_WHEEL_EVENT_MASK, PAINT_EVENT_MASK, RESERVED_ID_MAX, TEXT_EVENT_MASK, WINDOW_EVENT_MASK, WINDOW_FOCUS_EVENT_MASK, WINDOW_STATE_EVENT_MASK | Modifier and Type | Field | Description |
|---|---|---|
static final long |
ACTION_EVENT_MASK |
The event mask for selecting action events. |
static final long |
ADJUSTMENT_EVENT_MASK |
The event mask for selecting adjustment events. |
static final long |
COMPONENT_EVENT_MASK |
The event mask for selecting component events. |
protected boolean |
consumed |
Controls whether or not the event is sent back down to the peer once the source has processed it - false means it's sent to the peer; true means it's not. |
static final long |
CONTAINER_EVENT_MASK |
The event mask for selecting container events. |
static final long |
FOCUS_EVENT_MASK |
The event mask for selecting focus events. |
static final long |
HIERARCHY_BOUNDS_EVENT_MASK |
The event mask for selecting hierarchy bounds events. |
static final long |
HIERARCHY_EVENT_MASK |
The event mask for selecting hierarchy events. |
protected int |
id |
The event's id. |
static final long |
INPUT_METHOD_EVENT_MASK |
The event mask for selecting input method events. |
static final long |
INVOCATION_EVENT_MASK |
The event mask for selecting invocation events. |
static final long |
ITEM_EVENT_MASK |
The event mask for selecting item events. |
static final long |
KEY_EVENT_MASK |
The event mask for selecting key events. |
static final long |
MOUSE_EVENT_MASK |
The event mask for selecting mouse events. |
static final long |
MOUSE_MOTION_EVENT_MASK |
The event mask for selecting mouse motion events. |
static final long |
MOUSE_WHEEL_EVENT_MASK |
The event mask for selecting mouse wheel events. |
static final long |
PAINT_EVENT_MASK |
The event mask for selecting paint events. |
static final int |
RESERVED_ID_MAX |
The maximum value for reserved AWT event IDs. |
static final long |
TEXT_EVENT_MASK |
The event mask for selecting text events. |
static final long |
WINDOW_EVENT_MASK |
The event mask for selecting window events. |
static final long |
WINDOW_FOCUS_EVENT_MASK |
The event mask for selecting window focus events. |
static final long |
WINDOW_STATE_EVENT_MASK |
The event mask for selecting window state events. |
Fields declared in class EventObject
source | Modifier and Type | Field | Description |
|---|---|---|
protected Object |
source |
The object on which the Event initially occurred. |
Constructor Summary
| Constructor | Description |
|---|---|
MouseWheelEvent |
Constructs a MouseWheelEvent object with the specified source component, type, modifiers, coordinates, scroll type, scroll amount, and wheel rotation. |
MouseWheelEvent |
Constructs a MouseWheelEvent object with the specified source component, type, modifiers, coordinates, absolute coordinates, scroll type, scroll amount, and wheel rotation. |
MouseWheelEvent |
Constructs a MouseWheelEvent object with the specified source component, type, modifiers, coordinates, absolute coordinates, scroll type, scroll amount, and wheel rotation. |
Method Summary
| Modifier and Type | Method | Description |
|---|---|---|
double |
getPreciseWheelRotation() |
Returns the number of "clicks" the mouse wheel was rotated, as a double. |
int |
getScrollAmount() |
Returns the number of units that should be scrolled per click of mouse wheel rotation. |
int |
getScrollType() |
Returns the type of scrolling that should take place in response to this event. |
int |
getUnitsToScroll() |
This is a convenience method to aid in the implementation of the common-case MouseWheelListener - to scroll a ScrollPane or JScrollPane by an amount which conforms to the platform settings. |
int |
getWheelRotation() |
Returns the number of "clicks" the mouse wheel was rotated, as an integer. |
String |
paramString() |
Returns a parameter string identifying this event. |
Methods declared in class MouseEvent
getButton, getClickCount, getLocationOnScreen, getMouseModifiersText, getPoint, getX, getXOnScreen, getY, getYOnScreen, isPopupTrigger, translatePoint | Modifier and Type | Method | Description |
|---|---|---|
int |
getButton() |
Returns which, if any, of the mouse buttons has changed state. |
int |
getClickCount() |
Returns the number of mouse clicks associated with this event. |
Point |
getLocationOnScreen() |
Returns the absolute x, y position of the event. |
static String |
getMouseModifiersText |
Returns a String instance describing the modifier keys and mouse buttons that were down during the event, such as "Shift", or "Ctrl+Shift". |
Point |
getPoint() |
Returns the x,y position of the event relative to the source component. |
int |
getX() |
Returns the horizontal x position of the event relative to the source component. |
int |
getXOnScreen() |
Returns the absolute horizontal x position of the event. |
int |
getY() |
Returns the vertical y position of the event relative to the source component. |
int |
getYOnScreen() |
Returns the absolute vertical y position of the event. |
boolean |
isPopupTrigger() |
Returns whether or not this mouse event is the popup menu trigger event for the platform. |
void |
translatePoint |
Translates the event's coordinates to a new position by adding specified x (horizontal) and y (vertical) offsets. |
Methods declared in class InputEvent
consume, getMaskForButton, getModifiers, getModifiersEx, getModifiersExText, getWhen, isAltDown, isAltGraphDown, isConsumed, isControlDown, isMetaDown, isShiftDown | Modifier and Type | Method | Description |
|---|---|---|
void |
consume() |
Consumes this event so that it will not be processed in the default manner by the source which originated it. |
static int |
getMaskForButton |
A method to obtain a mask for any existing mouse button. |
int |
getModifiers() |
Deprecated. It is recommended that extended modifier keys and InputEvent.getModifiersEx() be used instead |
int |
getModifiersEx() |
Returns the extended modifier mask for this event. |
static String |
getModifiersExText |
Returns a String describing the extended modifier keys and mouse buttons, such as "Shift", "Button1", or "Ctrl+Shift". |
long |
getWhen() |
Returns the difference in milliseconds between the timestamp of when this event occurred and midnight, January 1, 1970 UTC. |
boolean |
isAltDown() |
Returns whether or not the Alt modifier is down on this event. |
boolean |
isAltGraphDown() |
Returns whether or not the AltGraph modifier is down on this event. |
boolean |
isConsumed() |
Returns whether or not this event has been consumed. |
boolean |
isControlDown() |
Returns whether or not the Control modifier is down on this event. |
boolean |
isMetaDown() |
Returns whether or not the Meta modifier is down on this event. |
boolean |
isShiftDown() |
Returns whether or not the Shift modifier is down on this event. |
Methods declared in class ComponentEvent
getComponent | Modifier and Type | Method | Description |
|---|---|---|
Component |
getComponent() |
Returns the originator of the event. |
Methods declared in class AWTEvent
getID, setSource, toString | Modifier and Type | Method | Description |
|---|---|---|
int |
getID() |
Returns the event type. |
void |
setSource |
Retargets an event to a new source. |
String |
toString() |
Returns a String representation of this object. |
Methods declared in class EventObject
getSource | Modifier and Type | Method | Description |
|---|---|---|
Object |
getSource() |
The object on which the Event initially occurred. |
Methods declared in class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait | Modifier and Type | Method | Description |
|---|---|---|
protected Object |
clone() |
Creates and returns a copy of this object. |
boolean |
equals |
Indicates whether some other object is "equal to" this one. |
protected void |
finalize() |
Deprecated, for removal: This API element is subject to removal in a future version. Finalization is deprecated and subject to removal in a future release. |
final Class |
getClass() |
Returns the runtime class of this Object. |
int |
hashCode() |
Returns a hash code value for this object. |
final void |
notify() |
Wakes up a single thread that is waiting on this object's monitor. |
final void |
notifyAll() |
Wakes up all threads that are waiting on this object's monitor. |
final void |
wait() |
Causes the current thread to wait until it is awakened, typically by being notified or interrupted. |
final void |
wait |
Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. |
final void |
wait |
Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. |
Field Details
WHEEL_UNIT_SCROLL
@Native public static final int WHEEL_UNIT_SCROLL
- See Also:
WHEEL_BLOCK_SCROLL
@Native public static final int WHEEL_BLOCK_SCROLL
- See Also:
Constructor Details
MouseWheelEvent
public MouseWheelEvent(Component source, int id, long when, int modifiers, int x, int y, int clickCount, boolean popupTrigger, int scrollType, int scrollAmount, int wheelRotation)
MouseWheelEvent object with the specified source component, type, modifiers, coordinates, scroll type, scroll amount, and wheel rotation. Absolute coordinates xAbs and yAbs are set to source's location on screen plus relative coordinates x and y. xAbs and yAbs are set to zero if the source is not showing.
Note that passing in an invalid id results in unspecified behavior. This method throws an IllegalArgumentException if source is null.
- Parameters:
-
source- theComponentthat originated the event -
id- the integer that identifies the event -
when- a long that gives the time the event occurred -
modifiers- the modifier keys down during event (shift, ctrl, alt, meta) -
x- the horizontal x coordinate for the mouse location -
y- the vertical y coordinate for the mouse location -
clickCount- the number of mouse clicks associated with event -
popupTrigger- a boolean, true if this event is a trigger for a popup-menu -
scrollType- the type of scrolling which should take place in response to this event; valid values areWHEEL_UNIT_SCROLLandWHEEL_BLOCK_SCROLL -
scrollAmount- for scrollTypeWHEEL_UNIT_SCROLL, the number of units to be scrolled -
wheelRotation- the integer number of "clicks" by which the mouse wheel was rotated - Throws:
-
IllegalArgumentException- ifsourceis null - See Also:
MouseWheelEvent
public MouseWheelEvent(Component source, int id, long when, int modifiers, int x, int y, int xAbs, int yAbs, int clickCount, boolean popupTrigger, int scrollType, int scrollAmount, int wheelRotation)
MouseWheelEvent object with the specified source component, type, modifiers, coordinates, absolute coordinates, scroll type, scroll amount, and wheel rotation. Note that passing in an invalid id results in unspecified behavior. This method throws an IllegalArgumentException if source is null.
Even if inconsistent values for relative and absolute coordinates are passed to the constructor, the MouseWheelEvent instance is still created and no exception is thrown.
- Parameters:
-
source- theComponentthat originated the event -
id- the integer that identifies the event -
when- a long that gives the time the event occurred -
modifiers- the modifier keys down during event (shift, ctrl, alt, meta) -
x- the horizontal x coordinate for the mouse location -
y- the vertical y coordinate for the mouse location -
xAbs- the absolute horizontal x coordinate for the mouse location -
yAbs- the absolute vertical y coordinate for the mouse location -
clickCount- the number of mouse clicks associated with event -
popupTrigger- a boolean, true if this event is a trigger for a popup-menu -
scrollType- the type of scrolling which should take place in response to this event; valid values areWHEEL_UNIT_SCROLLandWHEEL_BLOCK_SCROLL -
scrollAmount- for scrollTypeWHEEL_UNIT_SCROLL, the number of units to be scrolled -
wheelRotation- the integer number of "clicks" by which the mouse wheel was rotated - Throws:
-
IllegalArgumentException- ifsourceis null - Since:
- 1.6
- See Also:
MouseWheelEvent
public MouseWheelEvent(Component source, int id, long when, int modifiers, int x, int y, int xAbs, int yAbs, int clickCount, boolean popupTrigger, int scrollType, int scrollAmount, int wheelRotation, double preciseWheelRotation)
MouseWheelEvent object with the specified source component, type, modifiers, coordinates, absolute coordinates, scroll type, scroll amount, and wheel rotation. Note that passing in an invalid id parameter results in unspecified behavior. This method throws an IllegalArgumentException if source equals null.
Even if inconsistent values for relative and absolute coordinates are passed to the constructor, a MouseWheelEvent instance is still created and no exception is thrown.
- Parameters:
-
source- theComponentthat originated the event -
id- the integer value that identifies the event -
when- a long value that gives the time when the event occurred -
modifiers- the modifier keys down during event (shift, ctrl, alt, meta) -
x- the horizontalxcoordinate for the mouse location -
y- the verticalycoordinate for the mouse location -
xAbs- the absolute horizontalxcoordinate for the mouse location -
yAbs- the absolute verticalycoordinate for the mouse location -
clickCount- the number of mouse clicks associated with the event -
popupTrigger- a boolean value,trueif this event is a trigger for a popup-menu -
scrollType- the type of scrolling which should take place in response to this event; valid values areWHEEL_UNIT_SCROLLandWHEEL_BLOCK_SCROLL -
scrollAmount- for scrollTypeWHEEL_UNIT_SCROLL, the number of units to be scrolled -
wheelRotation- the integer number of "clicks" by which the mouse wheel was rotated -
preciseWheelRotation- the double number of "clicks" by which the mouse wheel was rotated - Throws:
-
IllegalArgumentException- ifsourceis null - Since:
- 1.7
- See Also:
Method Details
getScrollType
public int getScrollType()
- MouseWheelEvent.WHEEL_UNIT_SCROLL
- MouseWheelEvent.WHEEL_BLOCK_SCROLL
- Returns:
- either MouseWheelEvent.WHEEL_UNIT_SCROLL or MouseWheelEvent.WHEEL_BLOCK_SCROLL, depending on the configuration of the native platform.
- See Also:
getScrollAmount
public int getScrollAmount()
getScrollType returns MouseWheelEvent.WHEEL_UNIT_SCROLL
- Returns:
- number of units to scroll, or an undefined value if
getScrollTypereturnsMouseWheelEvent.WHEEL_BLOCK_SCROLL - See Also:
getWheelRotation
public int getWheelRotation()
- Returns:
- negative values if the mouse wheel was rotated up/away from the user, and positive values if the mouse wheel was rotated down/ towards the user
- See Also:
getPreciseWheelRotation
public double getPreciseWheelRotation()
- Returns:
- negative values if the mouse wheel was rotated up or away from the user, and positive values if the mouse wheel was rotated down or towards the user
- Since:
- 1.7
- See Also:
getUnitsToScroll
public int getUnitsToScroll()
ScrollPane and JScrollPane already have this functionality built in.) This method returns the number of units to scroll when scroll type is MouseWheelEvent.WHEEL_UNIT_SCROLL, and should only be called if getScrollType returns MouseWheelEvent.WHEEL_UNIT_SCROLL.
Direction of scroll, amount of wheel movement, and platform settings for wheel scrolling are all accounted for. This method does not and cannot take into account value of the Adjustable/Scrollable unit increment, as this will vary among scrolling components.
A simplified example of how this method might be used in a listener:
mouseWheelMoved(MouseWheelEvent event) {
ScrollPane sp = getScrollPaneFromSomewhere();
Adjustable adj = sp.getVAdjustable()
if (MouseWheelEvent.getScrollType() == WHEEL_UNIT_SCROLL) {
int totalScrollAmount =
event.getUnitsToScroll() *
adj.getUnitIncrement();
adj.setValue(adj.getValue() + totalScrollAmount);
}
}
- Returns:
- the number of units to scroll based on the direction and amount of mouse wheel rotation, and on the wheel scrolling settings of the native platform
- See Also:
paramString
public String paramString()
- Overrides:
-
paramStringin classMouseEvent - Returns:
- a string identifying the event and its attributes
© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
InputEvent.getModifiersEx()be used instead