com.github.gwtd3.api.core

Class Selection

java.lang.Object

com.google.gwt.core.client.JavaScriptObject

com.github.gwtd3.api.core.EnteringSelection

com.github.gwtd3.api.core.Selection

Direct Known Subclasses:

UpdateSelection

public class Selection
extends EnteringSelection

A selection is an array of elements pulled from the current document. D3 uses CSS3 to select elements. See D3.select(String) and D3#select(com.google.gwt.dom.client.Node) methods for creating Selection.

If your browser doesn't support selectors natively, you can include Sizzle before D3 for backwards-compatibility. TODO: include Sizzle lib dynamically according to the user.agent property (ie6)

After selecting elements, you apply operators to them to do stuff. These operators can get or set attributes, styles, properties, HTML and text content. Attribute values and such are specified as either constants or functions; the latter are evaluated for each element in the selection.

You can also join selections to data; this data is available to operators for data-driven transformations. In addition, joining to data produces enter and exit subselections, so that you may add or remove elements in response to changes in data.

You won't generally need to use for loops or recursive functions to modify the document with D3. That's because you operate on entire selections at once, rather than looping over individual elements. However, you can still loop over elements manually if you wish: there's an each(DatumFunction) operator which invokes an arbitrary function, and (TODO) selections are arrays, so elements can be accessed directly (e.g., selection[0][0]).

D3 supports method chaining for brevity when applying multiple operators: the operator return value is the selection.

Creating selections

D3 provides two top-level methods for selecting elements: D3.select(String) and D3.selectAll(String). These methods accept selector strings; the former selects only the first matching element, while the latter selects all matching elements in document traversal order. There are also variant of these methods which accept nodes, which is useful to integrate with GWT Element API.

Operating on selections

Selections are arrays of elements—literally. D3 binds additional methods to the array so that you can apply operators to the selected elements, such as setting an attribute on all the selected elements. One nuance is that selections are grouped: rather than a one-dimensional array, each selection is an array of arrays of elements. This preserves the hierarchical structure of subselections. Most of the time, you can ignore this detail, but that's why a single-element selection looks like [[node]] rather than [node]. For more on nested selections, see Nested Selections.

If you want to learn how selections work, try selecting elements interactively using your browser's developer console. You can inspect the returned array to see which elements were selected, and how they are grouped. You can also then apply operators to the selected elements and see how the page content changes.

Subselections

Whereas the top-level D3.select(String) methods query the entire document, a selection's EnteringSelection.select(String) and selectAll(String) operators restrict queries to descendants of each selected element; we call this "subselection". For example, d3.selectAll("p").select("b") returns the first bold ("b") elements in every paragraph ("p") element. Subselecting via selectAll(String) groups elements by ancestor. Thus, d3.selectAll("p").selectAll("b") groups by paragraph, while d3.selectAll("p b") returns a flat selection. Subselecting via select is similar, but preserves groups and propagates data. Grouping plays an important role in the data join, and functional operators may depend on the numeric index of the current element within its group.

Author:

Anthony Schiochet

Field Summary

Fields

Modifier and Type	Field and Description
static String	DATA_PROPERTY Name of the element property in which D3 stores the datum of an element.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Selection()

Method Summary

Methods

