com.github.gwtd3.api

Class D3

java.lang.Object

com.google.gwt.core.client.JavaScriptObject

com.github.gwtd3.api.D3

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

Entry point for D3 api modules. A lot of methods of this class allow access to other classes:

• select(Element) methods and Selection - manipulate elements in the current document.
• The array methods are in Array and Arrays classes.
• The interpolators methods are in Array and Arrays classes.
• Interpolation methods are in Interpolators.

Author:

Anthony Schiochet

Field Summary

Fields

Modifier and Type	Field and Description
static Scales	scale The scale factory module.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	D3()

Method Summary

Methods

Modifier and Type	Method and Description
static Behavior	behavior()
static <T> Dsv<T>	csv()
static <T> Dsv<T>	csv(String url) Issues an HTTP GET request for the comma-separated values (CSV) file at the specified url.
static <T> Dsv<T>	csv(String url, DsvCallback<T> callback) Issues an HTTP GET request for the comma-separated values (CSV) file at the specified url.
static <T> Dsv<T>	csv(String url, DsvObjectAccessor<T> accessor) Issues an HTTP GET request for the comma-separated values (CSV) file at the specified url.
static <T> Dsv<T>	csv(String url, DsvObjectAccessor<T> accessor, DsvCallback<T> callback) Issues an HTTP GET request for the comma-separated values (CSV) file at the specified url.
static Drag.DragEvent	dragEvent() Get the DragEvent from within a Drag listener.
static <T extends com.google.gwt.user.client.Event> T	event() Retrieve the current event, if any.
static Coords	eventAsCoords() Retrieve the current event if any, as a Coords object containing the x and y of the mouse.
static Coords	eventAsDCoords() Retrieve the current event if any, as a Coords object containing the dx and dy representing the element's coordinates relative to its position at the beginning of the gesture.
static Formatter	format(String specifier) Returns a new Formatter function with the given string specifier.
static Prefix	formatPrefix(double value, double precision) Return the SI Prefix for the specified value at the specified precision.
static Geography	geo()
static Geometry	geom()
static com.google.gwt.core.client.JavaScriptObject	identity() Return the identity function: function(d) { return d; }
static <T> Array<String>	keys(com.google.gwt.core.client.JavaScriptObject object) Returns an array containing the property names of the specified object (an associative array).
static Layout	layout()
static com.google.gwt.core.client.JsArrayNumber	mouse(com.google.gwt.dom.client.Node container) Returns the x and y coordinates of the current d3.event, relative to the specified container.
static Coords	mouseAsCoords(com.google.gwt.dom.client.Node container) Returns the x and y coordinates of the current d3.event, relative to the specified container.
static double	mouseX(com.google.gwt.dom.client.Node container) Returns the x coordinate of the current d3.event, relative to the specified container.
static double	mouseY(com.google.gwt.dom.client.Node container) Returns the y coordinate of the current d3.event, relative to the specified container.
static String	requote(String string) Returns a quoted (escaped) version of the specified string such that the string may be embedded in a regular expression as a string literal.
static double	round(double value, int digits) Returns the value x rounded to n digits after the decimal point.
static Selection	select(com.google.gwt.dom.client.Element element) Selects the specified element.
static Selection	select(String selector) Selects the first element that matches the specified selector string, returning a single-element selection.
static Selection	select(com.google.gwt.user.client.ui.Widget widget) Selects the specified widget.
static Selection	selectAll(Array<com.google.gwt.dom.client.Element> nodes) Selects the specified array of elements.
static Selection	selectAll(Collection<com.google.gwt.dom.client.Element> nodes) Selects the specified collection of elements.
static Selection	selectAll(com.google.gwt.dom.client.Element... nodes) Selects the specified array of elements.
static Selection	selectAll(com.google.gwt.dom.client.NodeList<?> nodes) Selects the list of elements.
static Selection	selectAll(String selector) Selects all elements that match the specified selector.
static Selection	selectAll(com.google.gwt.user.client.ui.Widget... nodes) Selects the elements corresponding to the root elements of the widgets in the specified array.
static Selection	selectAll(com.google.gwt.user.client.ui.WidgetCollection widgets) Selects the specified collection of elements.
static void	shuffle(char[] input)
static void	shuffle(int[] input)
static void	shuffle(List<?> objects) Randomly shuffle the list of objects provided.
static SVG	svg()
static Time	time()
static void	timer(TimerFunction command) Alias for timer(TimerFunction, int) with a delay equals to 0.
static void	timer(TimerFunction command, int delayMillis) Alias for timer(TimerFunction, int, int) with a mark equals to the "now" timestamp (i.e new Date().getTime()).
static void	timer(TimerFunction command, int delayMillis, int markMillis) Start a custom animation timer, invoking the specified TimerFunction repeatedly until it returns true.
static void	timerFlush() Immediately execute (invoke once) any active timers.
static com.google.gwt.core.client.JsArrayMixed	touches(com.google.gwt.dom.client.Node container) Returns the x and y coordinates of each touch associated with the current d3.event, based on the touches attribute, relative to the specified container.
static Transition	transition() Create an animated transition.
static <T> Dsv<T>	tsv()
static <T> Dsv<T>	tsv(String url) Issues an HTTP GET request for the comma-separated values (TSV) file at the specified url.
static <T> Dsv<T>	tsv(String url, DsvCallback<T> callback) Issues an HTTP GET request for the comma-separated values (TSV) file at the specified url.
static <T> Dsv<T>	tsv(String url, DsvObjectAccessor<T> accessor) Issues an HTTP GET request for the comma-separated values (TSV) file at the specified url.
static <T> Dsv<T>	tsv(String url, DsvObjectAccessor<T> accessor, DsvCallback<T> callback) Issues an HTTP GET request for the comma-separated values (TSV) file at the specified url.
static String	version()
static Zoom.ZoomEvent	zoomEvent() Get the ZoomEvent from within a Zoom listener.

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

