import Layer from 'waves-ui/src/core/layer.js'

public class | source

Layer

Extends:

events~events.EventEmitter → Layer

The layer class is the main visualization class. It is mainly defines by its related LayerTimeContext which determines its position in the overall timeline (through the start, duration, offset and stretchRatio attributes) and by it's registered Shape which defines how to display the data associated to the layer. Each created layer must be inserted into a Track instance in order to be displayed.

Note: in the context of the layer, an item is the SVG element returned by a Shape instance and associated with a particular datum.

Layer DOM structure

<g class="layer" transform="translate(${start}, 0)">
  <svg class="bounding-box" width="${duration}">
    <g class="offset" transform="translate(${offset, 0})">
      <!-- background -->
      <rect class="background"></rect>
      <!-- shapes and common shapes are inserted here -->
    </g>
    <g class="interactions"><!-- for feedback --></g>
  </svg>
</g>

Static Method Summary

Static Public Methods
public static	configureTimeContextBehavior(ctor: Object) Allows to override default the `TimeContextBehavior` used to edit the layer.

Constructor Summary

Public Constructor
public	constructor(dataType: String, data: Array \| Object, options: Object)

Member Summary

Public Members
public	$background: Element
public	$boundingBox: Element
public	$el: Element
public	$interactions: Element
public	$offset: Element
public	contextShape: Segment A Segment instanciated to interact with the Layer itself.
public get	data: Object[] Returns the data associated to the layer.
public set	data: Object \| Object[] Sets the data associated with the layer.
public	dataType: String Defines how the layer should look at the data (`'entity'` or `'collection'`).
public set	duration: Number Sets `LayerTimeContext`'s `duration` time domain value.
public get	duration: Number Returns `LayerTimeContext`'s `duration` time domain value.
public get	items: Array<Element> Returns an array containing all the displayed items.
public set	offset: Number Sets `LayerTimeContext`'s `offset` time domain value.
public get	offset: Number Returns `LayerTimeContext`'s `offset` time domain value.
public get	opacity: Number Returns the opacity of the whole layer.
public set	opacity: Number Sets the opacity of the whole layer.
public	params: Object Parameters of the layers, `defaults` overrided with options.
public get	selectedItems: Array<Element> Returns the items marked as selected.
public set	start: Number Sets `LayerTimeContext`'s `start` time domain value.
public get	start: Number Returns `LayerTimeContext`'s `start` time domain value.
public set	stretchRatio: Number Sets `LayerTimeContext`'s `stretchRatio` time domain value.
public get	stretchRatio: Number Returns `LayerTimeContext`'s `stretchRatio` time domain value.
public	timeContext: LayerTimeContext
public get	timeToPixel: Number Returns the transfert function used to display the data in the x axis.
public get	valueToPixel: Number Returns the transfert function used to display the data in the y axis.
public set	yDomain: Array Set the domain boundaries of the data for the y axis.
public get	yDomain: Array Returns the domain boundaries of the data for the y axis.

Method Summary

Public Methods
public	configureCommonShape(ctor: BaseShape, accessors: Object, options: Object) Optionnaly register a shape to be used accros the entire collection.
public	configureShape(ctor: BaseShape, accessors: Object, options: Object) Register a shape and its configuration to use in order to render the data.
public	destroy() Destroy the layer, clear all references.
public	edit($items: Element \| Element[], dx: Number, dy: Number, $target: Element) Edit item(s) according to the `edit` defined in the registered `Behavior`.
public	editContext(dx: Number, dy: Number, $target: Element) Edit the layer and thus its related `LayerTimeContext` attributes.
public	getDatumFromDOMElement($el: Element): Object \| Array \| null Returns the datum associated to a specific item from any DOM element composing the shape.
public	getDatumFromItem($item: Element): Object \| Array \| null Returns the datum associated to a specific item.
public	getItemFromDOMElement($el: Element): Element \| null Returns an item from a DOM element related to the shape, null otherwise.
public	getItemsInArea(area: Object): Array Retrieve all the items in a given area as defined in the registered `Shape~inArea` method.
public	hasElement($el: Element): bool Defines if a given element belongs to the layer.
public	hasItem($item: Element): Boolean Tests if the given DOM element is an item of the layer.
public	render() Create the DOM structure of the shapes according to the given data.
public	select($items: Element \| Element[]) Mark item(s) as selected.
public	setBehavior(behavior: BaseBehavior) Register the behavior to use when interacting with a shape.
public	setContextEditable(bool: boolean) Defines if the `Layer`, and thus the `LayerTimeContext` is editable or not.
public	setTimeContext(timeContext: TimeContext) Sets the context of the layer, thus defining its `start`, `duration`, `offset` and `stretchRatio`.
public	stretchContext(dx: Number, dy: Number, $target: Element) Stretch the layer and thus its related `LayerTimeContext` attributes.
public	toggleSelection($items: Element \| Element[]) Toggle item(s) selection state according to their current state.
public	unselect($items: Element \| Element[]) Removes item(s) from selected items.
public	update() Updates the container of the layer and the attributes of the existing shapes.
public	updateContainer() Updates the container of the layer.
public	updateShapes() Updates the attributes of all the `Shape` instances rendered into the layer.