Modifier and Type	Method and Description
String	attr(String name) Returns the value of the specified attribute for the first non-null element in the selection.
<T> Selection	attr(String name, boolean value) See attr(String, String).
Selection	attr(String name, DatumFunction<?> callback) Sets the attribute with the specified name to the value returned by the specified function on all selected elements.
Selection	attr(String name, double value) See attr(String, String).
Selection	attr(String name, PathDataGenerator value) Sets the attribute with the specified name to the specified PathDataGenerator value on all selected elements.
<T> Selection	attr(String name, String value) Sets the attribute with the specified name to the specified value on all selected elements.
boolean	classed(String classNames) Returns true if and only if the first non-null element in this selection has the specified class.
Selection	classed(String classNames, boolean add) Sets whether or not the specified class(es) is(are) associated with the selected elements.
Selection	classed(String classNames, DatumFunction<Boolean> addFunction) Sets whether or not the class should be associated or not to the elements, according to the return value of the given function.
<T> Array<T>	data() Returns the array of data for the first group in the selection.
UpdateSelection	data(byte[] array) Joins the specified array of data with the current selection using the default by-index key mapping.
UpdateSelection	data(byte[] array, KeyFunction<?> keyFunction) Same as data(JavaScriptObject, KeyFunction).
<T extends com.google.gwt.core.client.JavaScriptObject> UpdateSelection	data(DatumFunction<T> callback) Joins each array returned by the specified function to a group of the current selection, using the default by-index key mapping.
UpdateSelection	data(double[] array) Joins the specified array of data with the current selection using the default by-index key mapping.
UpdateSelection	data(double[] array, KeyFunction<?> keyFunction) Same as data(JavaScriptObject, KeyFunction).
UpdateSelection	data(float[] array) Joins the specified array of data with the current selection using the default by-index key mapping.
UpdateSelection	data(float[] array, KeyFunction<?> keyFunction) Same as data(JavaScriptObject, KeyFunction).
UpdateSelection	data(int[] array) Joins the specified array of data with the current selection using the default by-index key mapping.
UpdateSelection	data(int[] array, KeyFunction<?> keyFunction) Same as data(JavaScriptObject, KeyFunction).
UpdateSelection	data(com.google.gwt.core.client.JavaScriptObject array) Joins the specified array of values with the current selection using the default by-index key mapping.
UpdateSelection	data(com.google.gwt.core.client.JavaScriptObject array, KeyFunction<?> keyFunction) Same as data(JavaScriptObject) but let the user control how to map data to the selection.
UpdateSelection	data(List<?> list) Same as #data(JavaScriptObject) for an List of objects.
UpdateSelection	data(List<?> list, KeyFunction<?> keyFunction) Same as data(JavaScriptObject, KeyFunction) for an List of objects.
UpdateSelection	data(long[] array) Joins the specified array of data with the current selection using the default by-index key mapping.
UpdateSelection	data(long[] array, KeyFunction<?> keyFunction) Same as data(JavaScriptObject, KeyFunction).
UpdateSelection	data(Object[] array) Joins the specified array of data with the current selection using the default by-index key mapping.
UpdateSelection	data(Object[] array, KeyFunction<?> keyFunction) Same as data(JavaScriptObject, KeyFunction).
UpdateSelection	data(short[] array) Joins the specified array of data with the current selection using the default by-index key mapping.
UpdateSelection	data(short[] array, KeyFunction<?> keyFunction) Same as data(JavaScriptObject, KeyFunction).
Value	datum() Returns the bound datum for the first non-null element in the selection.
<T> Selection	datum(DatumFunction<T> datumFunction) Sets the bound data to the specified value on all selected elements.
Selection	datum(Object object) Sets the bound data to the specified value on all selected elements.
Selection	each(DatumFunction<Void> func) Invokes the specified function for each element in the current selection, passing in the current datum d and index i.
Selection	filter(DatumFunction<com.google.gwt.dom.client.Element> datumFunction) Filters the selection, returning a new selection that contains only the elements returned by the given function.
Selection	filter(String selector) Filters the selection, returning a new selection that contains only the elements for which the specified selector is true.
String	html() Returns the value of the inner HTML content for the first non-null element in the selection.
Selection	html(DatumFunction<String> callback) Sets the inner html content to the value returned by the specified function on all selected elements.
Selection	html(String value) Sets the inner html content of all selected elements to the specified value.
Selection	interrupt() Immediately interrupts the current transition, if any.
com.google.gwt.dom.client.Element	node() Returns the first non-null element in the current selection.
Selection	on(String eventType, DatumFunction<Void> listener) Same as on(String, DatumFunction, boolean) with false for the useCapture flag.
Selection	on(String eventType, DatumFunction<Void> listener, boolean useCapture) Adds or removes an event listener to each element in the current selection, for the specified type.
Selection	order() Re-inserts elements into the document such that the document order matches the selection order.
Value	property(String name) This method return the value of the specified property for the first non-null element in the selection.
<T> Selection	property(String name, boolean value) See property(String, String).
Selection	property(String name, DatumFunction<?> callback) Sets the property with the specified name to the value returned by the specified function on all selected elements.
Selection	property(String name, double value) See property(String, String).
<T> Selection	property(String name, com.google.gwt.core.client.JavaScriptObject value) See property(String, String).
<T> Selection	property(String name, String value) Sets the property with the specified name to the specified value on all selected elements.
Selection	remove() Removes the elements in the current selection from the current document.
<T extends com.google.gwt.dom.client.Node> Selection	selectAll(DatumFunction<com.google.gwt.dom.client.NodeList<T>> func) For each element in the current selection, selects elements returned by the specified function, which is invoked in the same manner as other operator functions, being passed the current datum d and index i, with the this context as the current DOM element.
Selection	selectAll(String selector) For each element in the current selection, selects descendant elements that match the specified selector string.
int	size() Return the number of elements in the current selection.
Selection	sort(Comparator<Value> comparator) Sorts the elements in the current selection according to the specified comparator function.
String	style(String name) Returns the current computed value of the specified style property for the first non-null element in the selection.
Selection	style(String name, DatumFunction<?> callback) See Selection#style(String, T, boolean).
Selection	style(String name, DatumFunction<?> callback, boolean important) Sets the CSS style property with the specified name to the value returned by the given function on all selected elements.
Selection	style(String name, double value) See Selection#style(String, T, boolean).
Selection	style(String name, String value) See Selection#style(String, T, boolean).
String	text() Returns the value of the text content for the first non-null element in the selection.
Selection	text(DatumFunction<String> callback) Sets the text content to the value returned by the specified function on all selected elements.
<T> Selection	text(String value) Sets the text content of all selected elements to the given value.
Transition	transition() Starts a Transition for the current selection.