scale

public static final Scales scale

The scale factory module.

Constructor Detail

D3

protected D3()

Method Detail

version

public static final String version()

Returns:

the version of the d3 API

select

public static final Selection select(String selector)

Selects the first element that matches the specified selector string, returning a single-element selection. If no elements in the current document match the specified selector, returns the empty selection. If multiple elements match the selector, only the first matching element (in document traversal order) will be selected.

The selector is a valid CSS3 selector. For example, you can select by tag ("div"), class (".awesome"), unique identifier ("#foo"), attribute ("[color=red]"), or containment ("parent child"). Selectors can also be intersected (".this.that" for logical AND) or unioned (".this, .that" for logical OR)

Parameters:

selector - a CSS3 selector

Returns:

the Selection

select

public static final Selection select(com.google.gwt.dom.client.Element element)

Selects the specified element. This is useful if you already have a reference to an element, or a global such as Document.getBody()

Parameters:

element - the element to select

Returns:

the Selection

select

public static final Selection select(com.google.gwt.user.client.ui.Widget widget)

Selects the specified widget. This is useful if you already have a reference to a widget, or a global such as RootPanel.get()

Parameters:

widget - the widget to select

Returns:

the Selection

selectAll

public static final Selection selectAll(String selector)

Selects all elements that match the specified selector. The elements will be selected in document traversal order (top-to-bottom). If no elements in the current document match the specified selector, returns the empty selection.

Parameters:

selector -

Returns:

selectAll

public static final Selection selectAll(com.google.gwt.dom.client.NodeList<?> nodes)

Selects the list of elements.

Parameters:

nodes - the elements

Returns:

the selection

selectAll

public static final Selection selectAll(Array<com.google.gwt.dom.client.Element> nodes)

Selects the specified array of elements.

Parameters:

nodes - the elements

Returns:

the selection

selectAll

public static final Selection selectAll(com.google.gwt.dom.client.Element... nodes)

Selects the specified array of elements.

Parameters:

nodes - the elements

Returns:

the selection

selectAll

public static final Selection selectAll(Collection<com.google.gwt.dom.client.Element> nodes)

Selects the specified collection of elements.

Parameters:

nodes - the elements

Returns:

the selection

selectAll

public static final Selection selectAll(com.google.gwt.user.client.ui.Widget... nodes)

Selects the elements corresponding to the root elements of the widgets in the specified array.

Parameters:

nodes - the elements

Returns:

the selection

selectAll

