LayoutController.md

LayoutController

LayoutController lays out renderables according to a layout- function and a data-source.

Events:

event	description
layoutstart	Emitted before the layout function is executed.
layoutend	Emitted after the layout function has been executed.
reflow	Emitted after one or more renderables have been changed.

• LayoutController
  • LayoutController ⏏
    • new LayoutController(options)
    • .setOptions(options) ⇒ LayoutController
    • .setDataSource(dataSource) ⇒ LayoutController
    • .getDataSource() ⇒ Array | LinkedListViewSequence | Object
    • .setLayout(layout, [options]) ⇒ LayoutController
    • .getLayout() ⇒ function | Object
    • .setLayoutOptions([options]) ⇒ LayoutController
    • .getLayoutOptions() ⇒ Object
    • .setDirection(direction) ⇒ LayoutController
    • .getDirection([actual]) ⇒ Utility.Direction
    • .getSpec(node, [normalize], [endState]) ⇒ Spec
    • .reflowLayout() ⇒ LayoutController
    • .resetFlowState() ⇒ LayoutController
    • .insert(indexOrId, renderable, [insertSpec]) ⇒ LayoutController
    • .push(renderable, [insertSpec]) ⇒ LayoutController
    • .get(indexOrId) ⇒ Renderable
    • .swap(index, index2) ⇒ LayoutController
    • .replace(indexOrId, renderable, [noAnimation]) ⇒ Renderable
    • .move(index, newIndex) ⇒ LayoutController
    • .remove(indexOrId, [removeSpec]) ⇒ Renderable
    • .removeAll([removeSpec]) ⇒ LayoutController
    • .getSize() ⇒ Array.Number

LayoutController ⏏

Kind: Exported class

new LayoutController(options)

Param	Type	Description
options	Object	Options.
[options.layout]	function | Object	Layout function or layout-literal.
[options.layoutOptions]	Object	Options to pass in to the layout-function.
[options.dataSource]	Array | LinkedListViewSequence | Object	Array, LinkedListViewSequence or Object with key/value pairs.
[options.direction]	Utility.Direction	Direction to layout into (e.g. Utility.Direction.Y) (when omitted the default direction of the layout is used)
[options.flow]	Bool	Enables flow animations when the layout changes (default: false).
[options.flowOptions]	Object	Options used by nodes when reflowing.
[options.flowOptions.reflowOnResize]	Bool	Smoothly reflows renderables on resize (only used when flow = true) (default: true).
[options.flowOptions.spring]	Object	Spring options used by nodes when reflowing (default: {dampingRatio: 0.8, period: 300}).
[options.flowOptions.properties]	Object	Properties which should be enabled or disabled for flowing.
[options.flowOptions.insertSpec]	Spec	Size, transform, opacity... to use when inserting new renderables into the scene (default: {}).
[options.flowOptions.removeSpec]	Spec	Size, transform, opacity... to use when removing renderables from the scene (default: {}).
[options.alwaysLayout]	Bool	When set to true, always calls the layout function on every render-cycle (default: false).
[options.autoPipeEvents]	Bool	When set to true, automatically calls .pipe on all renderables when inserted (default: false).
[options.preallocateNodes]	Object	Optimisation option to improve initial scrolling/animation performance by pre-allocating nodes, e.g.: {count: 50, spec: {size:[0, 0], transform: Transform.identity}}.

layoutController.setOptions(options) ⇒ LayoutController

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

Kind: instance method of LayoutController
Returns: LayoutController - this

Param	Type	Description
options	Options	An object of configurable options for the LayoutController instance.
[options.layout]	function | Object	Layout function or layout-literal.
[options.layoutOptions]	Object	Options to pass in to the layout-function.
[options.dataSource]	Array | LinkedListViewSequence | Object	Array, LinkedListViewSequence or Object with key/value pairs.
[options.direction]	Utility.Direction	Direction to layout into (e.g. Utility.Direction.Y) (when omitted the default direction of the layout is used)
[options.flowOptions]	Object	Options used by nodes when reflowing.
[options.flowOptions.reflowOnResize]	Bool	Smoothly reflows renderables on resize (only used when flow = true) (default: true).
[options.flowOptions.spring]	Object	Spring options used by nodes when reflowing (default: {dampingRatio: 0.8, period: 300}).
[options.flowOptions.properties]	Object	Properties which should be enabled or disabled for flowing.
[options.flowOptions.insertSpec]	Spec	Size, transform, opacity... to use when inserting new renderables into the scene (default: {}).
[options.flowOptions.removeSpec]	Spec	Size, transform, opacity... to use when removing renderables from the scene (default: {}).
[options.alwaysLayout]	Bool	When set to true, always calls the layout function on every render-cycle (default: false).

layoutController.setDataSource(dataSource) ⇒ LayoutController

Sets the collection of renderables which are layed out according to the layout-function.

The data-source can be either an Array, LinkedListViewSequence or Object with key/value pairs.

Kind: instance method of LayoutController
Returns: LayoutController - this

Param	Type	Description
dataSource	Array | Object | LinkedListViewSequence	Array, LinkedListViewSequence or Object.

layoutController.getDataSource() ⇒ Array | LinkedListViewSequence | Object

Get the data-source.

Kind: instance method of LayoutController
Returns: Array | LinkedListViewSequence | Object - data-source

layoutController.setLayout(layout, [options]) ⇒ LayoutController

Set the new layout.

Kind: instance method of LayoutController
Returns: LayoutController - this

Param	Type	Description
layout	function | Object	Layout function or layout-literal
[options]	Object	Options to pass in to the layout-function

layoutController.getLayout() ⇒ function | Object

