MouseWheelEvent (Java Platform SE 8 )
Keywords: java.awt.event.MouseWheelEvent class
Date: 2020-03-26

java.awt.event

## Class MouseWheelEvent

- java.lang.Object
- - java.util.EventObject
  - - java.awt.AWTEvent
    - - java.awt.event.ComponentEvent
      - - java.awt.event.InputEvent
        - - java.awt.event.MouseEvent
          - - java.awt.event.MouseWheelEvent

- All 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.

  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:
    `MouseWheelListener`, `ScrollPane`, `ScrollPane.setWheelScrollingEnabled(boolean)`, `JScrollPane`, `JScrollPane.setWheelScrollingEnabled(boolean)`, Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `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, 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`

    - ### Fields inherited from class java.util.EventObject

      `source`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `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.
    `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)` Constructs a `MouseWheelEvent` object with the specified source component, type, modifiers, coordinates, absolute coordinates, scroll type, scroll amount, and wheel rotation.
    `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)` Constructs a `MouseWheelEvent` object with the specified source component, type, modifiers, coordinates, absolute coordinates, scroll type, scroll amount, and wheel rotation.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and 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 inherited from class java.awt.event.MouseEvent

      `getButton, getClickCount, getLocationOnScreen, getModifiersEx, getMouseModifiersText, getPoint, getX, getXOnScreen, getY, getYOnScreen, isPopupTrigger, translatePoint`

    - ### Methods inherited from class java.awt.event.InputEvent

      `consume, getMaskForButton, getModifiers, getModifiersExText, getWhen, isAltDown, isAltGraphDown, isConsumed, isControlDown, isMetaDown, isShiftDown`

    - ### Methods inherited from class java.awt.event.ComponentEvent

      `getComponent`

    - ### Methods inherited from class java.awt.AWTEvent

      `getID, setSource, toString`

    - ### Methods inherited from class java.util.EventObject

      `getSource`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### WHEEL_UNIT_SCROLL

          @Native
          public static final int WHEEL_UNIT_SCROLL

      Constant representing scrolling by "units" (like scrolling with the arrow keys)
      See Also:
        `getScrollType()`, Constant Field Values

    - #### WHEEL_BLOCK_SCROLL

          @Native
          public static final int WHEEL_BLOCK_SCROLL

      Constant representing scrolling by a "block" (like scrolling with page-up, page-down keys)
      See Also:
        `getScrollType()`, Constant Field Values

  - ### Constructor Detail

    - #### 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.

      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 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 integer number of "clicks" by which the mouse wheel was rotated
      Throws:
        `IllegalArgumentException` - if `source` is null
      See Also:
        `MouseEvent.MouseEvent(java.awt.Component, int, long, int, int, int, int, boolean)`, `MouseEvent.MouseEvent(java.awt.Component, int, long, int, int, int, int, int, int, boolean, int)`

    - #### 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)

      Constructs a `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` - 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
        `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 are `WHEEL_UNIT_SCROLL` and `WHEEL_BLOCK_SCROLL`
        `scrollAmount` - for scrollType `WHEEL_UNIT_SCROLL`, the number of units to be scrolled
        `wheelRotation` - the integer number of "clicks" by which the mouse wheel was rotated
      Throws:
        `IllegalArgumentException` - if `source` is null
      Since:
        1.6
      See Also:
        `MouseEvent.MouseEvent(java.awt.Component, int, long, int, int, int, int, boolean)`, `MouseEvent.MouseEvent(java.awt.Component, int, long, int, int, int, int, int, int, boolean, int)`

    - #### 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)

      Constructs a `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` - the `Component` that 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 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 the event
        `popupTrigger` - a boolean value, `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 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` - if `source` is null
      Since:
        1.7
      See Also:
        `MouseEvent.MouseEvent(java.awt.Component, int, long, int, int, int, int, boolean)`, `MouseEvent.MouseEvent(java.awt.Component, int, long, int, int, int, int, int, int, boolean, int)`

  - ### Method Detail

    - #### 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.
      See Also:
        `Adjustable.getUnitIncrement()`, `Adjustable.getBlockIncrement()`, `Scrollable.getScrollableUnitIncrement(java.awt.Rectangle, int, int)`, `Scrollable.getScrollableBlockIncrement(java.awt.Rectangle, int, int)`

    - #### getScrollAmount

          public int getScrollAmount()

      Returns the number of units that should be scrolled per click of mouse wheel rotation. 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`
      See Also:
        `getScrollType()`

    - #### getWheelRotation

          public int getWheelRotation()

      Returns the number of "clicks" the mouse wheel was rotated, as an integer. A partial rotation may occur if the mouse supports a high-resolution wheel. In this case, the method returns zero until a full "click" has been accumulated.
      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()`

    - #### getPreciseWheelRotation

          public double getPreciseWheelRotation()

      Returns the number of "clicks" the mouse wheel was rotated, as a double. A partial rotation may occur if the mouse supports a high-resolution wheel. In this case, the return value will include a fractional "click".
      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:
        `getWheelRotation()`

    - #### 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
      See Also:
        `getScrollType()`, `getScrollAmount()`, `MouseWheelListener`, `Adjustable`, `Adjustable.getUnitIncrement()`, `Scrollable`, `Scrollable.getScrollableUnitIncrement(java.awt.Rectangle, int, int)`, `ScrollPane`, `ScrollPane.setWheelScrollingEnabled(boolean)`, `JScrollPane`, `JScrollPane.setWheelScrollingEnabled(boolean)`

    - #### paramString

          public String paramString()

      Returns a parameter string identifying this event. This method is useful for event-logging and for debugging.
      Overrides:
        `paramString` in class `MouseEvent`
      Returns:
        a string identifying the event and its attributes

Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2020, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.