public static final Selection selectAll(com.google.gwt.user.client.ui.WidgetCollection widgets)

Selects the specified collection of elements.

Parameters:

nodes - the elements

Returns:

the selection

transition

public static final Transition transition()

Create an animated transition.

This is equivalent to D3.select(document).transition(). This method is used rarely, as it is typically easier to derive a transition from an existing selection, rather than deriving a selection from an existing transition.

Returns:

the transition the new transition

shuffle

public static final void shuffle(List<?> objects)

Randomly shuffle the list of objects provided.

Note: Collections.shuffle(List) is not GWT compatible

Parameters:

objects - the list to shuffle

shuffle

public static final void shuffle(int[] input)

shuffle

public static final void shuffle(char[] input)

svg

public static final SVG svg()

Returns:

the svg module

layout

public static final Layout layout()

Returns:

the layout module

geom

public static final Geometry geom()

Returns:

the Geometry module

geo

public static final Geography geo()

Returns:

the Geography module

timer

public static final void timer(TimerFunction command)

Alias for timer(TimerFunction, int) with a delay equals to 0.

Parameters:

command - the command to be executed until it returns true.

delayMillis - the delay to expires before the command should start being invoked (may be negative if markMillis is in the future)

timer

public static final void timer(TimerFunction command,
         int delayMillis)

Alias for timer(TimerFunction, int, int) with a mark equals to the "now" timestamp (i.e new Date().getTime()).

Parameters:

command - the command to be executed until it returns true.

delayMillis - the delay to expires before the command should start being invoked (may be negative if markMillis is in the future)

timer

public static final void timer(TimerFunction command,
         int delayMillis,
         int markMillis)

Start a custom animation timer, invoking the specified TimerFunction repeatedly until it returns true.

There is no way to cancel the timer after it starts, so make sure your timer function returns true when done! The optional numeric delay [unit: integer, millisecond] may be specified when the given function should only start to be invoked after delay milliseconds have expired after the specified mark timestamp [unit: integer, milliseconds since epoch].

When mark is omitted, Date.now() is assumed instead. Otherwise, you may use Date.getTime to convert your Date object to a suitable mark timestamp.

You may use delay and mark to specify relative and absolute moments in time when the function should start being invoked, e.g. a calendar-based event might be coded as

 Date appointment = new Date(2012, 09, 29, 14, 0, 0); // @ 29/sep/2012, 1400 hours
 ...
 // flash appointment on screen when it's due in 4 hours or less: note that negative (delay) is okay!
 d3.timer(flash_appointments_due, -4 * 3600 * 1000, appointment);
 
 

Parameters:

command - the command to be executed until it returns true.

delayMillis - the delay to expires before the command should start being invoked (may be negative if markMillis is in the future)

markMillis - the timestamp from which the delay starts

timerFlush

public static final void timerFlush()

Immediately execute (invoke once) any active timers.

Normally, zero-delay transitions are executed after an instantaneous delay (<10ms).

This can cause a brief flicker if the browser renders the page twice: once at the end of the first event loop, then again immediately on the first timer callback.

By flushing the timer queue at the end of the first event loop, you can run any zero-delay transitions immediately and avoid the flicker.

Note: the original method is d3.timer.flush() but has been pushed here because the timer API is limited to this method

time

public static final Time time()

Returns:

the time module

event

public static final <T extends com.google.gwt.user.client.Event> T event()

Retrieve the current event, if any.

This global variable exists during an event listener callback registered with the on operator. The current event is reset after the listener is notified in a finally block. This allows the listener function to have the same form as other operator functions, being passed the current datum d and index i.

The event() object is a DOM event and implements the standard event fields like timeStamp and keyCode as well as methods like preventDefault() and stopPropagation(). While you can use the native event's pageX and pageY, it is often more convenient to transform the event position to the local coordinate system of the container that received the event. For example, if you embed an SVG in the normal flow of your page, you may want the event position relative to the top-left corner of the SVG image. If your SVG contains transforms, you might also want to know the position of the event relative to those transforms.

Use the d3.mouse operator for the standard mouse pointer, and use d3.touches for multitouch events on iOS.

You may get an instance of D3Event by an auto-casting call:

 
     D3Event d3e = D3.event();
     //allow a call to d3e.sourceEvent();
 
 

