Scroller

View source
Entity → Visual → ceramic.Scroller (Class)
Implements: tracker.Observable

A scrollable container that allows smooth scrolling and dragging of content.

Supports touch/mouse dragging, momentum scrolling, bounce effects, and optional paging. Can scroll vertically or horizontally.

Static Members

threshold: Float

Instance Members

observedDirty: Bool

Default is false, automatically set to true when any of this instance's observable variables has changed.

content: Visual

The content visual that will be scrolled.

scrollbar: Visual

Optional scrollbar visual that indicates scroll position. The scrollbar will be automatically positioned and sized.

direction: Anonymous

Scroll direction: VERTICAL or HORIZONTAL.

allowPointerOutside: Bool

Whether to allow pointer events outside the scroller bounds. When false, pointer events outside will be blocked.

scrollTransform: Transform

Transform used to position the content for scrolling.

scrollEnabled: Bool

Whether scrolling is enabled.

dragEnabled: Bool

Whether dragging to scroll is enabled.

dragThreshold: Float

If set to a value above zero, dragging should reach that value before the scroller start to actually move its content. In case the same value (or noDragThreshold value if above zero) is reached in wrong direction (vertical vs horizontal), scroll will be entirely cancelled for the current touch. This can be useful if you want to perform custom behaviour depending on the direction of the drag, or if you want to nest two scrollers that have different directions.

noDragThreshold: Float

If set to a value above zero, when reaching that value in wrong direction (vertical vs horizontal), scroll will be entirely cancelled for the current touch.

roundScrollWhenIdle: Int

If set to a value above zero, scrollX and scrollY will be rounded when scroller is idle.

roundScrollWhenIdle = 0; // No rounding (default)
roundScrollWhenIdle = 1; // Pixel perfect rounding
roundScrollWhenIdle = 2; // Half-pixel rounding
status: Anonymous

Current status of the scroller. Can be IDLE, TOUCHING, DRAGGING, or SCROLLING.

verticalToHorizontalWheel: Bool

When set to true, vertical mouse wheel events will also work on horizontal scrollers.

deceleration: Float

Deceleration rate for momentum scrolling (pixels per second squared).

wheelDeceleration: Float

Deceleration rate for mouse wheel scrolling (pixels per second squared).

wheelFactor: Float

Multiplier for mouse wheel scroll speed.

wheelMomentum: Bool

Whether to apply momentum to mouse wheel scrolling.

wheelEndDelay: Float

Delay in seconds before wheel scrolling is considered ended.

overScrollResistance: Float

Resistance factor when scrolling beyond bounds. Higher values make it harder to scroll past edges.

maxClickMomentum: Float

Maximum momentum that still allows a click to register. Higher momentum will cancel the click.

bounceMomentumFactor: Float

Factor for converting momentum to bounce distance.

bounceMinDuration: Float

Minimum duration for bounce animation in seconds.

bounceDurationFactor: Float

Factor for calculating bounce duration based on momentum.

bounceNoMomentumDuration: Float

Duration for bounce animation when there's no momentum.

dragFactor: Float

Multiplier for drag speed. Values less than 1.0 make dragging slower.

touchableStrictHierarchy: Bool

Whether to use strict hierarchy checking for touch events.

scrollX: Float

Current horizontal scroll position.

scrollY: Float

Current vertical scroll position.

scrollVelocity: Velocity

Current scroll velocity tracker. Used to calculate momentum when dragging ends.

momentum: Float

Current momentum value. Positive values scroll down/right, negative up/left.

animating: Bool

Whether the scroller is currently animating.

pagingEnabled: Bool

Enable paging of the scroller so that everytime we stop dragging, it snaps to the closest page.

pageSize: Float

When pagingEnabled is true, this is the size of a page. If kept to -1 (default), it will use the scroller size.

pageSpacing: Float

When pagingEnabled is true, this is the spacing between each page.

pageMomentumThreshold: Float

When pagingEnabled is true, this threshold value will be used to move to a sibling page if the momentum is equal or above it. If kept to -1 (default), it will use the page size.

invalidateStatus(): Void
destroy(): Void
scrollToBounds(): Void

Scroll to ensure content is within bounds. If content is smaller than the scroller, it will be positioned at 0. If scrolled beyond bounds, it will snap back to the nearest edge.

isContentPositionInBounds(x: Float, y: Float): Bool

Check if a content position is visible within the scroller bounds.

Name Type Description
x Float X position in content coordinates
y Float Y position in content coordinates
Returns Description
Bool True if the position is visible
ensureContentPositionIsInBounds(x: Float, y: Float): Void

Scroll to ensure a specific content position is visible.

Name Type Description
x Float X position in content coordinates to make visible
y Float Y position in content coordinates to make visible
isOverScrollingTop(): Bool

Check if content is scrolled beyond the top edge.

Returns Description
Bool True if over-scrolled at top
isOverScrollingBottom(): Bool

Check if content is scrolled beyond the bottom edge.

Returns Description
Bool True if over-scrolled at bottom
isOverScrollingLeft(): Bool

Check if content is scrolled beyond the left edge.

Returns Description
Bool True if over-scrolled at left
isOverScrollingRight(): Bool

Check if content is scrolled beyond the right edge.

Returns Description
Bool True if over-scrolled at right
stop(): Void

Stop all scrolling and animations immediately.

stopTweens(): Void

Stop any active scroll animations.

scrollTo(scrollX: Float, scrollY: Float): Void

Immediately scroll to a specific position.

Name Type Description
scrollX Float Target horizontal scroll position
scrollY Float Target vertical scroll position
smoothScrollTo(scrollX: Float, scrollY: Float, ?duration: Float = 0.15, ?easing: Anonymous): Void

