java.awt.event

Class MouseWheelEvent

Implemented Interfaces:
Serializable

public class MouseWheelEvent
extends MouseEvent

An event which indicates that the mouse wheel was rotated in a component.

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.

Since:
1.4
See Also:
MouseWheelListener, ScrollPane, ScrollPane.setWheelScrollingEnabled(boolean), JScrollPane, JScrollPane.setWheelScrollingEnabled(boolean), Serialized Form

Field Summary

static int
WHEEL_BLOCK_SCROLL
Constant representing scrolling by a "block" (like scrolling with page-up, page-down keys)
static int
WHEEL_UNIT_SCROLL
Constant representing scrolling by "units" (like scrolling with the arrow keys)

Fields inherited from class java.awt.event.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

Fields inherited from class java.awt.event.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

Fields inherited from class java.awt.event.ComponentEvent

COMPONENT_FIRST, COMPONENT_HIDDEN, COMPONENT_LAST, COMPONENT_MOVED, COMPONENT_RESIZED, COMPONENT_SHOWN

Fields inherited from class java.awt.AWTEvent

ACTION_EVENT_MASK, ADJUSTMENT_EVENT_MASK, COMPONENT_EVENT_MASK, CONTAINER_EVENT_MASK, FOCUS_EVENT_MASK, HIERARCHY_BOUNDS_EVENT_MASK, HIERARCHY_EVENT_MASK, 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, consumed, id

Fields inherited from class java.util.EventObject

source

Constructor Summary

MouseWheelEvent(Component source, int id, long when, int modifiers, int x, int y, int clickCount, boolean popupTrigger, int scrollType, int scrollAmount, int wheelRotation)
Constructs a MouseWheelEvent object with the specified source component, type, modifiers, coordinates, scroll type, scroll amount, and wheel rotation.

Method Summary

int
getScrollAmount()
Returns the number of units that should be scrolled in response to this event.
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.
String
paramString()
Returns a parameter string identifying this event.

Methods inherited from class java.awt.event.MouseEvent

getButton, getClickCount, getMouseModifiersText, getPoint, getX, getY, isPopupTrigger, paramString, translatePoint

Methods inherited from class java.awt.event.InputEvent

consume, getModifiers, getModifiersEx, getModifiersExText, getWhen, isAltDown, isAltGraphDown, isConsumed, isControlDown, isMetaDown, isShiftDown

Methods inherited from class java.awt.event.ComponentEvent

getComponent, paramString

Methods inherited from class java.awt.AWTEvent

consume, getID, isConsumed, paramString, setSource, toString

Methods inherited from class java.util.EventObject

getSource, toString

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

WHEEL_BLOCK_SCROLL

public static final int WHEEL_BLOCK_SCROLL
Constant representing scrolling by a "block" (like scrolling with page-up, page-down keys)
Field Value:
1
Usages and Demos :

View More Examples of MouseWheelEvent.WHEEL_BLOCK_SCROLL
   1:             
   2:             case MouseWheelEvent.WHEEL_BLOCK_SCROLL:
   3:                 mouseWheelRotatedByBlock(event);
   4:                 break;
   5:                 

View Full Code Here
   1:                     case MouseWheelEvent.WHEEL_UNIT_SCROLL:
   2:                     case MouseWheelEvent.WHEEL_BLOCK_SCROLL:
   3:                         aResult = getAcceptsMouseWheelRotated();
   4:                         break;
   5:                         

View Full Code Here

WHEEL_UNIT_SCROLL

public static final int WHEEL_UNIT_SCROLL
Constant representing scrolling by "units" (like scrolling with the arrow keys)
Field Value:
0
Usages and Demos :

View More Examples of MouseWheelEvent.WHEEL_UNIT_SCROLL
   1: 
   2:             case MouseWheelEvent.WHEEL_UNIT_SCROLL:
   3:                 mouseWheelRotated(event);
   4:                 break;
   5:             

View Full Code Here
   1: 
   2:                     case MouseWheelEvent.WHEEL_UNIT_SCROLL:
   3:                     case MouseWheelEvent.WHEEL_BLOCK_SCROLL:
   4:                         aResult = getAcceptsMouseWheelRotated();
   5:                         break;

View Full Code Here
   1:             1, System.currentTimeMillis(), 0, 0, 0, 2, false,
   2:             MouseWheelEvent.WHEEL_UNIT_SCROLL, 1, 1 );
   3:         this.vw.mouseWheelMoved( mwe );
   4:         
   5:         assertEquals( "Did not fire a wheel event to listener 1.",

View Full Code Here

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)
Constructs a MouseWheelEvent object with the specified source component, type, modifiers, 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.

Parameters:
source - the Component that 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 are WHEEL_UNIT_SCROLL and WHEEL_BLOCK_SCROLL
scrollAmount - for scrollType WHEEL_UNIT_SCROLL, the number of units to be scrolled
wheelRotation - the amount that the mouse wheel was rotated (the number of "clicks")
Throws:
IllegalArgumentException - if source is null

Method Details

getScrollAmount

public int getScrollAmount()
Returns the number of units that should be scrolled in response to this event. Only valid if getScrollType returns MouseWheelEvent.WHEEL_UNIT_SCROLL
Returns:
number of units to scroll, or an undefined value if getScrollType returns MouseWheelEvent.WHEEL_BLOCK_SCROLL
Usages and Demos :