Methods inherited from class com.github.gwtd3.api.core.EnteringSelection

append, asElementArray, call, empty, groupCount, insert, parentNode, prepend, select, select

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

Field Detail

DATA_PROPERTY

public static final String DATA_PROPERTY

Name of the element property in which D3 stores the datum of an element.

See Also:

Constant Field Values

Constructor Detail

Selection

protected Selection()

Method Detail

node

public final com.google.gwt.dom.client.Element node()

Returns the first non-null element in the current selection. If the selection is empty, returns null.

Returns:

the first non-null element in the current selection or null if the selection is empty.

selectAll

public final Selection selectAll(String selector)

For each element in the current selection, selects descendant elements that match the specified selector string.

The returned selection is grouped by the ancestor node in the current selection. If no element matches the specified selector for the current element, the group at the current index will be empty in the returned selection.

The subselection does not inherit data from the current selection; however, if the data value is specified as a function, this function will be called with the data d of the ancestor node and the group index i to determine the data bindings for the subselection.

Grouping by selectAll also affects subsequent entering placeholder nodes. Thus, to specify the parent node when appending entering nodes, use select followed by selectAll:

 
 d3.select("body").selectAll("div")
 
 

You can see the parent node of each group by inspecting the parentNode property of each group array, such as selection[0].parentNode, or by using the EnteringSelection.parentNode(int) method.

TODO: check this method also work for EnteringSelections and pull it up in that case...

Parameters:

selector -

Returns:

selectAll

public final <T extends com.google.gwt.dom.client.Node> Selection selectAll(DatumFunction<com.google.gwt.dom.client.NodeList<T>> func)

For each element in the current selection, selects elements returned by the specified function, which is invoked in the same manner as other operator functions, being passed the current datum d and index i, with the this context as the current DOM element.

The returned selection is grouped by the ancestor node in the current selection. If no element matches the specified selector for the current element, the group at the current index will be empty in the returned selection.

The subselection does not inherit data from the current selection; however, if the data value is specified as a function, this function will be called with the data d of the ancestor node and the group index i to determine the data bindings for the subselection.

Grouping by selectAll also affects subsequent entering placeholder nodes. Thus, to specify the parent node when appending entering nodes, use select followed by selectAll:

 
 d3.select("body").selectAll("div")
 
 

You can see the parent node of each group by inspecting the parentNode property of each group array, such as selection[0].parentNode, or by using the EnteringSelection.parentNode(int) method.

TODO: check this method also work for EnteringSelections and pull it up in that case...

Parameters:

selector -

Returns:

attr

public final String attr(String name)