Smoothly animate scroll to a specific position.

Name Type Default Description
scrollX Float Target horizontal scroll position
scrollY Float Target vertical scroll position
duration Float 0.15 Animation duration in seconds (default: 0.15)
easing Anonymous (optional) Easing function to use (default: QUAD_EASE_IN_OUT)
snapTo(scrollX: Float, scrollY: Float, ?duration: Float = 0.15, ?easing: Anonymous): Void
Name Type Default
scrollX Float
scrollY Float
duration Float 0.15
easing Anonymous (optional)
bounceScroll(): Void
pageIndexFromScroll(scrollX: Float, scrollY: Float): Int
Name Type
scrollX Float
scrollY Float
Returns
Int
computeTargetPageIndex(): Int
Returns
Int
scrollToPageIndex(pageIndex: Int): Void
Name Type
pageIndex Int
smoothScrollToPageIndex(pageIndex: Int, ?duration: Float = 0.15, ?easing: Anonymous, ?allowOverscroll: Bool = false): Void
Name Type Default
pageIndex Int
duration Float 0.15
easing Anonymous (optional)
allowOverscroll Bool false
getTargetScrollXForPageIndex(pageIndex: Int, ?allowOverscroll: Bool = false): Float
Name Type Default
pageIndex Int
allowOverscroll Bool false
Returns
Float
getTargetScrollYForPageIndex(pageIndex: Int, ?allowOverscroll: Bool = false): Float
Name Type Default
pageIndex Int
allowOverscroll Bool false
Returns
Float
new(?content: Visual): Void

Create a new Scroller.

Name Type Default Description
content Visual (optional) Optional content visual to scroll. If null, a new Visual is created.

Private Members

unobservedStatus: Anonymous
prevPointerX: Float
prevPointerY: Float
dragThresholdStatus: ScrollerDragThresholdStatus
position: Float
contentStart: Float
pointerStart: Float
pointerStartX: Float
pointerStartY: Float
touchIndex: Int
releaseSnap: Bool
fromWheel: Bool
lastWheelEventTime: Float
canClick: Bool
tweenX: Tween
tweenY: Tween
pointerOnScroller: Bool
pointerOnScrollerChild: Bool
blockingDefaultScroll: Bool
scrollbarDownX: Float
scrollbarDownY: Float
scrollbarStartX: Float
scrollbarStartY: Float
pageIndexOnStartDrag: Int
emitObservedDirty(instance: Scroller, fromSerializedField: Bool): Void

Event when any observable value as changed on this instance.

Name Type
instance Scroller
fromSerializedField Bool
emitAnimateStart(): Void

Event fired when scroll animation starts.

emitAnimateEnd(): Void

Event fired when scroll animation ends.

emitDragStart(): Void

Event fired when the user starts dragging.

emitDragEnd(): Void

Event fired when the user stops dragging.

emitWheelStart(): Void

Event fired when mouse wheel scrolling starts.

emitWheelEnd(): Void

Event fired when mouse wheel scrolling ends.

emitClick(info: TouchInfo): Void

Event fired when the scroller is clicked (tap without scrolling).

Name Type Description
info TouchInfo Touch information for the click
emitScrollerPointerDown(info: TouchInfo): Void

Event fired when pointer is pressed down on the scroller.

Name Type Description
info TouchInfo Touch information
emitScrollerPointerUp(info: TouchInfo): Void

Event fired when pointer is released from the scroller.

Name Type Description
info TouchInfo Touch information
emitStatusChange(current: Anonymous, previous: Anonymous): Void

Event when status field changes.

Name Type
current Anonymous
previous Anonymous
interceptPointerDown(hittingVisual: Visual, x: Float, y: Float, touchIndex: Int, buttonId: Int): Bool
Name Type
hittingVisual Visual
x Float
y Float
touchIndex Int
buttonId Int
Returns
Bool
interceptPointerOver(hittingVisual: Visual, x: Float, y: Float): Bool
Name Type
hittingVisual Visual
x Float
y Float
Returns
Bool
startTracking(): Void
stopTracking(): Void
pointerOver(info: TouchInfo): Void
Name Type
info TouchInfo
pointerOut(info: TouchInfo): Void
Name Type
info TouchInfo
mouseWheel(x: Float, y: Float): Void
Name Type
x Float
y Float
pointerDown(info: TouchInfo): Void
Name Type
info TouchInfo
pointerUp(info: TouchInfo): Void
Name Type
info TouchInfo
screenFocus(focusedVisual: Visual): Void
Name Type
focusedVisual Visual
roundScrollIfNeeded(): Void
update(delta: Float): Void
Name Type
delta Float
updateScrollbar(): Void
bindScrollbar(scrollbar: Visual): Void
Name Type
scrollbar Visual
handleScrollbarDown(info: TouchInfo): Void
Name Type
info TouchInfo
handleScrollbarUp(info: TouchInfo): Void
Name Type
info TouchInfo
handleScrollbarMove(info: TouchInfo): Void
Name Type
info TouchInfo
scrollUpdate(pointerX: Float, pointerY: Float, delta: Float, ?minusDelta: Float = 0): Void
Name Type Default
pointerX Float
pointerY Float
delta Float
minusDelta Float 0

Metadata

Name Parameters
:build tracker.macros.ObservableMacro.build()
:autoBuild tracker.macros.ObservableMacro.build()
:build tracker.macros.EventsMacro.build()
:autoBuild tracker.macros.EventsMacro.build()
:build ceramic.macros.EntityMacro.buildForCompletion()
:autoBuild ceramic.macros.EntityMacro.buildForCompletion()