Returns:

the instance of Event

eventAsCoords

public static final Coords eventAsCoords()

Retrieve the current event if any, as a Coords object containing the x and y of the mouse. This is useful when using Drag behavior.

Returns:

the current event as a Coords object

eventAsDCoords

public static final Coords eventAsDCoords()

Retrieve the current event if any, as a Coords object containing the dx and dy representing the element's coordinates relative to its position at the beginning of the gesture. This is useful when using Drag behavior.

Returns:

the current event as a Coords object

mouse

public static final com.google.gwt.core.client.JsArrayNumber mouse(com.google.gwt.dom.client.Node container)

Returns the x and y coordinates of the current d3.event, relative to the specified container. The container may be an HTML or SVG container element, such as an svg:g or svg:svg. The coordinates are returned as a two-element array [ x, y].

Parameters:

container -

Returns:

mouseAsCoords

public static final Coords mouseAsCoords(com.google.gwt.dom.client.Node container)

Returns the x and y coordinates of the current d3.event, relative to the specified container. The container may be an HTML or SVG container element, such as an svg:g or svg:svg. The coordinates are returned as a two-element array [ x, y].

Parameters:

container -

Returns:

mouseX

public static final double mouseX(com.google.gwt.dom.client.Node container)

Returns the x coordinate of the current d3.event, relative to the specified container. The container may be an HTML or SVG container element, such as an svg:g or svg:svg. The coordinates are returned as a two-element array [ x, y].

Parameters:

container -

Returns:

mouseY

public static final double mouseY(com.google.gwt.dom.client.Node container)

Returns the y coordinate of the current d3.event, relative to the specified container. The container may be an HTML or SVG container element, such as an svg:g or svg:svg. The coordinates are returned as a two-element array [ x, y].

Parameters:

container -

Returns:

touches

public static final com.google.gwt.core.client.JsArrayMixed touches(com.google.gwt.dom.client.Node container)

Returns the x and y coordinates of each touch associated with the current d3.event, based on the touches attribute, relative to the specified container.

The container may be an HTML or SVG container element, such as an svg:g or svg:svg.

The coordinates are returned as an array of two-element arrays [ [ x1, y1], [ x2, y2], … ].

Parameters:

container - the node to get the coords relative to

Returns:

an array of array of 2 elements.

csv

public static final <T> Dsv<T> csv()

Returns:

the CSV module

csv

public static final <T> Dsv<T> csv(String url,
             DsvCallback<T> callback)

Issues an HTTP GET request for the comma-separated values (CSV) file at the specified url.

The file contents are assumed to be RFC4180-compliant. The mime type of the request will be "text/csv". The request is processed asynchronously, such that this method returns immediately after opening the request. When the CSV data is available, the specified callback will be invoked with the parsed rows as the argument. If an error occurs, the callback function will instead be invoked with null.

csv

public static final <T> Dsv<T> csv(String url,
             DsvObjectAccessor<T> accessor,
             DsvCallback<T> callback)

Issues an HTTP GET request for the comma-separated values (CSV) file at the specified url.

The file contents are assumed to be RFC4180-compliant. The mime type of the request will be "text/csv". The request is processed asynchronously, such that this method returns immediately after opening the request. When the CSV data is available, the specified callback will be invoked with the parsed rows as the argument. If an error occurs, the callback function will instead be invoked with null. The accessor may be specified, which is then passed to d3.csv.parse; the accessor may also be specified by using the return request object’s row function.

csv

public static final <T> Dsv<T> csv(String url,
             DsvObjectAccessor<T> accessor)

Issues an HTTP GET request for the comma-separated values (CSV) file at the specified url.

The file contents are assumed to be RFC4180-compliant. The mime type of the request will be "text/csv". The request is processed asynchronously, such that this method returns immediately after opening the request. When the CSV data is available, the specified callback will be invoked with the parsed rows as the argument. If an error occurs, the callback function will instead be invoked with null. The accessor may be specified, which is then passed to d3.csv.parse; the accessor may also be specified by using the return request object’s row function.

csv

public static final <T> Dsv<T> csv(String url)

Issues an HTTP GET request for the comma-separated values (CSV) file at the specified url.

