ScrollEvent (JavaFX 13)

Module javafx.graphics
Package javafx.scene.input

## Class ScrollEvent

- java.lang.Object
- - java.util.EventObject
  - - javafx.event.Event
    - - javafx.scene.input.InputEvent
      - - javafx.scene.input.GestureEvent
        - - javafx.scene.input.ScrollEvent

- All Implemented Interfaces:
    `Serializable`, `Cloneable`

      public final class ScrollEvent
      extends GestureEvent

  Scroll event indicates that user performed scrolling by mouse wheel, track pad, touch screen or other similar device.

  When the scrolling is produced by a touch gesture (such as dragging a finger over a touch screen), it is surrounded by the `SCROLL_STARTED` and `SCROLL_FINISHED` events. Changing number of involved touch points during the scrolling is considered a new gesture, so the pair of `SCROLL_FINISHED` and `SCROLL_STARTED` notifications is delivered each time the `touchCount` changes. When the scrolling is caused by a mouse wheel rotation, only a one-time `SCROLL` event is delivered, without the started/finished surroundings. If scrolling inertia is active on the given platform, some `SCROLL` events with `isInertia()` returning `true` can come after `SCROLL_FINISHED`.

  The event is delivered to the top-most node picked on the gesture coordinates in time of the gesture start - the whole gesture is delivered to the same node even if the coordinates change during the gesture. For mouse wheel rotation the event is delivered to the top-most node picked on mouse cursor location. The delivery is independent of current focus owner.

  The event provides two different types of scrolling values: pixel-based and character/line-based. The basic `deltaX` and `deltaY` values give reasonable results when used as number of pixels to scroll (The `totalDeltaX` and `totalDeltaY` contain the cumulative values for the whole gesture, zeros for mouse wheel). For scrolling text (or other line-based content as tables) the `textDelta` values should be used if they are available. The `textDeltaXUnits` and `textDeltaYUnits` determine how to interpret the `textDeltaX` and `textDeltaY` values. If the units are set to `NONE`, the text-based values are not available (not provided by the underlying platform) and the pixel-based values need to be used.

  As all gestures, scrolling can be direct (performed directly at the concrete coordinates as on touch screen - the center point among all the touches is usually used as the gesture coordinates) or indirect (performed indirectly as on track pad or with mouse - the mouse cursor location is usually used as the gesture coordinates).

  For example, scrolling a graphical node can be achieved by following code:

          node.setOnScroll(new EventHandler<ScrollEvent>() {
              @Override public void handle(ScrollEvent event) {
                  node.setTranslateX(node.getTranslateX() + event.getDeltaX());
                  node.setTranslateY(node.getTranslateY() + event.getDeltaY());
              }
          });

  A scroll event handler on text-based component behaving according to system settings on all platforms should contain following logic:

          switch(event.getTextDeltaYUnits()) {
              case LINES:
                  // scroll about event.getTextDeltaY() lines
                  break;
              case PAGES:
                  // scroll about event.getTextDeltaY() pages
                  break;
              case NONE:
                  // scroll about event.getDeltaY() pixels
                  break;
          }

  Since:
    JavaFX 2.0
  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `ScrollEvent.HorizontalTextScrollUnits` | Horizontal text-based scrolling units.
    `static class` | `ScrollEvent.VerticalTextScrollUnits` | Vertical text-based scrolling units.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static EventType<ScrollEvent>` | `ANY` | Common supertype for all scroll event types.
    `static EventType<ScrollEvent>` | `SCROLL` | This event occurs when user performs a scrolling action such as rotating mouse wheel or dragging a finger over touch screen.
    `static EventType<ScrollEvent>` | `SCROLL_FINISHED` | This event occurs when a scrolling gesture ends.
    `static EventType<ScrollEvent>` | `SCROLL_STARTED` | This event occurs when a scrolling gesture is detected.

    - ### Fields inherited from class javafx.event.Event

      `consumed, eventType, NULL_SOURCE_TARGET, target`

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

      `source`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `ScrollEvent​(Object source, EventTarget target, EventType<ScrollEvent> eventType, double x, double y, double screenX, double screenY, boolean shiftDown, boolean controlDown, boolean altDown, boolean metaDown, boolean direct, boolean inertia, double deltaX, double deltaY, double totalDeltaX, double totalDeltaY, ScrollEvent.HorizontalTextScrollUnits textDeltaXUnits, double textDeltaX, ScrollEvent.VerticalTextScrollUnits textDeltaYUnits, double textDeltaY, int touchCount, PickResult pickResult)` | Constructs new ScrollEvent event.
    `ScrollEvent​(EventType<ScrollEvent> eventType, double x, double y, double screenX, double screenY, boolean shiftDown, boolean controlDown, boolean altDown, boolean metaDown, boolean direct, boolean inertia, double deltaX, double deltaY, double totalDeltaX, double totalDeltaY, double multiplierX, double multiplierY, ScrollEvent.HorizontalTextScrollUnits textDeltaXUnits, double textDeltaX, ScrollEvent.VerticalTextScrollUnits textDeltaYUnits, double textDeltaY, int touchCount, PickResult pickResult)` | Constructs new ScrollEvent event with null source and target
    `ScrollEvent​(EventType<ScrollEvent> eventType, double x, double y, double screenX, double screenY, boolean shiftDown, boolean controlDown, boolean altDown, boolean metaDown, boolean direct, boolean inertia, double deltaX, double deltaY, double totalDeltaX, double totalDeltaY, ScrollEvent.HorizontalTextScrollUnits textDeltaXUnits, double textDeltaX, ScrollEvent.VerticalTextScrollUnits textDeltaYUnits, double textDeltaY, int touchCount, PickResult pickResult)` | Constructs new ScrollEvent event with null source and target

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `ScrollEvent` | `copyFor​(Object newSource, EventTarget newTarget)` | Creates and returns a copy of this event with the specified event source and target.
    `ScrollEvent` | `copyFor​(Object newSource, EventTarget newTarget, EventType<ScrollEvent> type)` | Creates a copy of the given event with the given fields substituted.
    `double` | `getDeltaX()` | Gets the horizontal scroll amount.
    `double` | `getDeltaY()` | Gets the vertical scroll amount.
    `EventType<ScrollEvent>` | `getEventType()` | Gets the event type of this event.
    `double` | `getMultiplierX()` | Gets the multiplier used to convert mouse wheel rotation units to pixels
    `double` | `getMultiplierY()` | Gets the multiplier used to convert mouse wheel rotation units to pixels
    `double` | `getTextDeltaX()` | Gets the horizontal text-based scroll amount.
    `ScrollEvent.HorizontalTextScrollUnits` | `getTextDeltaXUnits()` | Gets the horizontal scrolling units for text-based scrolling.
    `double` | `getTextDeltaY()` | Gets the vertical text-based scroll amount.
    `ScrollEvent.VerticalTextScrollUnits` | `getTextDeltaYUnits()` | Gets the vertical scrolling units for text-based scrolling.
    `double` | `getTotalDeltaX()` | Gets the cumulative horizontal scroll amount for the whole gesture.
    `double` | `getTotalDeltaY()` | Gets the cumulative vertical scroll amount for the whole gesture.
    `int` | `getTouchCount()` | Gets number of touch points that caused this event.
    `String` | `toString()` | Returns a string representation of this `ScrollEvent` object.

    - ### Methods inherited from class javafx.scene.input.GestureEvent

      `getPickResult, getSceneX, getSceneY, getScreenX, getScreenY, getX, getY, getZ, isAltDown, isControlDown, isDirect, isInertia, isMetaDown, isShiftDown, isShortcutDown`

    - ### Methods inherited from class javafx.event.Event

      `clone, consume, fireEvent, getTarget, isConsumed`

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

      `getSource`

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

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

- - ### Field Detail

    - #### ANY

          public static final EventType<ScrollEvent> ANY

      Common supertype for all scroll event types.

    - #### SCROLL

          public static final EventType<ScrollEvent> SCROLL

      This event occurs when user performs a scrolling action such as rotating mouse wheel or dragging a finger over touch screen.

    - #### SCROLL_STARTED

          public static final EventType<ScrollEvent> SCROLL_STARTED

      This event occurs when a scrolling gesture is detected. It doesn't occur for mouse wheel scrolling.
      Since:
        JavaFX 2.2

    - #### SCROLL_FINISHED

          public static final EventType<ScrollEvent> SCROLL_FINISHED

      This event occurs when a scrolling gesture ends. It doesn't occur for mouse wheel scrolling.
      Since:
        JavaFX 2.2

  - ### Constructor Detail

    - #### ScrollEvent

          public ScrollEvent​(Object source,
                             EventTarget target,
                             EventType<ScrollEvent> eventType,
                             double x,
                             double y,
                             double screenX,
                             double screenY,
                             boolean shiftDown,
                             boolean controlDown,
                             boolean altDown,
                             boolean metaDown,
                             boolean direct,
                             boolean inertia,
                             double deltaX,
                             double deltaY,
                             double totalDeltaX,
                             double totalDeltaY,
                             ScrollEvent.HorizontalTextScrollUnits textDeltaXUnits,
                             double textDeltaX,
                             ScrollEvent.VerticalTextScrollUnits textDeltaYUnits,
                             double textDeltaY,
                             int touchCount,
                             PickResult pickResult)

      Constructs new ScrollEvent event.
      Parameters:
        `source` - the source of the event. Can be null.
        `target` - the target of the event. Can be null.
        `eventType` - The type of the event.
        `x` - The x with respect to the scene.
        `y` - The y with respect to the scene.
        `screenX` - The x coordinate relative to screen.
        `screenY` - The y coordinate relative to screen.
        `shiftDown` - true if shift modifier was pressed.
        `controlDown` - true if control modifier was pressed.
        `altDown` - true if alt modifier was pressed.
        `metaDown` - true if meta modifier was pressed.
        `direct` - true if the event was caused by direct input device. See `GestureEvent.isDirect()`
        `inertia` - if represents inertia of an already finished gesture.
        `deltaX` - horizontal scroll amount
        `deltaY` - vertical scroll amount
        `totalDeltaX` - cumulative horizontal scroll amount
        `totalDeltaY` - cumulative vertical scroll amount
        `textDeltaXUnits` - units for horizontal text-based scroll amount
        `textDeltaX` - horizontal text-based scroll amount
        `textDeltaYUnits` - units for vertical text-based scroll amount
        `textDeltaY` - vertical text-based scroll amount
        `touchCount` - number of touch points
        `pickResult` - pick result. Can be null, in this case a 2D pick result without any further values is constructed based on the scene coordinates and the target
      Since:
        JavaFX 8.0

    - #### ScrollEvent

          public ScrollEvent​(EventType<ScrollEvent> eventType,
                             double x,
                             double y,
                             double screenX,
                             double screenY,
                             boolean shiftDown,
                             boolean controlDown,
                             boolean altDown,
                             boolean metaDown,
                             boolean direct,
                             boolean inertia,
                             double deltaX,
                             double deltaY,
                             double totalDeltaX,
                             double totalDeltaY,
                             ScrollEvent.HorizontalTextScrollUnits textDeltaXUnits,
                             double textDeltaX,
                             ScrollEvent.VerticalTextScrollUnits textDeltaYUnits,
                             double textDeltaY,
                             int touchCount,
                             PickResult pickResult)

      Constructs new ScrollEvent event with null source and target
      Parameters:
        `eventType` - The type of the event.
        `x` - The x with respect to the scene.
        `y` - The y with respect to the scene.
        `screenX` - The x coordinate relative to screen.
        `screenY` - The y coordinate relative to screen.
        `shiftDown` - true if shift modifier was pressed.
        `controlDown` - true if control modifier was pressed.
        `altDown` - true if alt modifier was pressed.
        `metaDown` - true if meta modifier was pressed.
        `direct` - true if the event was caused by direct input device. See `GestureEvent.isDirect()`
        `inertia` - if represents inertia of an already finished gesture.
        `deltaX` - horizontal scroll amount
        `deltaY` - vertical scroll amount
        `totalDeltaX` - cumulative horizontal scroll amount
        `totalDeltaY` - cumulative vertical scroll amount
        `textDeltaXUnits` - units for horizontal text-based scroll amount
        `textDeltaX` - horizontal text-based scroll amount
        `textDeltaYUnits` - units for vertical text-based scroll amount
        `textDeltaY` - vertical text-based scroll amount
        `touchCount` - number of touch points
        `pickResult` - pick result. Can be null, in this case a 2D pick result without any further values is constructed based on the scene coordinates
      Since:
        JavaFX 8.0

    - #### ScrollEvent

          public ScrollEvent​(EventType<ScrollEvent> eventType,
                             double x,
                             double y,
                             double screenX,
                             double screenY,
                             boolean shiftDown,
                             boolean controlDown,
                             boolean altDown,
                             boolean metaDown,
                             boolean direct,
                             boolean inertia,
                             double deltaX,
                             double deltaY,
                             double totalDeltaX,
                             double totalDeltaY,
                             double multiplierX,
                             double multiplierY,
                             ScrollEvent.HorizontalTextScrollUnits textDeltaXUnits,
                             double textDeltaX,
                             ScrollEvent.VerticalTextScrollUnits textDeltaYUnits,
                             double textDeltaY,
                             int touchCount,
                             PickResult pickResult)

      Constructs new ScrollEvent event with null source and target
      Parameters:
        `eventType` - The type of the event.
        `x` - The x with respect to the scene.
        `y` - The y with respect to the scene.
        `screenX` - The x coordinate relative to screen.
        `screenY` - The y coordinate relative to screen.
        `shiftDown` - true if shift modifier was pressed.
        `controlDown` - true if control modifier was pressed.
        `altDown` - true if alt modifier was pressed.
        `metaDown` - true if meta modifier was pressed.
        `direct` - true if the event was caused by direct input device. See `GestureEvent.isDirect()`
        `inertia` - if represents inertia of an already finished gesture.
        `deltaX` - horizontal scroll amount
        `deltaY` - vertical scroll amount
        `totalDeltaX` - cumulative horizontal scroll amount
        `totalDeltaY` - cumulative vertical scroll amount
        `multiplierX` - an X multiplier used to convert wheel rotations to pixels
        `multiplierY` - an Y multiplier used to convert wheel rotations to pixels
        `textDeltaXUnits` - units for horizontal text-based scroll amount
        `textDeltaX` - horizontal text-based scroll amount
        `textDeltaYUnits` - units for vertical text-based scroll amount
        `textDeltaY` - vertical text-based scroll amount
        `touchCount` - number of touch points
        `pickResult` - pick result. Can be null, in this case a 2D pick result without any further values is constructed based on the scene coordinates
      Since:
        JavaFX 8.0

  - ### Method Detail

    - #### getDeltaX

          public double getDeltaX()

      Gets the horizontal scroll amount. This value should be interpreted as a number of pixels to scroll. When scrolling a text-based content, the `textDeltaX` and `textDeltaXUnits` values should be considered first.

      The sign of the value is reversed compared to the coordinate system (when you scroll right, the content actually needs to go left). So the returned value can be simply added to the content's `X` coordinate.

      Returns:
        Number of pixels to scroll horizontally

    - #### getDeltaY

          public double getDeltaY()

      Gets the vertical scroll amount. This value should be interpreted as a number of pixels to scroll. When scrolling a line-based content, the `textDeltaY` and `textDeltaYUnits` values should be considered first.

      The sign of the value is reversed compared to the coordinate system (when you scroll down, the content actually needs to go up). So the returned value can be simply added to the content's `Y` coordinate.

      Returns:
        Number of pixels to scroll vertically

    - #### getTotalDeltaX

          public double getTotalDeltaX()

      Gets the cumulative horizontal scroll amount for the whole gesture. This value should be interpreted as a number of pixels to scroll relatively to the state at the beginning of the gesture. Contains zeros for mouse wheel scrolling.

      The sign of the value is reversed compared to the coordinate system (when you scroll right, the content actually needs to go left). So the returned value can be simply added to the content's `X` coordinate.

      Returns:
        Number of pixels scrolled horizontally during the gesture
      Since:
        JavaFX 2.2

    - #### getTotalDeltaY

          public double getTotalDeltaY()

      Gets the cumulative vertical scroll amount for the whole gesture. This value should be interpreted as a number of pixels to scroll relatively to the state at the beginning of the gesture. Contains zeros for mouse wheel scrolling.

      The sign of the value is reversed compared to the coordinate system (when you scroll down, the content actually needs to go up). So the returned value can be simply added to the content's `Y` coordinate.

      Returns:
        Number of pixels to scrolled vertically during the gesture
      Since:
        JavaFX 2.2

    - #### getTextDeltaXUnits

          public ScrollEvent.HorizontalTextScrollUnits getTextDeltaXUnits()

      Gets the horizontal scrolling units for text-based scrolling. The returned value indicates how to interpret the `getTextDeltaX()` value. If the returned value is `NONE`, the text-based scrolling value is not available and the pixel-based `getDeltaX()` value needs to be used.
      Returns:
        the horizontal scrolling units for text-based scrolling

    - #### getTextDeltaYUnits

          public ScrollEvent.VerticalTextScrollUnits getTextDeltaYUnits()

      Gets the vertical scrolling units for text-based scrolling. The returned value indicates how to interpret the `getTextDeltaY()` value. If the returned value is `NONE`, the text-based scrolling value is not available and the pixel-based `getDeltaY()` value needs to be used.
      Returns:
        the vertical scrolling units for text-based scrolling

    - #### getTextDeltaX

          public double getTextDeltaX()

      Gets the horizontal text-based scroll amount. This value should be interpreted according to the `getTextDeltaXUnits()` value.
      Returns:
        Number of units to scroll horizontally, zero if the text-based horizontal scrolling data is not available `getTextDeltaXUnits()` returns `NONE`

    - #### getTextDeltaY

          public double getTextDeltaY()

      Gets the vertical text-based scroll amount. This value should be interpreted according to the `getTextDeltaYUnits()` value.
      Returns:
        Number of units to scroll vertically, zero if the text-based vertical scrolling data is not available `getTextDeltaYUnits()` returns `NONE`

    - #### getTouchCount

          public int getTouchCount()

      Gets number of touch points that caused this event. For non-touch source devices as mouse wheel and for inertia events after gesture finish it returns zero.
      Returns:
        Number of touch points that caused this event
      Since:
        JavaFX 2.2

    - #### getMultiplierX

          public double getMultiplierX()

      Gets the multiplier used to convert mouse wheel rotation units to pixels
      Returns:
        the x multiplier
      Since:
        JavaFX 8.0

    - #### getMultiplierY

          public double getMultiplierY()

      Gets the multiplier used to convert mouse wheel rotation units to pixels
      Returns:
        the y multiplier
      Since:
        JavaFX 8.0

    - #### toString

          public String toString()

      Returns a string representation of this `ScrollEvent` object.
      Overrides:
        `toString` in class `GestureEvent`
      Returns:
        a string representation of this `ScrollEvent` object.

    - #### copyFor

          public ScrollEvent copyFor​(Object newSource,
                                     EventTarget newTarget)

      Description copied from class: `GestureEvent`
      Creates and returns a copy of this event with the specified event source and target. If the source or target is set to `null`, it is replaced by the `NULL_SOURCE_TARGET` value.
      Overrides:
        `copyFor` in class `GestureEvent`
      Parameters:
        `newSource` - the new source of the copied event
        `newTarget` - the new target of the copied event
      Returns:
        the event copy with the new source and target

    - #### copyFor

          public ScrollEvent copyFor​(Object newSource,
                                     EventTarget newTarget,
                                     EventType<ScrollEvent> type)

      Creates a copy of the given event with the given fields substituted.
      Parameters:
        `newSource` - the new source of the copied event
        `newTarget` - the new target of the copied event
        `type` - the new eventType
      Returns:
        the event copy with the fields substituted
      Since:
        JavaFX 8.0

    - #### getEventType

          public EventType<ScrollEvent> getEventType()

      Description copied from class: `Event`
      Gets the event type of this event. Objects of the same `Event` class can have different event types. These event types further specify what kind of event occurred.
      Overrides:
        `getEventType` in class `GestureEvent`
      Returns:
        the event type