# Class: c3.Selection

Defined in: | js/c3.coffee

## Overview

The c3 selection object is used internally as an abstraction around D3 selections to provide common functionality and patterns. It is not meant to provide a general solution or replace D3. The motivation behind it is to normalize design patterns and performance optimizations useful for c3 visualizations on top of what D3 offers. In particular, it is useful to allow c3 users to define options which c3 visualizations can then use to do the actual DOM updates.

Please refer to c3.Selection.Options for user-configurable options.

c3 visualizations create c3.Selection objects to in turn create and represent various DOM nodes. c3.Selection.Options objects are used to persist user options that are used in subsequent updates or styling of nodes. For example, there is a `circle_options` {c3.Selection.options} used to describe how to setup and style circles in a scatter plot. You can still modify the different selection option properties, which will then be used as appropriate when redraw() or restyle() is called.

## Variables

- `all` - [d3.selection] D3 selection of all nodes
- `new` - [d3.selection] D3 selection of newly created nodes
- `old` - [d3.selection] D3 selection of nodes removed due to data binding

### Author:

- Douglas Armstrong

### See also:

- c3.Selection.Options
- ~c3.select
- https://github.com/mbostock/d3/wiki/Selections

## Variables Summary

opt =

      {}

  [c3.Selection.Options] User configurable options for ongoing `update()` and `style()` manipulation of nodes.

opt_array =

      undefined

  [Array<c3.Selection.Options>] Array of user options for each node in the selection based on the index.

## Instance Method Summary

- # (void) select(query, before, children_only) Create a new c3 selection based on the current selection
- # (void) inherit(query, create = true, prepend = false) Bound Create a child node for each node in the parent's selection with a 1:1 mapping to the same data.
- # (void) singleton(datum) Bound Create a single DOM node based on the passed in data.
- # (void) bind(data, key) Bound Update the DOM nodes based on the provided data using D3.
- # (void) remove() Bound Remove this selection
- # (void) options(opt = {}, opt_accessor) Set persistent user-configurable options.
- # (void) animate(animate = true) Allow animations for this selection during binding or positioning if the user requested them with `animate` in the c3.Selection.Options.
- # (void) update() Bound This will setup event handlers for new nodes and update classes, tooltips, text, and html for all nodes based on the current data and options.
- # (void) position(attrs) Bound Update the attribute values for the dom nodes of this selection based on the values and callbacks set in attrs.
- # (void) position_tweens(attrs) Bound Update the attribute values for the dom nodes of this selection based on tween functions in `attrs`
- # (void) style(style_new) Bound A method to style and setup CSS classes for the nodes in the selection based on the current {c3.Selection.options options}.
- # (HTMLElement) node() Bound Return a single HTML Element for this selection.

## Constructor Details

# (void) constructor(d3_selection = d3.select(), query, before, children_only)

TODO: Support all possible selectors.

Create a new selection

### Parameters:

- d3_selection ( `{https://github.com/mbostock/d3/wiki/Selections d3.selection` )
- query ( `String` ) — Search string to query in the parent selection to make this new selection. If a class is specified, such as "tag.class", then the class will automatically be added to newly created nodes.
- before ( `String` ) — An optional selector to insert nodes before. `:first-child` will insert nodes at the beginning.
- children_only ( `boolean` ) — Only select direct children, not all descendents

## Instance Method Details

# (void) select(query, before, children_only)

Create a new c3 selection based on the current selection

### Parameters:

- query ( `String` ) — Search string to query in the parent selection to make this new selection. If a class is specified, such as "tag.class", then the class will automatically be added to newly created nodes.
- before ( `String` ) — An optional selector to insert nodes before. `:first-child` will insert nodes at the beginning.
- children_only ( `boolean` ) — Only select direct children, not all descendents

# (void) inherit(query, create = true, prepend = false) Bound

Create a child node for each node in the parent's selection with a 1:1 mapping to the same data. For example, if the parent selection had a set of svg:g nodes, then inheriting from that with a `circle` query would create an svg:circle node nested in each svg:g node.

### Parameters:

- query ( `String` ) — Node type to create as nested nodes in the current selection
- create ( `Boolean, String` ) — Create missing child nodes for new nodes or set to `restore` to ensure that child nodes are created for existing parent nodes that don't already have them.
- prepend ( `Boolean` ) — If true, then prepend child nodes instead of appending them. Note that this will not prepend in front of any text content, only child nodes.

# (void) singleton(datum) Bound

Create a single DOM node based on the passed in data. Ensure that only one node will be created and will remove extra nodes that match the query if they previously existed.

### Parameters:

- datum ( `*` ) — The datum to bind to the DOM node. This may be left undefined.

# (void) bind(data, key) Bound

Update the DOM nodes based on the provided data using D3. Create new nodes and remove them as necessary so there is a node for each element in the data array and they are bound together. The `key` function is optional and is used to uniquely identify data elements. So, even if the data is reordered in subsequent calls to update, they will still be bound to the same DOM nodes. Animate opacity for entering or exiting nodes if `animate` is set in the options unless the opacity style is defined.

### Parameters:

- data ( `Array` ) — Array of data to bind to the DOM
- key ( `Function` ) — Accessor to uniquely identify data elements

# (void) remove() Bound

Remove this selection

# (void) options(opt = {}, opt_accessor)

Set persistent user-configurable options. A reference to these options are stored in the selection and are used for future manipulation in `update()` and `style()`. options for a specific data element.

### Parameters:

- opt ( `c3.Selection.Options` ) — User-configurable options to define how to setup and style the selection's nodes.
- opt_accessor ( `Function` ) — An optional accessor to return

# (void) animate(animate = true)

Allow animations for this selection during binding or positioning if the user requested them with `animate` in the c3.Selection.Options.

### Parameters:

- animate ( `Boolean` ) — Allow animations

# (void) update() Bound

This will setup event handlers for new nodes and update classes, tooltips, text, and html for all nodes based on the current data and options.

# (void) position(attrs) Bound

Update the attribute values for the dom nodes of this selection based on the values and callbacks set in attrs.

### Parameters:

- attrs ( `Object` ) — A map where the keys represent DOM attribute names and the values are the corresponding values or functions to set them. The functions are called via D3. They are passed the bound datum and index to the data as arguments and the `this` context is set to refer to the HTML element.

# (void) position_tweens(attrs) Bound

Update the attribute values for the dom nodes of this selection based on tween functions in `attrs`

### Parameters:

- tweens ( `Object` ) — A map where the keys represent DOM attribute names and the values are corresponding tween functions for animating them. The functions are called via D3. They are passed the bound datum and index to the data as arguments and the `this` context refers to the HTML element. They should return a "tween" function thich takes a time parameter from 0-1 as the transition animation progresses based on the easing function. It is the tween function that should finally return the value of the attribute for that point in the transition.

# (void) style(style_new) Bound

A method to style and setup CSS classes for the nodes in the selection based on the current {c3.Selection.options options}.

### Parameters:

- style_new ( `Boolean` ) — By default all nodes will be updated. If this is set, then only new nodes will be updated. This only works if the data was bound with a key function to avoid nodes having incorrect styles when the bound data is dynamically rearranged.

# (HTMLElement) node() Bound

Return a single HTML Element for this selection. Mostly useful if you know the selection only represents a single node.

### Returns:

- ( `HTMLElement` ) — node

Quickly fuzzy find classes, mixins, methods, file:

- T Open fuzzy finder dialog

Control the navigation frame:

- L Toggle list view
- C Show class list
- I Show mixin list
- F Show file list
- M Show method list
- E Show extras list

You can focus and blur the search input:

- S Focus search input
- Esc Blur search input