Returns the value of the specified attribute for the first non-null element in the selection. This is generally useful only if you know that the selection contains exactly one element.

The specified name may have a namespace prefix, such as xlink:href, to specify an "href" attribute in the XLink 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 attribute

Returns:

the value of the attribute

attr

public final <T> Selection attr(String name,
                 String value)

Sets the attribute with the specified name to the specified value on all selected elements.

The specified name may have a namespace prefix, such as xlink:href, to specify an "href" attribute in the XLink namespace. By default, D3 supports svg, xhtml, xlink, xml, and xmlns namespaces. Additional namespaces can be registered by adding to d3.ns.prefix.

A null value will remove the specified attribute.

Parameters:

name - the name of the attribute

value - the new value to assign, or null to remove the attribute

Returns:

the current selection

attr

public final Selection attr(String name,
             PathDataGenerator value)

Sets the attribute with the specified name to the specified PathDataGenerator value on all selected elements.

This method should always been used with a selection containing a svg <path> element by specifying "d" for the name argument.

The specified name may have a namespace prefix, such as xlink:href, to specify an "href" attribute in the XLink 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 attribute

value - the new value to assign

Returns:

the current selection

attr

public final Selection attr(String name,
             double value)

See attr(String, String).

Parameters:

name -

value -

Returns:

attr

public final <T> Selection attr(String name,
                 boolean value)

See attr(String, String).

Parameters:

name -

value -

Returns:

attr

public final Selection attr(String name,
             DatumFunction<?> callback)

Sets the attribute with the specified name to the value returned by the specified function on all selected elements.

The function is evaluated for each selected element (in order), being passed the current datum d and the current index i. The function's return value is then used to set each element's attribute. A null value will remove the specified attribute.

The specified name may have a namespace prefix, such as xlink:href, to specify an "href" attribute in the XLink 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 attribute

callback - the function used to compute the new value of the attribute

Returns:

the current selection

style

public final String style(String name)

Returns the current computed value of the specified style property for the first non-null element in the selection.

This is generally useful only if you know the selection contains exactly one element.

Note that the computed value may be different than the value that was previously set, particularly if the style property was set using a shorthand property (such as the "font" style, which is shorthand for "font-size", "font-face", etc.).

Parameters:

name - the name of the style to return

Returns:

the style value

style

public final Selection style(String name,
              String value)

See Selection#style(String, T, boolean).

Parameters:

name -

value -

Returns:

style

public final Selection style(String name,
              double value)

See Selection#style(String, T, boolean).

Parameters:

name -

value -

Returns:

style

public final Selection style(String name,
              DatumFunction<?> callback)

See Selection#style(String, T, boolean).

Parameters:

name -

value -

Returns:

style

public final Selection style(String name,
              DatumFunction<?> callback,
              boolean important)

Sets the CSS style property with the specified name to the value returned by the given function on all selected elements.

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

The function's return value's Object.toString() method is then used to set each element's style property.

A null value will remove the style property.

Parameters:

name - the name of the style to set

callback - the function to be called on each element and returning the value of the style

important - true if the style value should be marked as !important, false otherwise

Returns:

the current selection

classed

public final Selection classed(String classNames,
                boolean add)

Sets whether or not the specified class(es) is(are) associated with the selected elements.

This operator is a convenience routine for setting the "class" attribute; it understands that the "class" attribute is a set of tokens separated by spaces.

Under the hood, it will use the classList if available, for convenient adding, removing and toggling of CSS classes.

If add is true, then all elements are assigned the specified class(es), if not already assigned; if false, then the class(es) is(are) removed from all selected elements, if assigned.

Parameters:

className - the className(s) to add or remove

add - true to add false to remove the class(es) from all the elements of the selection

Returns:

the current selection

classed

public final boolean classed(String classNames)

Returns true if and only if the first non-null element in this selection has the specified class. This is generally useful only if you know the selection contains exactly one element.

Parameters:

className - the className to test the presence

Returns:

true if the first element of the selection has the given classname in the class attribute

classed

public final Selection classed(String classNames,
                DatumFunction<Boolean> addFunction)

Sets whether or not the class should be associated or not to the elements, according to the return value of the given function.

