Skip to content
This repository has been archived by the owner on Dec 2, 2021. It is now read-only.

Latest commit

 

History

History
285 lines (237 loc) · 16.3 KB

ScrollController.md

File metadata and controls

285 lines (237 loc) · 16.3 KB

##ScrollController Scrollable layout-controller.

Key features:

  • Customizable layout
  • Insert/remove renderables into the scene using animations/spec
  • Support for true size renderables
  • Horizontal/vertical direction
  • Top/left or bottom/right alignment
  • Pagination
  • Option to embed in a ContainerSurface

Events:

event description
scrollstart Emitted when scrolling starts.
scroll Emitted as the content scrolls (once for each frame the visible offset has changed).
pagechange Emitted whenever the visible page changes.
scrollend Emitted after scrolling stops (when the scroll particle settles).

Inherited from: LayoutController

###class: ScrollController ⇐ LayoutController ⏏ Extends: LayoutController
####new ScrollController(options)

Param Type Description
options Object Configurable options (see LayoutController for all inherited options).
[options.useContainer] Bool Embeds the view in a ContainerSurface to hide any overflow and capture input events (default: false).
[options.container] String Options that are passed to the ContainerSurface in case useContainer is true.
[options.paginated] Bool Enabled pagination when set to true (default: false).
[options.paginationEnergyThresshold] Number Thresshold after which pagination kicks in (default: 0.01).
[options.paginationMode] PaginationMode Pagination-mode (either page-based or scroll-based) (default: PaginationMode.PAGE).
[options.alignment] Number Alignment of the renderables (0 = top/left, 1 = bottom/right) (default: 0).
[options.mouseMove] Bool Enables scrolling by holding the mouse-button down and moving the mouse (default: false).
[options.enabled] Bool Enables or disabled user input (default: true).
[options.nodeSpring] Object Spring options to use when transitioning renderables between scenes
[options.scrollParticle] Object Options for the scroll particle (default: {})
[options.scrollSpring] Object Spring-force options that are applied on the scroll particle when e.g. bounds is reached (default: {dampingRatio: 1.0, period: 350})
[options.scrollDrag] Object Drag-force options to apply on the scroll particle
[options.scrollFriction] Object Friction-force options to apply on the scroll particle
[options.layoutAll] Bool When set to true, always lays out all renderables in the datasource (default: false).
[options.visibleItemThresshold] Number Thresshold (0..1) used for determining whether an item is considered to be the first/last visible item (default: 0.5).
[options.debug] Bool Logs debug output to the console (default: false).

####scrollController.setOptions(options) ⇒ ScrollController Patches the ScrollController instance's options with the passed-in ones.

Param Type Description
options Object Configurable options (see LayoutController for all inherited options).
[options.paginated] Bool Enabled pagination when set to true (default: false).
[options.paginationEnergyThresshold] Number Thresshold after which pagination kicks in (default: 0.01).
[options.paginationMode] PaginationMode Pagination-mode (either page-based or scroll-based) (default: PaginationMode.PAGE).
[options.alignment] Number Alignment of the renderables (0 = top/left, 1 = bottom/right) (default: 0).
[options.mouseMove] Bool Enables scrolling by holding the mouse-button down and moving the mouse (default: false).
[options.enabled] Bool Enables or disabled user input (default: true).
[options.nodeSpring] Object Spring options to use when transitioning renderables between scenes
[options.scrollParticle] Object Options for the scroll particle (default: {})
[options.scrollSpring] Object Spring-force options that are applied on the scroll particle when e.g. bounds is reached (default: {dampingRatio: 1.0, period: 500})
[options.scrollDrag] Object Drag-force options to apply on the scroll particle
[options.scrollFriction] Object Friction-force options to apply on the scroll particle
[options.visibleItemThresshold] Number Thresshold (0..1) used for determining whether an item is considered to be the first/last visible item (default: 0.5).
[options.layoutAll] Bool When set to true, always lays out all renderables in the datasource (default: false).
[options.debug] Bool Logs debug output to the console (default: false).

Returns: ScrollController - this
####scrollController.getVisibleItems() ⇒ Array Get all items that are partly or completely visible.

The returned result is an array of objects containing the following properties. Example:

{
  viewSequence: {ViewSequence},
  index: {Number},
  renderNode: {renderable},
  visiblePerc: {Number} 0..1
}

Returns: Array - array of items
####scrollController.getFirstVisibleItem() ⇒ Object Get the first visible item in the view.

An item is considered to be the first visible item when:

  • First item that is partly visible and the visibility % is higher than options.visibleItemThresshold
  • It is the first item after the top/left bounds