Static Public Methods

public static configureTimeContextBehavior(ctor: Object) source

Allows to override default the TimeContextBehavior used to edit the layer.

Params:

Name	Type	Attribute	Description
ctor	Object

Public Constructors

public constructor(dataType: String, data: Array | Object, options: Object) source

Params:

Name	Type	Attribute	Description
dataType	String		Defines how the layer should look at the data. Can be 'entity' or 'collection'.
data	Array \| Object		The data associated to the layer.
options	Object		Configures the layer.
options.height	Number	optional default: 100	Defines the height of the layer.
options.top	Number	optional default: 0	Defines the top position of the layer.
options.opacity	Number	optional default: 1	Defines the opacity of the layer.
options.yDomain	Number	optional default: [0,1]	Defines boundaries of the data values in y axis (for exemple to display an audio buffer, this attribute should be set to [-1, 1].
options.className	String	optional default: null	An optionnal class to add to each created shape.
options.className	String	optional default: 'selected'	The class to add to a shape when selected.
options.contextHandlerWidth	Number	optional default: 2	The width of the handlers displayed to edit the layer.
options.hittable	Number	optional default: false	Defines if the layer can be interacted with. Basically, the layer is not returned by `BaseState.getHitLayers` when set to false (a common use case is a layer that contains a cursor)

Public Members

public $background: Element source

public $boundingBox: Element source

public $el: Element source

public $interactions: Element source

public $offset: Element source

public contextShape: Segment source

A Segment instanciated to interact with the Layer itself.

public get data: Object[] source

Returns the data associated to the layer.

public set data: Object | Object[] source

Sets the data associated with the layer.

public dataType: String source

Defines how the layer should look at the data ('entity' or 'collection').

public set duration: Number source

Sets LayerTimeContext's duration time domain value.

public get duration: Number source

Returns LayerTimeContext's duration time domain value.

public get items: Array<Element> source

Returns an array containing all the displayed items.

public set offset: Number source

Sets LayerTimeContext's offset time domain value.

public get offset: Number source

Returns LayerTimeContext's offset time domain value.

public get opacity: Number source

Returns the opacity of the whole layer.

public set opacity: Number source

Sets the opacity of the whole layer.

public params: Object source

Parameters of the layers, defaults overrided with options.

public get selectedItems: Array<Element> source

Returns the items marked as selected.

public set start: Number source

Sets LayerTimeContext's start time domain value.

public get start: Number source

Returns LayerTimeContext's start time domain value.

public set stretchRatio: Number source

Sets LayerTimeContext's stretchRatio time domain value.

public get stretchRatio: Number source

Returns LayerTimeContext's stretchRatio time domain value.

public timeContext: LayerTimeContext source

public get timeToPixel: Number source

Returns the transfert function used to display the data in the x axis.

public get valueToPixel: Number source

Returns the transfert function used to display the data in the y axis.

public set yDomain: Array source

Set the domain boundaries of the data for the y axis.

public get yDomain: Array source

Returns the domain boundaries of the data for the y axis.

Public Methods

public configureCommonShape(ctor: BaseShape, accessors: Object, options: Object) source

Optionnaly register a shape to be used accros the entire collection.

Params:

Name	Type	Attribute	Description
ctor	BaseShape		The constructor of the shape to be used.
accessors	Object	optional default: {}	Defines how the shape should adapt to a particular data struture.
options	Object	optional default: {}	Global configuration for the shapes, is specific to each `Shape`.

public configureShape(ctor: BaseShape, accessors: Object, options: Object) source

Params:

Name	Type	Attribute	Description
ctor	BaseShape		The constructor of the shape to be used.
accessors	Object	optional default: {}	Defines how the shape should adapt to a particular data struture.
options	Object	optional default: {}	Global configuration for the shapes, is specific to each `Shape`.

public destroy() source

Destroy the layer, clear all references.

public edit($items: Element | Element[], dx: Number, dy: Number, $target: Element) source

Edit item(s) according to the edit defined in the registered Behavior.

Params:

Name	Type	Attribute	Description
$items	Element \| Element[]		The item(s) to edit.
dx	Number		The modification to apply in the x axis (in pixels).
dy	Number		The modification to apply in the y axis (in pixels).
$target	Element		The target of the interaction (for example, left handler DOM element in a segment).

public editContext(dx: Number, dy: Number, $target: Element) source

Edit the layer and thus its related LayerTimeContext attributes.

Params:

Name	Type	Attribute	Description
dx	Number		The modification to apply in the x axis (in pixels).
dy	Number		The modification to apply in the y axis (in pixels).
$target	Element		The target of the event of the interaction.

public getDatumFromDOMElement($el: Element): Object | Array | null source

Returns the datum associated to a specific item from any DOM element composing the shape. Basically a shortcut for getItemFromDOMElement and getDatumFromItem methods.

Params:

Name	Type	Attribute	Description
$el	Element

Return:

Object | Array | null

public getDatumFromItem($item: Element): Object | Array | null source

Returns the datum associated to a specific item.

Params:

Name	Type	Attribute	Description
$item	Element

Return:

Object | Array | null

public getItemFromDOMElement($el: Element): Element | null source

Returns an item from a DOM element related to the shape, null otherwise.

Params:

Name	Type	Attribute	Description
$el	Element		the element to be tested

Return:

Element | null

public getItemsInArea(area: Object): Array source

Retrieve all the items in a given area as defined in the registered Shape~inArea method.

Params:

Name	Type	Attribute	Description
area	Object		The area in which to find the elements
area.top	Number
area.left	Number
area.width	Number
area.height	Number

Return:

Array

list of the items presents in the area

public hasElement($el: Element): bool source

Defines if a given element belongs to the layer. Is more general than hasItem, can mostly used to check interactions elements.

Params:

Name	Type	Attribute	Description
$el	Element		The DOM element to be tested.

Return:

bool

public hasItem($item: Element): Boolean source

Tests if the given DOM element is an item of the layer.

Params:

Name	Type	Attribute	Description
$item	Element		The item to be tested.

Return:

Boolean

public render() source

Create the DOM structure of the shapes according to the given data. Inspired from the enter and exit d3.js paradigm, this method should be called each time a datum is added or removed from the data. While the DOM is created the update method must be called in order to update the shapes attributes and thus place them where they should.

public select($items: Element | Element[]) source

Mark item(s) as selected.

Params:

Name	Type	Attribute	Description
$items	Element \| Element[]

public setBehavior(behavior: BaseBehavior) source

Params:

Name	Type	Attribute	Description
behavior	BaseBehavior

public setContextEditable(bool: boolean) source

Defines if the Layer, and thus the LayerTimeContext is editable or not.

Params:

Name	Type	Attribute	Description
bool	boolean	optional default: true

public setTimeContext(timeContext: TimeContext) source

Sets the context of the layer, thus defining its start, duration, offset and stretchRatio.

Params:

Name	Type	Attribute	Description
timeContext	TimeContext		The timeContext in which the layer is displayed.

public stretchContext(dx: Number, dy: Number, $target: Element) source

Stretch the layer and thus its related LayerTimeContext attributes.

Params:

Name	Type	Attribute	Description
dx	Number		The modification to apply in the x axis (in pixels).
dy	Number		The modification to apply in the y axis (in pixels).
$target	Element		The target of the event of the interaction.

public toggleSelection($items: Element | Element[]) source

Toggle item(s) selection state according to their current state.

Params:

Name	Type	Attribute	Description
$items	Element \| Element[]

public unselect($items: Element | Element[]) source

Removes item(s) from selected items.

Params:

Name	Type	Attribute	Description
$items	Element \| Element[]

public update() source

Updates the container of the layer and the attributes of the existing shapes.

public updateContainer() source

Updates the container of the layer.

public updateShapes() source

Updates the attributes of all the Shape instances rendered into the layer.

TODO:

- allow to filter which shape(s) should be updated.