he function is evaluated for each selected element (in order), being passed the current datum d and the current index i, with the this context as the current DOM element. The function's return value is then used to assign or unassign the specified class on each element.

This operator is a convenience routine for setting the "class" attribute; it understands that the "class" attribute is a set of tokens separated by spaces.

Under the hood, it will use the classList if available, for convenient adding, removing and toggling of CSS classes.

If the function returns true, then the element is assigned the specified class, if not already assigned; if it returns false or null, then the class is removed from the element, if assigned.

Parameters:

className - the class to assign or not

addFunction - the function evaluated for each element and returning a boolean indicating to assign or not the class to the element

Returns:

the current selection

property

public final Value property(String name)

This method return the value of the specified property for the first non-null element in the selection. This is generally useful only if you know that the selection contains exactly one element.

Some HTML elements have special properties that are not addressable using standard attributes or styles. For example, form text fields have a value string property, and checkboxes have a checked boolean property, and underlying element has addressable fields, such as className. This method is used to address thoses properties.

Parameters:

name - the name of the property

Returns:

the value of the property

property

public final <T> Selection property(String name,
                     String value)

Sets the property with the specified name to the specified value on all selected elements.

Some HTML elements have special properties that are not addressable using standard attributes or styles. For example, form text fields have a value string property, and checkboxes have a checked boolean property, and underlying element has addressable fields, such as className. This method is used to address thoses properties.

A null value will remove the specified property.

Parameters:

name - the name of the attribute

value - the new value to assign, or null to remove the attribute

Returns:

the current selection

property

public final Selection property(String name,
                 double value)

See property(String, String).

Parameters:

name - the name of the property

value - the value

Returns:

the current selection

property

public final <T> Selection property(String name,
                     com.google.gwt.core.client.JavaScriptObject value)

See property(String, String).

Parameters:

name - the name of the property

value - the value

Returns:

the current selection

property

public final <T> Selection property(String name,
                     boolean value)

See property(String, String).

Parameters:

name - the name of the property

value - the value

Returns:

the current selection

property

public final Selection property(String name,
                 DatumFunction<?> callback)

Sets the property with the specified name to the value returned by the specified function on all selected elements.

The function is evaluated for each selected element (in order), being passed the current datum d and the current index i. The function's return value is then used to set each element's attribute. A null value will remove the specified attribute.

The specified name may have a namespace prefix, such as xlink:href, to specify an "href" attribute in the XLink namespace. By default, D3 supports svg, xhtml, xlink, xml, and xmlns namespaces. Additional namespaces can be registered by adding to d3.ns.prefix.

Note: if you provide a DatumFunction parameterized with a wrapper type, such as java.lang.Double or java.lang.Boolean, when getting the property value ( property(String)), you should use Value.as(Class) with the corresponding Class object, such as Value.as(Double) or Value.as(Boolean) to get the property value.

Parameters:

name - the name of the attribute

callback - the function used to compute the new value of the attribute

Returns:

the current selection

text

public final String text()

Returns the value of the text content for the first non-null element in the selection. This is generally useful only if you know that the selection contains exactly one element.

The text operator is based on the textContent property.

Returns:

the value of the text property

text

public final <T> Selection text(String value)

Sets the text content of all selected elements to the given value. A null value will clear the content.

The text operator is based on the textContent property; setting the text content will replace any existing child elements.

Parameters:

value - the new text value to set

Returns:

the current selection

text

public final Selection text(DatumFunction<String> callback)

Sets the text content to the value returned by the specified function on all selected elements. A null value will clear the content.

The function is evaluated for each selected element (in order), being passed the current datum d and the current index i. The function's return value is then used to set each element's text content.

The text operator is based on the textContent property; setting the text content will replace any existing child elements.

Parameters:

callback - the function used to compute the new text property

Returns:

the current selection

html

public final Selection html(DatumFunction<String> callback)

Sets the inner html content to the value returned by the specified function on all selected elements. A null value will clear the content.

The function is evaluated for each selected element (in order), being passed the current datum d and the current index i. The function's return value is then used to set each element's inner html content.

The html operator is based on the innerHTML property; setting the inner HTML content will replace any existing child elements. Also, you may prefer to use the EnteringSelection.append(String) or EnteringSelection.insert(String, String) operators to create HTML content in a data-driven way; this operator is intended for when you want a little bit of HTML, say for rich formatting.