View More Examples of getScrollAmount()
   1: 
   2: import java.awt.event.MouseWheelEvent;
   3: import java.awt.event.MouseWheelListener;
   4:         ...
   5:     }
   6:     public void mouseWheelMoved (MouseWheelEvent e)
   7:         ...
   8:     {    if (e.getScrollType()==MouseWheelEvent.WHEEL_BLOCK_SCROLL)
   9:         {    if (e.getWheelRotation()>0)
  10:         ...
  11:         else
  12:         {    int n=e.getScrollAmount();

View Full Code Here
   1: 
   2: import java.awt.event.MouseWheelEvent;
   3: import java.awt.event.MouseWheelListener;
   4:         ...
   5:     
   6:     public void mouseWheelMoved (MouseWheelEvent e)
   7:         ...
   8:     {    if (e.getScrollType()==MouseWheelEvent.WHEEL_BLOCK_SCROLL)
   9:         {    if (e.getWheelRotation()>0)
  10:         ...
  11:         else
  12:         {    int n=e.getScrollAmount();

View Full Code Here
   1: import java.awt.event.MouseEvent;
   2: import java.awt.event.MouseWheelEvent;
   3: 
   4:         ...
   5:             if(id == MouseEvent.MOUSE_WHEEL) {
   6:                 MouseWheelEvent mouseWheelEvent = (MouseWheelEvent) mouseEvent;
   7:                 int             scrollType = mouseWheelEvent.getScrollType();
   8:         ...
   9:                 int             scrollAmount = mouseWheelEvent.getScrollAmount();
  10:                 int             wheelRotation = mouseWheelEvent.getWheelRotation();

View Full Code Here

getScrollType

public int getScrollType()
Returns the type of scrolling that should take place in response to this event. This is determined by the native platform. Legal values are:
  • 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.
Usages and Demos :

View More Examples of getScrollType()
   1: import java.awt.event.MouseEvent;
   2: import java.awt.event.MouseWheelEvent;
   3: 
   4:         ...
   5:             if(id == MouseEvent.MOUSE_WHEEL) {
   6:                 MouseWheelEvent mouseWheelEvent = (MouseWheelEvent) mouseEvent;
   7:         ...
   8:                 int             scrollType = mouseWheelEvent.getScrollType();
   9:                 int             scrollAmount = mouseWheelEvent.getScrollAmount();

View Full Code Here

getUnitsToScroll

public 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. (Note, however, that 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

getWheelRotation

public int getWheelRotation()
Returns the number of "clicks" the mouse wheel was rotated.
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
Usages and Demos :

View More Examples of getWheelRotation()
   1: import java.awt.event.MouseEvent;
   2: import java.awt.event.MouseWheelEvent;
   3: 
   4:         ...
   5:     
   6:     public MouseWheelCaptureEvent( MouseWheelEvent event )
   7:     {
   8:         ...
   9:         
  10:         this.rotation = event.getWheelRotation();
  11:     }

View Full Code Here
   1: 
   2: import java.awt.event.MouseWheelEvent;
   3: 
   4:         ...
   5:     
   6:     public void itemWheelMoved(VisualItem item, MouseWheelEvent e) {
   7:         if ( zoomOverItem )
   8:         ...
   9:     
  10:     public void mouseWheelMoved(MouseWheelEvent e) {
  11:         zoom(e);
  12:         ...
  13:         
  14:         double zoom = 1 + 0.1f * e.getWheelRotation();

View Full Code Here
   1:     
   2:     public void mouseWheelMoved(MouseWheelEvent e)
   3:     {
   4:         ...
   5:         int notches = e.getWheelRotation();
   6:         int vertValue = vert.getValue() + notches;
   7:         int scroll = count/2;
   8:         if (count%2 == 1) scroll++;

View Full Code Here
   1: import java.awt.event.MouseEvent;
   2: import java.awt.event.MouseWheelEvent;
   3: 
   4:         ...
   5:             if(id == MouseEvent.MOUSE_WHEEL) {
   6:                 MouseWheelEvent mouseWheelEvent = (MouseWheelEvent) mouseEvent;
   7:                 int             scrollType = mouseWheelEvent.getScrollType();
   8:         ...
   9:                 int             scrollAmount = mouseWheelEvent.getScrollAmount();
  10:                 int             wheelRotation = mouseWheelEvent.getWheelRotation();
  11:                 newEvent = new MouseWheelEvent(parentComponent, id, when, modifiers, point.x, point.y,

View Full Code Here
   1: import java.awt.*;
   2: import java.awt.event.MouseWheelEvent;
   3: import java.awt.event.MouseWheelListener;
   4:         ...
   5:             lblImage.addMouseWheelListener(new MouseWheelListener() {
   6:                 public void mouseWheelMoved(MouseWheelEvent evt) {
   7:         ...
   8:                     resizeImage(evt.getWheelRotation());
   9:                 }

View Full Code Here

paramString

public String paramString()
Returns a parameter string identifying this event. This method is useful for event-logging and for debugging.
Overrides:
paramString in interface MouseEvent
Returns:
a string identifying the event and its attributes