Java Doc for MouseWheelEvent.java in  » 6.0-JDK-Core » AWT » java » awt » event » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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.
author:
   Brent Christian
version:
   1.20 05/05/07
See Also:   MouseWheelListener
See Also:   java.awt.ScrollPane
See Also:   java.awt.ScrollPane.setWheelScrollingEnabled(boolean)
See Also:   javax.swing.JScrollPane
See Also:   javax.swing.JScrollPane.setWheelScrollingEnabled(boolean)
since:
   1.4

Absolute coordinates xAbs and yAbs are set to source's location on screen plus relative coordinates x and y.

Note that passing in an invalid id results in unspecified behavior.

• WHEEL_UNIT_SCROLL
• WHEEL_BLOCK_SCROLL

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 - the Component that originatedthe event
Parameters:
  id - the integer that identifies the event
Parameters:
  when - a long that gives the time the event occurred
Parameters:
  modifiers - the modifier keys down during event(shift, ctrl, alt, meta)
Parameters:
  x - the horizontal x coordinate for the mouse location
Parameters:
  y - the vertical y coordinate for the mouse location
Parameters:
  clickCount - the number of mouse clicks associated with event
Parameters:
  popupTrigger - a boolean, true if this event is a trigger for apopup-menu
Parameters:
  scrollType - the type of scrolling which should take place inresponse to this event; valid values areWHEEL_UNIT_SCROLL andWHEEL_BLOCK_SCROLL
Parameters:
  scrollAmount - for scrollType WHEEL_UNIT_SCROLL,the number of units to be scrolled
Parameters:
  wheelRotation - the amount that the mouse wheel was rotated (thenumber of "clicks")
throws:
  IllegalArgumentException - if source is null
See Also:   MouseEvent.MouseEvent(java.awt.Componentintlongintintintintboolean)
See Also:   MouseEvent.MouseEvent(java.awt.Componentintlongintintintintintintbooleanint)

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 - the Component that originatedthe event
Parameters:
  id - the integer that identifies the event
Parameters:
  when - a long that gives the time the event occurred
Parameters:
  modifiers - the modifier keys down during event(shift, ctrl, alt, meta)
Parameters:
  x - the horizontal x coordinate for the mouse location
Parameters:
  y - the vertical y coordinate for the mouse location
Parameters:
  xAbs - the absolute horizontal x coordinate for the mouse location
Parameters:
  yAbs - the absolute vertical y coordinate for the mouse location
Parameters:
  clickCount - the number of mouse clicks associated with event
Parameters:
  popupTrigger - a boolean, true if this event is a trigger for apopup-menu
Parameters:
  scrollType - the type of scrolling which should take place inresponse to this event; valid values areWHEEL_UNIT_SCROLL andWHEEL_BLOCK_SCROLL
Parameters:
  scrollAmount - for scrollType WHEEL_UNIT_SCROLL,the number of units to be scrolled
Parameters:
  wheelRotation - the amount that the mouse wheel was rotated (thenumber of "clicks")
throws:
  IllegalArgumentException - if source is null
See Also:   MouseEvent.MouseEvent(java.awt.Componentintlongintintintintboolean)
See Also:   MouseEvent.MouseEvent(java.awt.Componentintlongintintintintintintbooleanint)
since:
   1.6

• MouseWheelEvent.WHEEL_UNIT_SCROLL
• MouseWheelEvent.WHEEL_BLOCK_SCROLL

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);
 }
 }