Parameters:

callback - the function used to compute the new inner html property

Returns:

the current selection

html

public final Selection html(String value)

Sets the inner html content of all selected elements to the specified value. A null value will clear the content.

The html operator is based on the innerHTML property; setting the inner HTML content will replace any existing child elements. Also, you may prefer to use the EnteringSelection.append(String) or EnteringSelection.insert(String, String) operators to create HTML content in a data-driven way; this operator is intended for when you want a little bit of HTML, say for rich formatting.

Parameters:

value - the new value to set

Returns:

the current selection

html

public final String html()

Returns the value of the inner HTML content for the first non-null element in the selection. This is generally useful only if you know that the selection contains exactly one element.

The html operator is based on the innerHTML property.

Returns:

the value of the text property

remove

public final Selection remove()

Removes the elements in the current selection from the current document. Returns the current selection (the same elements that were removed) which are now “off-screen”, detached from the DOM. Note that there is not currently a dedicated API to add removed elements back to the document; however, you can pass a function to selection.each or selection.select to re-add elements.

The elements are removed from the DOM but still remains in the selection.

Returns:

the current selection containing only the removed elements

See Also:

that issue for more information.

size

public final int size()

Return the number of elements in the current selection.

Returns:

the number of elements

each

public final Selection each(DatumFunction<Void> func)

Invokes the specified function for each element in the current selection, passing in the current datum d and index i.

This operator is used internally by nearly every other operator, and can be used to invoke arbitrary code for each selected element.

The each operator can be used to process selections recursively, by using d3.select(context) within the callback function.

Parameters:

func - the callback function

Returns:

the current selection

data

public final <T> Array<T> data()

Returns the array of data for the first group in the selection.

The length of the returned array will match the length of the first group, and the index of each datum in the returned array will match the corresponding index in the selection.

If some of the elements in the selection are null, or if they have no associated data, then the corresponding element in the array will be undefined.

Returns:

the array of data for the first group in the selection

data

public final UpdateSelection data(com.google.gwt.core.client.JavaScriptObject array)

Joins the specified array of values with the current selection using the default by-index key mapping.

The specified values must be an array-like structure of data values, such as an array of numbers or objects. Use JsArrayUtils or JsArrays to turn your Java arrays into Javascript arrays (which has no overhead in prod mode), or use the variant data() methods.

The by-index key mapping means that the first datum in the array is assigned to the first element in the current selection, the second datum to the second selected element, and so on. If you want to control how data is mapped to elements, use the data methods that takes a KeyFunction parameter, such as data(JavaScriptObject, KeyFunction).

The given array specifies data for each group in the selection. Thus, if the selection has multiple groups (such as a D3.selectAll(java.lang.String) followed by a selectAll(java.lang.String)), and if you want different data for each group, you should rather use the method data(DatumFunction).

When data is assigned to an element, it is stored in the property DATA_PROPERTY, thus making the data "sticky" so that the data is available on re-selection.

Parameters:

array - the values array to map to the selection

Returns:

the update selection

data

public final UpdateSelection data(com.google.gwt.core.client.JavaScriptObject array,
                   KeyFunction<?> keyFunction)

Same as data(JavaScriptObject) but let the user control how to map data to the selection.

See KeyFunction's documentation.

Parameters:

array - the data array to map to the selection

keyFunction - the function to control how data is mapped to the selection elements

Returns:

the UpdateSelection

data

public final <T extends com.google.gwt.core.client.JavaScriptObject> UpdateSelection data(DatumFunction<T> callback)

Joins each array returned by the specified function to a group of the current selection, using the default by-index key mapping.

The specified callback must return an array-like structure of data values, such as an array of numbers or objects. Use Arrays, Array, or JsArrayUtils to turn your Java arrays into Javascript arrays (which has no overhead in prod mode).

This method is appropriate to join data on a multi-group selection, like one returned by d3.selectAll followed by a call to selection.selectAll.

For example, you may bind a two-dimensional array to an initial selection, and then bind the contained inner arrays to each subselection. The values function in this case is the identity function: it is invoked for each group of child elements, being passed the data bound to the parent element, and returns this array of data.

