com.github.gwtd3.api.core

Class EnteringSelection

java.lang.Object

com.google.gwt.core.client.JavaScriptObject

com.github.gwtd3.api.core.EnteringSelection

Direct Known Subclasses:

Selection

public class EnteringSelection
extends com.google.gwt.core.client.JavaScriptObject

A selection returned by a call to UpdateSelection.enter().

The entering selection only contains placeholder nodes for each data element for which no corresponding existing DOM element was found in the current selection.

In addition, the entering selection only defines append, insert and select operators; you must use these operators to instantiate the entering nodes before modifying any content.

Note that the enter operator merely returns a reference to the entering selection, and it is up to you to add the new nodes.

The enter selection merges into the update selection when you append or insert. This approach reduces code duplication between enter and update. Rather than applying operators to both the enter and update selection separately, you can now apply them to the update selection after entering the nodes. In the rare case that you want to run operators only on the updating nodes, you can run them on the update selection before entering new nodes.

Author:

Anthony Schiochet

See Also:

Official API

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	EnteringSelection()

Method Summary

Methods

Modifier and Type	Method and Description
Selection	append(String name) Appends a new element with the specified name as the last child of each element in the current selection.
Array<Array<com.google.gwt.dom.client.Element>>	asElementArray() Return the internal structure of the selection.
Selection	call(IsFunction jsFunction) Invokes the specified function once, passing in the current selection as a single parameter.
boolean	empty() Returns true if the current selection is empty; a selection is empty if it contains no non-null elements.
int	groupCount() Return the number of groups in the selection.
Selection	insert(String name, String beforeSelector) Inserts a new element with the specified name before the element matching the specified before selector, for each element in the current selection.
com.google.gwt.dom.client.Element	parentNode(int i) Return the parentNode property of the i-th group of the selection.
Selection	prepend(String name) Insert a new element before any other existing children.
Selection	select(DatumFunction<com.google.gwt.dom.client.Element> func) Creates a new selection containing the first non-null element returned by the given function.
Selection	select(String selector) For each element in the current selection, selects the first descendant element that matches the specified selector string.

Methods inherited from class com.google.gwt.core.client.JavaScriptObject

cast, createArray, createArray, createFunction, createObject, equals, hashCode, toSource, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

EnteringSelection

protected EnteringSelection()

Method Detail

append

public final Selection append(String name)

Appends a new element with the specified name as the last child of each element in the current selection.

Returns a new selection containing the appended elements.

Each new element inherits the data of the current elements, if any, in the same manner as select for subselections.

The name must be specified as a constant, though in the future we might allow appending of existing elements or a function to generate the name dynamically. The element's tag name may have a namespace prefix, such as "svg:text" to create a "text" element in the SVG namespace. By default, D3 supports svg, xhtml, xlink, xml and xmlns namespaces. Additional namespaces can be registered by adding to d3.ns.prefix.

Parameters:

name - the name of the new element to append

Returns:

a new selection containing the appended elements

prepend

public final Selection prepend(String name)

Insert a new element before any other existing children.

The method returns a new Selection containing the inserted element.

Parameters:

string -

Returns:

a new selection containing the inserted element

select

public final Selection select(String selector)

For each element in the current selection, selects the first descendant element that matches the specified selector string.

If no element matches the specified selector for the current element, the element at the current index will be null in the returned selection; operators (with the exception of Selection.data()) automatically skip null elements, thereby preserving the index of the existing selection.

If the current element has associated data, this data is inherited by the returned subselection, and automatically bound to the newly selected elements.

If multiple elements match the selector, only the first matching element in document traversal order will be selected.

Parameters:

selector - the selector

Returns:

the returned selection, containing at most only one element

select

public final Selection select(DatumFunction<com.google.gwt.dom.client.Element> func)

Creates a new selection containing the first non-null element returned by the given function.

The function is evaluated for each element in the current selection (in order), being passed the current datum d and the current index i.

Parameters:

func -

Returns:

insert

public final Selection insert(String name,
               String beforeSelector)

Inserts a new element with the specified name before the element matching the specified before selector, for each element in the current selection.

Returns a new selection containing the inserted elements.

If the before selector does not match any elements, then the new element will be the last child as with append(String).

Each new element inherits the data of the current elements (if any), in the same manner as select for subselections. The name and before selector must be specified as constants, though in the future we might allow inserting of existing elements or a function to generate the name or selector dynamically.

For instance, insert("div", ":first-child") will prepend child div nodes to the current selection.

The element's tag name may have a namespace prefix, such as "svg:text" to create a "text" element in the SVG namespace. By default, D3 supports svg, xhtml, xlink, xml and xmlns namespaces. Additional namespaces can be registered by adding to d3.ns.prefix.

Parameters:

name -

beforeSelector - a selector to select element to insert the new element before

Returns:

a new selection containing the inserted elements

empty

public final boolean empty()

Returns true if the current selection is empty; a selection is empty if it contains no non-null elements.

Returns:

true if selection is empty, false otherwise.

call

public final Selection call(IsFunction jsFunction)

Invokes the specified function once, passing in the current selection as a single parameter.

Parameters:

jsFunction -

Returns:

the current selection

parentNode

public final com.google.gwt.dom.client.Element parentNode(int i)

Return the parentNode property of the i-th group of the selection.

A parentNode is the node where element will be added using append.

When using D3.select(java.lang.String), D3.selectAll(java.lang.String) there is only one group and its parent node is the document root element (the html tag).

When creating a selection from an initial selection using select(java.lang.String), (TODO: check that) there may be more than one group, but the parent node of each group is the document root element (the html tag).

When creating a selection from an initial selection using Selection.selectAll(java.lang.String), there may be more than one group, and the parent node of each group is the corresponding node of the initial selection.

Parameters:

i - the index of the group

groupCount

public final int groupCount()

Return the number of groups in the selection.

The notion of group is only relevant to nested selections.

Selections created by D3.select(java.lang.String) and D3.selectAll(java.lang.String) always have only 1 group.

Selections created from an initial selection with select(java.lang.String) or Selection.selectAll(java.lang.String) have a group count equals to the number of nodes in the initial selection.

Returns:

the number of groups

asElementArray

public final Array<Array<com.google.gwt.dom.client.Element>> asElementArray()

Return the internal structure of the selection.

Returns:

this selection as an array of array of elements