Returns: Object - item or undefined
####scrollController.getLastVisibleItem() ⇒ Object Get the last visible item in the view.

An item is considered to be the last visible item when:

  • Last item that is partly visible and the visibility % is higher than options.visibleItemThresshold
  • It is the last item before the bottom/right bounds

Returns: Object - item or undefined
####scrollController.goToFirstPage() ⇒ ScrollController Scroll to the first page, making it visible.

NOTE: This function does not work on ViewSequences that have the loop property enabled.

Returns: ScrollController - this
####scrollController.goToPreviousPage() ⇒ ScrollController Scroll to the previous page, making it visible.

Returns: ScrollController - this
####scrollController.goToNextPage() ⇒ ScrollController Scroll to the next page, making it visible.

Returns: ScrollController - this
####scrollController.goToLastPage() ⇒ ScrollController Scroll to the last page, making it visible.

NOTE: This function does not work on ViewSequences that have the loop property enabled.

Returns: ScrollController - this
####scrollController.goToRenderNode(node) ⇒ ScrollController Scroll to the given renderable in the datasource.

Param Type Description
node RenderNode renderable to scroll to.

Returns: ScrollController - this
####scrollController.ensureVisible(node) ⇒ ScrollController Ensures that a render-node is entirely visible.

When the node is already visible, nothing happens. If the node is not entirely visible the view is scrolled as much as needed to make it entirely visibl.

Param Type Description
node Number | ViewSequence | Renderable index, renderNode or ViewSequence

Returns: ScrollController - this
####scrollController.scroll(delta) ⇒ ScrollController Scrolls the view by the specified number of pixels.

Param Type Description
delta Number Delta in pixels (< 0 = down/right, > 0 = top/left).

Returns: ScrollController - this
####scrollController.canScroll(delta) ⇒ Number Checks whether the scrollview can scroll the given delta. When the scrollView can scroll the whole delta, then the return value is the same as the delta. If it cannot scroll the entire delta, the return value is the number of pixels that can be scrolled.

Param Type Description
delta Number Delta to test

Returns: Number - Number of pixels the view is allowed to scroll
####scrollController.halt() ⇒ ScrollController Halts all scrolling going on. In essence this function sets the velocity to 0 and cancels any goToXxx operation that was applied.

Returns: ScrollController - this
####scrollController.isScrolling() ⇒ Bool Checks whether scrolling is in progress or not.

Returns: Bool - true when scrolling is active
####scrollController.getBoundsReached() ⇒ ScrollController.Bounds Checks whether any boundaries have been reached.

Returns: ScrollController.Bounds - Either, Bounds.PREV, Bounds.NEXT, Bounds.BOTH or Bounds.NONE
####scrollController.getVelocity() ⇒ Number Get the current scrolling velocity.

Returns: Number - Scroll velocity
####scrollController.setVelocity(velocity) ⇒ ScrollController Set the scrolling velocity.

Param Type Description
velocity Number New scroll velocity

Returns: ScrollController - this
####scrollController.applyScrollForce(delta) ⇒ ScrollController Applies a permanent scroll-force (delta) until it is released. When the cumulative scroll-offset lies outside the allowed bounds a strech effect is used, and the offset beyond the bounds is substracted by halve. This function should always be accompanied by a call to releaseScrollForce.

This method is used for instance when using touch gestures to move the scroll offset and corresponds to the touchstart event.

Param Type Description
delta Number Starting scroll-delta force to apply

Returns: ScrollController - this
####scrollController.updateScrollForce(prevDelta, newDelta) ⇒ ScrollController Updates a existing scroll-force previously applied by calling applyScrollForce.

This method is used for instance when using touch gestures to move the scroll offset and corresponds to the touchmove event.

Param Type Description
prevDelta Number Previous delta
newDelta Number New delta

Returns: ScrollController - this
####scrollController.releaseScrollForce(delta, [velocity]) ⇒ ScrollController Releases a scroll-force and sets the velocity.

This method is used for instance when using touch gestures to move the scroll offset and corresponds to the touchend event.

Param Type Description
delta Number Scroll delta to release
[velocity] Number Velocity to apply after which the view keeps scrolling

Returns: ScrollController - this
####scrollController.getSpec(node, normalize) ⇒ Spec Get the spec (size, transform, etc..) for the given renderable or Id.

Param Type Description
node Renderable | String Renderabe or Id to look for.
normalize Bool When set to true normalizes the origin/align into the transform translation (default: false).

Returns: Spec - spec or undefined