Parameters:

callback - the function called for each group in the selection, passing the data of the parent node of the group.

Returns:

the UpdateSelection

data

public final UpdateSelection data(Object[] array)

Joins the specified array of data with the current selection using the default by-index key mapping.

Parameters:

array - the data array to map to the selection

Returns:

the update selection

data

public final UpdateSelection data(Object[] array,
                   KeyFunction<?> keyFunction)

Same as data(JavaScriptObject, KeyFunction).

Parameters:

array - the data array to map to the selection

keyFunction - the function to control how data is mapped to the selection elements

Returns:

the update selection

data

public final UpdateSelection data(byte[] array)

Joins the specified array of data with the current selection using the default by-index key mapping.

Parameters:

array - the data array to map to the selection

Returns:

the update selection

data

public final UpdateSelection data(byte[] array,
                   KeyFunction<?> keyFunction)

Same as data(JavaScriptObject, KeyFunction).

Parameters:

array - the data array to map to the selection

keyFunction - the function to control how data is mapped to the selection elements

Returns:

the update selection

data

public final UpdateSelection data(double[] array)

Joins the specified array of data with the current selection using the default by-index key mapping.

Parameters:

array - the data array to map to the selection

Returns:

the update selection

data

public final UpdateSelection data(double[] array,
                   KeyFunction<?> keyFunction)

Same as data(JavaScriptObject, KeyFunction).

Parameters:

array - the data array to map to the selection

keyFunction - the function to control how data is mapped to the selection elements

Returns:

the update selection

data

public final UpdateSelection data(float[] array)

Joins the specified array of data with the current selection using the default by-index key mapping.

Parameters:

array - the data array to map to the selection

Returns:

the update selection

data

public final UpdateSelection data(float[] array,
                   KeyFunction<?> keyFunction)

Same as data(JavaScriptObject, KeyFunction).

Parameters:

array - the data array to map to the selection

keyFunction - the function to control how data is mapped to the selection elements

Returns:

the update selection

data

public final UpdateSelection data(int[] array)

Joins the specified array of data with the current selection using the default by-index key mapping.

Parameters:

array - the data array to map to the selection

Returns:

the update selection

data

public final UpdateSelection data(int[] array,
                   KeyFunction<?> keyFunction)

Same as data(JavaScriptObject, KeyFunction).

Parameters:

array - the data array to map to the selection

keyFunction - the function to control how data is mapped to the selection elements

Returns:

the update selection

data

public final UpdateSelection data(long[] array)

Joins the specified array of data with the current selection using the default by-index key mapping.

Parameters:

array - the data array to map to the selection

Returns:

the update selection

data

public final UpdateSelection data(long[] array,
                   KeyFunction<?> keyFunction)

Same as data(JavaScriptObject, KeyFunction).

Parameters:

array - the data array to map to the selection

keyFunction - the function to control how data is mapped to the selection elements

Returns:

the update selection

data

public final UpdateSelection data(short[] array)

Joins the specified array of data with the current selection using the default by-index key mapping.

Parameters:

array - the data array to map to the selection

Returns:

the update selection

data

public final UpdateSelection data(short[] array,
                   KeyFunction<?> keyFunction)

Same as data(JavaScriptObject, KeyFunction).

Parameters:

array - the data array to map to the selection

keyFunction - the function to control how data is mapped to the selection elements

Returns:

the update selection

data

public final UpdateSelection data(List<?> list)

Same as #data(JavaScriptObject) for an List of objects.

Parameters:

list -

Returns:

the UpdateSelection

See Also:

data(JavaScriptObject)

data

public final UpdateSelection data(List<?> list,
                   KeyFunction<?> keyFunction)

Same as data(JavaScriptObject, KeyFunction) for an List of objects.

Parameters:

list - the list

keyFunction - the key function

Returns:

the UpdateSelection

See Also:

data(JavaScriptObject)

datum

public final <T> Selection datum(DatumFunction<T> datumFunction)

Sets the bound data to the specified value on all selected elements.

Unlike the data() methods, this method does not compute a join (and thus does not compute enter and exit selections). This method is implemented on top of property(String).

