ScrollController.md

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

• ScrollController
  • ScrollController ⇐ LayoutController ⏏
    • new ScrollController(options)
    • .setOptions(options) ⇒ ScrollController
    • .getVisibleItems() ⇒ Array
    • .getFirstVisibleItem() ⇒ Object
    • .getLastVisibleItem() ⇒ Object
    • .goToFirstPage([noAnimation]) ⇒ ScrollController
    • .goToPreviousPage([noAnimation]) ⇒ ScrollController
    • .goToNextPage([noAnimation]) ⇒ ScrollController
    • .goToLastPage([noAnimation]) ⇒ ScrollController
    • .goToRenderNode(node, [noAnimation]) ⇒ ScrollController
    • .ensureVisible(node) ⇒ ScrollController
    • .scroll(delta) ⇒ ScrollController
    • .canScroll(delta) ⇒ Number
    • .halt() ⇒ ScrollController
    • .isScrolling() ⇒ Bool
    • .getBoundsReached() ⇒ ScrollController.Bounds
    • .getVelocity() ⇒ Number
    • .getEnergy() ⇒ Number
    • .setVelocity(velocity) ⇒ ScrollController
    • .applyScrollForce(delta) ⇒ ScrollController
    • .updateScrollForce(prevDelta, newDelta) ⇒ ScrollController
    • .releaseScrollForce(delta, [velocity]) ⇒ ScrollController
    • .getSpec(node, normalize) ⇒ Spec

ScrollController ⇐ LayoutController ⏏

Kind: Exported class
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.paginationEnergyThreshold]	Number	Threshold 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.overscroll]	Bool	Enables or disables overscroll (default: true).
[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).

scrollController.setOptions(options) ⇒ ScrollController

Patches the ScrollController instance's options with the passed-in ones.

Kind: instance method of ScrollController
Returns: ScrollController - this

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.paginationEnergyThreshold]	Number	Threshold 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 disables user input (default: true).
[options.overscroll]	Bool	Enables or disables overscroll (default: true).
[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.layoutAll]	Bool	When set to true, always lays out all renderables in the datasource (default: false).

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: {LinkedListViewSequence},
  index: {Number},
  renderNode: {renderable},
  visiblePerc: {Number} 0..1
}

Kind: instance method of ScrollController
Returns: Array - array of items

scrollController.getFirstVisibleItem() ⇒ Object

Get the first visible item in the view.

Kind: instance method of ScrollController
Returns: Object - item or undefined

scrollController.getLastVisibleItem() ⇒ Object

Get the last visible item in the view.

Kind: instance method of ScrollController
Returns: Object - item or undefined

scrollController.goToFirstPage([noAnimation]) ⇒ ScrollController

Goes to the first page, making it visible.

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

Kind: instance method of ScrollController
Returns: ScrollController - this

Param	Type	Description
[noAnimation]	Bool	When set to true, immediately shows the node without any scrolling animation.

scrollController.goToPreviousPage([noAnimation]) ⇒ ScrollController

Goes to the previous page, making it visible.

Kind: instance method of ScrollController
Returns: ScrollController - this

Param	Type	Description
[noAnimation]	Bool	When set to true, immediately shows the node without any scrolling animation.

scrollController.goToNextPage([noAnimation]) ⇒ ScrollController

Goes to the next page, making it visible.

Kind: instance method of ScrollController
Returns: ScrollController - this

Param	Type	Description
[noAnimation]	Bool	When set to true, immediately shows the node without any scrolling animation.

scrollController.goToLastPage([noAnimation]) ⇒ ScrollController

Goes to the last page, making it visible.

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

Kind: instance method of ScrollController
Returns: ScrollController - this

Param	Type	Description
[noAnimation]	Bool	When set to true, immediately shows the node without any scrolling animation.

scrollController.goToRenderNode(node, [noAnimation]) ⇒ ScrollController

Goes to the given renderable in the datasource.

Kind: instance method of ScrollController
Returns: ScrollController - this

Param	Type	Description
node	RenderNode	renderable to scroll to.
[noAnimation]	Bool	When set to true, immediately shows the node without scrolling animation.

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.

Kind: instance method of ScrollController
Returns: ScrollController - this

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

scrollController.scroll(delta) ⇒ ScrollController

Scrolls the view by the specified number of pixels.

Kind: instance method of ScrollController
Returns: ScrollController - this

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

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.

Kind: instance method of ScrollController
Returns: Number - Number of pixels the view is allowed to scroll

Param	Type	Description
delta	Number	Delta to test

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.

Kind: instance method of ScrollController
Returns: ScrollController - this

scrollController.isScrolling() ⇒ Bool

Checks whether scrolling is in progress or not.

Kind: instance method of ScrollController
Returns: Bool - true when scrolling is active

scrollController.getBoundsReached() ⇒ ScrollController.Bounds

Checks whether any boundaries have been reached.

Kind: instance method of ScrollController
Returns: ScrollController.Bounds - Either, Bounds.PREV, Bounds.NEXT, Bounds.BOTH or Bounds.NONE

scrollController.getVelocity() ⇒ Number

Get the current scrolling velocity.

Kind: instance method of ScrollController
Returns: Number - Scroll velocity

scrollController.getEnergy() ⇒ Number

Get the current energy of the scrolling particle.

Kind: instance method of ScrollController
Returns: Number - Energy

scrollController.setVelocity(velocity) ⇒ ScrollController

Set the scrolling velocity.

Kind: instance method of ScrollController
Returns: ScrollController - this

Param	Type	Description
velocity	Number	New scroll velocity

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.

Kind: instance method of ScrollController
Returns: ScrollController - this

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

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.

Kind: instance method of ScrollController
Returns: ScrollController - this

Param	Type	Description
prevDelta	Number	Previous delta
newDelta	Number	New delta

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.

Kind: instance method of ScrollController
Returns: ScrollController - this

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

scrollController.getSpec(node, normalize) ⇒ Spec

Get the spec (size, transform, etc..) for the given renderable or Id.

Kind: instance method of ScrollController
Returns: Spec - spec or undefined

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