Get the current layout.

Kind: instance method of LayoutController
Returns: function | Object - Layout function or layout literal

layoutController.setLayoutOptions([options]) ⇒ LayoutController

Set the options for the current layout. Use this function after setLayout to update one or more options for the layout-function.

Kind: instance method of LayoutController
Returns: LayoutController - this

Param	Type	Description
[options]	Object	Options to pass in to the layout-function

layoutController.getLayoutOptions() ⇒ Object

Get the current layout options.

Kind: instance method of LayoutController
Returns: Object - Layout options

layoutController.setDirection(direction) ⇒ LayoutController

Set the direction of the layout. When no direction is set, the default direction of the layout function is used.

Kind: instance method of LayoutController
Returns: LayoutController - this

Param	Type	Description
direction	Utility.Direction	Direction (e.g. Utility.Direction.X)

layoutController.getDirection([actual]) ⇒ Utility.Direction

Get the direction (e.g. Utility.Direction.Y). By default, this function returns the direction that was configured by setting setDirection. When the direction has not been set, undefined is returned.

When no direction has been set, the first direction is used that is specified in the capabilities of the layout-function. To obtain the actual in-use direction, use getDirection(true). This method returns the actual in-use direction and never returns undefined.

Kind: instance method of LayoutController
Returns: Utility.Direction - Direction or undefined

Param	Type	Description
[actual]	Boolean	Set to true to obtain the actual in-use direction

layoutController.getSpec(node, [normalize], [endState]) ⇒ Spec

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

Kind: instance method of LayoutController
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).
[endState]	Bool	When set to true returns the flowing end-state spec rather than the current spec.

layoutController.reflowLayout() ⇒ LayoutController

Forces a reflow of the layout the next render cycle.

Kind: instance method of LayoutController
Returns: LayoutController - this

layoutController.resetFlowState() ⇒ LayoutController

Resets the current flow state, so that all renderables are immediately displayed in their end-state.

Kind: instance method of LayoutController
Returns: LayoutController - this

layoutController.insert(indexOrId, renderable, [insertSpec]) ⇒ LayoutController

Inserts a renderable into the data-source.

The optional argument insertSpec is only used flow mode is enabled. When specified, the renderable is inserted using an animation starting with size, origin, opacity, transform, etc... as specified in `insertSpec'.

Kind: instance method of LayoutController
Returns: LayoutController - this

Param	Type	Description
indexOrId	Number | String	Index (0 = before first, -1 at end), within dataSource array or id (String)
renderable	Object	Renderable to add to the data-source
[insertSpec]	Spec	Size, transform, etc.. to start with when inserting

layoutController.push(renderable, [insertSpec]) ⇒ LayoutController

Adds a renderable to the end of a sequential data-source.

The optional argument insertSpec is only used flow mode is enabled. When specified, the renderable is inserted using an animation starting with size, origin, opacity, transform, etc... as specified in `insertSpec'.

Kind: instance method of LayoutController
Returns: LayoutController - this

Param	Type	Description
renderable	Object	Renderable to add to the data-source
[insertSpec]	Spec	Size, transform, etc.. to start with when inserting

layoutController.get(indexOrId) ⇒ Renderable

Get the renderable at the given index or Id.

Kind: instance method of LayoutController
Returns: Renderable - renderable or undefined

Param	Type	Description
indexOrId	Number | String	Index within dataSource array or id (String)

layoutController.swap(index, index2) ⇒ LayoutController

Swaps two renderables at the given positions.

This method is only supported for dataSources of type Array or LinkedListViewSequence.

Kind: instance method of LayoutController
Returns: LayoutController - this

Param	Type	Description
index	Number	Index of the renderable to swap
index2	Number	Index of the renderable to swap with

layoutController.replace(indexOrId, renderable, [noAnimation]) ⇒ Renderable

Replaces a renderable at the given index or id.

Kind: instance method of LayoutController
Returns: Renderable - old renderable that has been replaced

Param	Type	Description
indexOrId	Number | String	Index within dataSource array or id (String)
renderable	Renderable	renderable to replace with
[noAnimation]	Bool	When set to true, replaces the renderable without any flowing animation.

layoutController.move(index, newIndex) ⇒ LayoutController

Moves a renderable to a new index.

This method is only supported for dataSources of type Array or LinkedListViewSequence.

Kind: instance method of LayoutController
Returns: LayoutController - this

Param	Type	Description
index	Number	Index of the renderable to move.
newIndex	Number	New index of the renderable.

layoutController.remove(indexOrId, [removeSpec]) ⇒ Renderable

Removes a renderable from the data-source.

The optional argument removeSpec is only used flow mode is enabled. When specified, the renderable is removed using an animation ending at the size, origin, opacity, transform, etc... as specified in `removeSpec'.

Kind: instance method of LayoutController
Returns: Renderable - renderable that has been removed

Param	Type	Description
indexOrId	Number | String | Renderable	Index, id (String) or renderable to remove.
[removeSpec]	Spec	Size, transform, etc.. to end with when removing

layoutController.removeAll([removeSpec]) ⇒ LayoutController

Removes all renderables from the data-source.

The optional argument removeSpec is only used when flow mode is enabled. When specified, the renderables are removed using an animation ending at the size, origin, opacity, transform, etc... as specified in `removeSpec'.

Kind: instance method of LayoutController
Returns: LayoutController - this

Param	Type	Description
[removeSpec]	Spec	Size, transform, etc.. to end with when removing

layoutController.getSize() ⇒ Array.Number

Return size of contained element or undefined when size is not defined.

Kind: instance method of LayoutController
Returns: Array.Number - [width, height]