- All Implemented Interfaces:
Serializable
,Cloneable
public final class ScrollEvent extends GestureEvent
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 targetScrollEvent(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
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 pixelsdouble
getMultiplierY()
Gets the multiplier used to convert mouse wheel rotation units to pixelsdouble
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 thisScrollEvent
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 java.util.EventObject
getSource
-
Field Details
-
ANY
Common supertype for all scroll event types. -
SCROLL
This event occurs when user performs a scrolling action such as rotating mouse wheel or dragging a finger over touch screen. -
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
This event occurs when a scrolling gesture ends. It doesn't occur for mouse wheel scrolling.- Since:
- JavaFX 2.2
-
-
Constructor Details
-
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. SeeGestureEvent.isDirect()
inertia
- if represents inertia of an already finished gesture.deltaX
- horizontal scroll amountdeltaY
- vertical scroll amounttotalDeltaX
- cumulative horizontal scroll amounttotalDeltaY
- cumulative vertical scroll amounttextDeltaXUnits
- units for horizontal text-based scroll amounttextDeltaX
- horizontal text-based scroll amounttextDeltaYUnits
- units for vertical text-based scroll amounttextDeltaY
- vertical text-based scroll amounttouchCount
- number of touch pointspickResult
- 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. SeeGestureEvent.isDirect()
inertia
- if represents inertia of an already finished gesture.deltaX
- horizontal scroll amountdeltaY
- vertical scroll amounttotalDeltaX
- cumulative horizontal scroll amounttotalDeltaY
- cumulative vertical scroll amounttextDeltaXUnits
- units for horizontal text-based scroll amounttextDeltaX
- horizontal text-based scroll amounttextDeltaYUnits
- units for vertical text-based scroll amounttextDeltaY
- vertical text-based scroll amounttouchCount
- number of touch pointspickResult
- 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. SeeGestureEvent.isDirect()
inertia
- if represents inertia of an already finished gesture.deltaX
- horizontal scroll amountdeltaY
- vertical scroll amounttotalDeltaX
- cumulative horizontal scroll amounttotalDeltaY
- cumulative vertical scroll amountmultiplierX
- an X multiplier used to convert wheel rotations to pixelsmultiplierY
- an Y multiplier used to convert wheel rotations to pixelstextDeltaXUnits
- units for horizontal text-based scroll amounttextDeltaX
- horizontal text-based scroll amounttextDeltaYUnits
- units for vertical text-based scroll amounttextDeltaY
- vertical text-based scroll amounttouchCount
- number of touch pointspickResult
- 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 Details
-
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, thetextDeltaX
andtextDeltaXUnits
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, thetextDeltaY
andtextDeltaYUnits
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
Gets the horizontal scrolling units for text-based scrolling. The returned value indicates how to interpret thegetTextDeltaX()
value. If the returned value isNONE
, the text-based scrolling value is not available and the pixel-basedgetDeltaX()
value needs to be used.- Returns:
- the horizontal scrolling units for text-based scrolling
-
getTextDeltaYUnits
Gets the vertical scrolling units for text-based scrolling. The returned value indicates how to interpret thegetTextDeltaY()
value. If the returned value isNONE
, the text-based scrolling value is not available and the pixel-basedgetDeltaY()
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 thegetTextDeltaXUnits()
value.- Returns:
- Number of units to scroll horizontally, zero if the text-based
horizontal scrolling data is not available
getTextDeltaXUnits()
returnsNONE
-
getTextDeltaY
public double getTextDeltaY()Gets the vertical text-based scroll amount. This value should be interpreted according to thegetTextDeltaYUnits()
value.- Returns:
- Number of units to scroll vertically, zero if the text-based
vertical scrolling data is not available
getTextDeltaYUnits()
returnsNONE
-
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
Returns a string representation of thisScrollEvent
object.- Overrides:
toString
in classGestureEvent
- Returns:
- a string representation of this
ScrollEvent
object.
-
copyFor
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 tonull
, it is replaced by theNULL_SOURCE_TARGET
value.- Overrides:
copyFor
in classGestureEvent
- Parameters:
newSource
- the new source of the copied eventnewTarget
- the new target of the copied event- Returns:
- the event copy with the new source and target
-
copyFor
Creates a copy of the given event with the given fields substituted.- Parameters:
newSource
- the new source of the copied eventnewTarget
- the new target of the copied eventtype
- the new eventType- Returns:
- the event copy with the fields substituted
- Since:
- JavaFX 8.0
-
getEventType
Description copied from class:Event
Gets the event type of this event. Objects of the sameEvent
class can have different event types. These event types further specify what kind of event occurred.- Overrides:
getEventType
in classGestureEvent
- Returns:
- the event type
-