The file contents are assumed to be RFC4180-compliant. The mime type of the request will be "text/csv". The request is processed asynchronously, such that this method returns immediately after opening the request.

tsv

public static final <T> Dsv<T> tsv()

Returns:

the TSV module

tsv

public static final <T> Dsv<T> tsv(String url,
             DsvCallback<T> callback)

Issues an HTTP GET request for the comma-separated values (TSV) file at the specified url.

The file contents are assumed to be RFC4180-compliant. The mime type of the request will be "text/tsv". The request is processed asynchronously, such that this method returns immediately after opening the request. When the TSV data is available, the specified callback will be invoked with the parsed rows as the argument. If an error occurs, the callback function will instead be invoked with null.

tsv

public static final <T> Dsv<T> tsv(String url,
             DsvObjectAccessor<T> accessor,
             DsvCallback<T> callback)

Issues an HTTP GET request for the comma-separated values (TSV) file at the specified url.

The file contents are assumed to be RFC4180-compliant. The mime type of the request will be "text/tsv". The request is processed asynchronously, such that this method returns immediately after opening the request. When the TSV data is available, the specified callback will be invoked with the parsed rows as the argument. If an error occurs, the callback function will instead be invoked with null. The accessor may be specified, which is then passed to d3.tsv.parse; the accessor may also be specified by using the return request object’s row function.

tsv

public static final <T> Dsv<T> tsv(String url,
             DsvObjectAccessor<T> accessor)

Issues an HTTP GET request for the comma-separated values (TSV) file at the specified url.

The file contents are assumed to be RFC4180-compliant. The mime type of the request will be "text/tsv". The request is processed asynchronously, such that this method returns immediately after opening the request. When the TSV data is available, the specified callback will be invoked with the parsed rows as the argument. If an error occurs, the callback function will instead be invoked with null. The accessor may be specified, which is then passed to d3.tsv.parse; the accessor may also be specified by using the return request object’s row function.

tsv

public static final <T> Dsv<T> tsv(String url)

Issues an HTTP GET request for the comma-separated values (TSV) file at the specified url.

The file contents are assumed to be RFC4180-compliant. The mime type of the request will be "text/tsv". The request is processed asynchronously, such that this method returns immediately after opening the request.

keys

public static final <T> Array<String> keys(com.google.gwt.core.client.JavaScriptObject object)

Returns an array containing the property names of the specified object (an associative array). The order of the returned array is undefined.

Parameters:

object - the object to convert to an array

Returns:

an array containing the property names.

format

public static final Formatter format(String specifier)

Returns a new Formatter function with the given string specifier. A format function takes a number as the only argument, and returns a string representing the formatted number. Please see Formatter javadoc for the specifier specification.

Parameters:

specifier - the given string specifier.

Returns:

the format function.

See Also:

D3.js official documentation

formatPrefix

public static final Prefix formatPrefix(double value,
                  double precision)

Return the SI Prefix for the specified value at the specified precision.

This method is used by format(String) for the %s format.

Parameters:

value - the value to be prefixed

precision - the precision

Returns:

the prefix

round

public static final double round(double value,
           int digits)

Returns the value x rounded to n digits after the decimal point. If n is omitted, it defaults to zero. The result is a number. Values are rounded to the closest multiple of 10 to the power minus n; if two multiples are equally close, the value is rounded up in accordance with the built-in round function. Note that the resulting number when converted to a string may be imprecise due to IEEE floating point precision; to format a number to a string with a fixed number of decimal points, use d3.format instead.

Parameters:

value -

digits -

Returns:

requote

public static final String requote(String string)

Returns a quoted (escaped) version of the specified string such that the string may be embedded in a regular expression as a string literal.

Parameters:

string - the input string

Returns:

the regexp escaped string

behavior

public static final Behavior behavior()

Returns:

the behaviour module

zoomEvent

public static final Zoom.ZoomEvent zoomEvent()

Get the ZoomEvent from within a Zoom listener.

Returns:

the zoom event

dragEvent

public static final Drag.DragEvent dragEvent()

Get the DragEvent from within a Drag listener.

Returns:

the drag event

identity

public static final com.google.gwt.core.client.JavaScriptObject identity()

Return the identity function:

function(d) { return d; }

Returns:

the identity function