SelectionHandle

Use this class to read and write (and listen for changes to) the selection for a Crosstalk group. This is intended to be used for linked brushing.

If two (or more) SelectionHandle instances in the same webpage share the same group name, they will share the same state. Setting the selection using one SelectionHandle instance will result in the value property instantly changing across the others, and "change" event listeners on all instances (including the one that initiated the sending) will fire.

Kind: global class

new SelectionHandle([group], [extraInfo])

Param Type Default Description
[group] string null The name of the Crosstalk group, or if none, null or undefined (or any other falsy value). This can be changed later via the SelectionHandle#setGroup method.
[extraInfo] Object An object whose properties will be copied to the event object whenever an event is emitted.

selectionHandle.value

Retrieves the current selection for the group represented by this SelectionHandle.

  • If no selection is active, then this value will be falsy.
  • If a selection is active, but no data points are selected, then this value will be an empty array.
  • If a selection is active, and data points are selected, then the keys of the selected data points will be present in the array.

Kind: instance property of SelectionHandle

selectionHandle.setGroup(group)

Changes the Crosstalk group membership of this SelectionHandle. The group being switched away from (if any) will not have its selection value modified as a result of calling setGroup, even if this handle was the most recent handle to set the selection of the group.

The group being switched to (if any) will also not have its selection value modified as a result of calling setGroup. If you want to set the selection value of the new group, call set explicitly.

Kind: instance method of SelectionHandle

Param Type Description
group string The name of the Crosstalk group, or null (or undefined) to clear the group.

selectionHandle.set(selectedKeys, [extraInfo])

Overwrites the current selection for the group, and raises the "change" event among all of the group’s ’SelectionHandle instances (including this one).

Kind: instance method of SelectionHandle
Emits: change

Param Type Description
selectedKeys Array.<string> Falsy, empty array, or array of keys (see value).
[extraInfo] Object Extra properties to be included on the event object that’s passed to listeners (in addition to any options that were passed into the SelectionHandle constructor).

selectionHandle.clear([extraInfo])

Overwrites the current selection for the group, and raises the "change" event among all of the group’s ’SelectionHandle instances (including this one).

Kind: instance method of SelectionHandle
Emits: change

Param Type Description
[extraInfo] Object Extra properties to be included on the event object that’s passed to listeners (in addition to any that were passed into the SelectionHandle constructor).

selectionHandle.on(eventType, listener) ⇒ string

Subscribes to events on this SelectionHandle.

Kind: instance method of SelectionHandle
Returns: string - - A token to pass to off to cancel this subscription.

Param Type Description
eventType string Indicates the type of events to listen to. Currently, only "change" is supported.
listener listener The callback function that will be invoked when the event occurs.

selectionHandle.off(eventType, listener)

Cancels event subscriptions created by on.

Kind: instance method of SelectionHandle

Param Type Description
eventType string The type of event to unsubscribe.
listener string | listener Either the callback function previously passed into on, or the string that was returned from on.

selectionHandle.close()

Shuts down the SelectionHandle object.

Removes all event listeners that were added through this handle.

Kind: instance method of SelectionHandle

“change”

Kind: event emitted by SelectionHandle
Properties

Name Type Description
value object The new value of the selection, or undefined if no selection is active.
oldValue object The previous value of the selection.
sender SelectionHandle The SelectionHandle instance that changed the value.

SelectionHandle~listener : function

Kind: inner typedef of SelectionHandle

Param Type Description
event Object An object containing details of the event. For "change" events, this includes the properties value (the new value of the selection, or undefined if no selection is active), oldValue (the previous value of the selection), and sender (the SelectionHandle instance that made the change).