All elements in the selection are given the same data.

A null value will delete the bound data. This operator has no effect on the index.

See datum

Parameters:

the - function providing the datum

Returns:

the current selection

datum

public final Selection datum(Object object)

Sets the bound data to the specified value on all selected elements.

Unlike the data() methods, this method does not compute a join (and thus does not compute enter and exit selections). This method is implemented on top of property(String).

All elements in the selection are given the same data.

A null value will delete the bound data. This operator has no effect on the index.

See datum

Parameters:

object - the datum

Returns:

the current selection

datum

public final Value datum()

Returns the bound datum for the first non-null element in the selection.

This is generally useful only if you know the selection contains exactly one element.

Returns:

the datum of the first non null element

filter

public final Selection filter(String selector)

Filters the selection, returning a new selection that contains only the elements for which the specified selector is true. Like the built-in array filter method, the returned selection does not preserve the index of the original selection; it returns a copy with elements removed.

Parameters:

selector - the CSS3 selector to be used as a filter

Returns:

a new selection containing the filtered elements

filter

public final Selection filter(DatumFunction<com.google.gwt.dom.client.Element> datumFunction)

Filters the selection, returning a new selection that contains only the elements returned by the given function.

The given function is called for each element in the current selection, with the datum corresponding to the current element. Like the built-in array filter method, the returned selection does not preserve the index of the original selection; it returns a copy with elements removed.

Parameters:

datumFunction - the function to be used as a filter

Returns:

a new selection containing the filtered elements

sort

public final Selection sort(Comparator<Value> comparator)

Sorts the elements in the current selection according to the specified comparator function.

The comparator function is passed two data elements a and b to compare, returning either a negative, positive, or zero value. If negative, then a should be before b; if positive, then a should be after b; otherwise, a and b are considered equal and the order is arbitrary.

Note that the sort is not guaranteed to be stable; however, it is guaranteed to have the same behavior as your browser's built-in Array#sort method on arrays.

Parameters:

comparator - the comparator to be used

order

public final Selection order()

Re-inserts elements into the document such that the document order matches the selection order.

This is equivalent to calling sort() if the data is already sorted, but much faster.

transition

public final Transition transition()

Starts a Transition for the current selection. Transitions behave much like selections, except operators animate smoothly over time rather than applying instantaneously.

Returns:

the new transition

interrupt

public final Selection interrupt()

Immediately interrupts the current transition, if any.

Does not cancel any scheduled transitions that have not yet started. To cancel scheduled transitions as well, simply create a new zero-delay transition after interrupting the current transition:

 selection
 .interrupt() // cancel the current transition
 .transition(); // preempt any scheduled transitions
 

Returns:

the current selection

on

public final Selection on(String eventType,
           DatumFunction<Void> listener)

Same as on(String, DatumFunction, boolean) with false for the useCapture flag.

Parameters:

eventType -

listener -

Returns:

on

public final Selection on(String eventType,
           DatumFunction<Void> listener,
           boolean useCapture)

Adds or removes an event listener to each element in the current selection, for the specified type.

The type is a string event type name, such as "click", "mouseover", or "submit". You may use BrowserEvents constants for convenience.

The specified listener is invoked in the same manner as other operator functions, being passed the current datum d and index i, with the this context as the current DOM element.

To access the current event within a listener, use the global d3.event. The return value of the event listener is ignored.

If an event listener was already registered for the same type on the selected element, the existing listener is removed before the new listener is added. To register multiple listeners for the same event type, the type may be followed by an optional namespace, such as "click.foo" and "click.bar".

To remove a listener, pass null as the listener. To remove all listeners for a particular event type, pass null as the listener, and .type as the type, e.g. selection.on(".foo", null).

Parameters:

eventType - the type of the event to listen to; prefix the type with a dot to remove all listeners (specifying null as the second parameter).

listener - the listener to be added or to replace the previous one, or null to remove the previous listener(s)

useCapture - a capture flag, which corresponds to the W3C useCapture flag: "After initiating capture, all events of the specified type will be dispatched to the registered EventListener before being dispatched to any EventTargets beneath them in the tree. Events which are bubbling upward through the tree will not trigger an EventListener designated to use capture."

Returns:

the current selection