com.github.gwtd3.api.svg

Class Brush

java.lang.Object

com.google.gwt.core.client.JavaScriptObject

com.github.gwtd3.api.svg.Brush

All Implemented Interfaces:

IsFunction

public class Brush
extends com.google.gwt.core.client.JavaScriptObject
implements IsFunction

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Brush.BrushEvent

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	Brush()

Method Summary

Methods

Modifier and Type	Method and Description
Brush	apply(Selection selection) Draws or redraws this brush into the specified selection of elements.
Brush	apply(Transition transition) Draws or redraws this brush into the specified transition of elements.
Array<Boolean>	clamp() Gets the current clamping behavior.
Brush	clamp(boolean clamp) Sets the current clamping behavior., for a brush where only one of the x-scale and y-scale are available.
Brush	clamp(boolean clampX, boolean clampY) Sets the current clamping behavior, for a brush where both an x- and y-scale are available.
Brush	clear() Clears the extent, making the brush extent empty().
boolean	empty() Returns true if and only if the brush extent is empty.
IsFunction	event() Same as event(Selection) or event(Transition), but allows the use of EnteringSelection.call(IsFunction).
Brush	event(Selection selection) Dispatch a brush gesture to registered listeners as a three event sequence: Brush.BrushEvent.BRUSH_START, Brush.BrushEvent.BRUSH, and Brush.BrushEvent.BRUSH_END.
Brush	event(Transition transition) Registers the appropriate tweens so that the brush dispatches events over the course of the transition: a Brush.BrushEvent.BRUSH_START event when the transition starts from the previously-set extent, Brush.BrushEvent.BRUSH events for each tick of the transition, and finally a Brush.BrushEvent.BRUSH_END event when the transition ends.
<T> Array<T>	extent() Get the current brush’s extent.
<T> Brush	extent(Array<T> array) Set the current brush’s extent.
<T> Brush	extent(double min, double max) Set the current brush’s extent for a one-dimensional brush (defined by its x scale, or by its y scale, but not both).
<T> Brush	extent(double x0, double y0, double x1, double y1) Set the current brush’s extent for a two-dimensional brush (defined by both its x scale and its y scale.
Brush	on(Brush.BrushEvent event, DatumFunction<Void> listener) Set the listener for the specified event type.
<T extends Scale<T>> T	x() Get the brush’s x-scale, which defaults to null.
Brush	x(Scale<?> scale) Set the brush’s x-scale.
<T extends Scale<T>> T	y() Get the brush’s y-scale, which defaults to null
Brush	y(Scale<?> scale) Set the brush’s y-scale

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

Brush

protected Brush()

Method Detail

x

public final Brush x(Scale<?> scale)

Set the brush’s x-scale.

The scale is typically defined as a QuantitativeScale, in which case the extent() is in data space from the scale's Scale.domain(); however, it may instead be defined as an OrdinalScale, where the extent is in pixel space from the scale's OrdinalScale.rangeExtent().

Parameters:

scale - the x-scale.

Returns:

the current brush.

x

public final <T extends Scale<T>> T x()

Get the brush’s x-scale, which defaults to null.

The scale is typically defined as a QuantitativeScale, in which case the extent() is in data space from the scale's Scale.domain(); however, it may instead be defined as an OrdinalScale, where the extent is in pixel space from the scale's OrdinalScale.rangeExtent().

Returns:

the brush’s x-scale.

y

public final Brush y(Scale<?> scale)

Set the brush’s y-scale. *

The scale is typically defined as a QuantitativeScale, in which case the extent() is in data space from the scale's Scale.domain(); however, it may instead be defined as an OrdinalScale, where the extent is in pixel space from the scale's OrdinalScale.rangeExtent().

Parameters:

scale - the y-scale.

Returns:

the current brush.

y

public final <T extends Scale<T>> T y()

Get the brush’s y-scale, which defaults to null. * *

The scale is typically defined as a QuantitativeScale, in which case the extent() is in data space from the scale's Scale.domain(); however, it may instead be defined as an OrdinalScale, where the extent is in pixel space from the scale's OrdinalScale.rangeExtent().

Returns:

the brush’s y-scale.

apply

public final Brush apply(Selection selection)

Draws or redraws this brush into the specified selection of elements.

The brush may be drawn into multiple elements simultaneously, but note that these brushes would share the same backing extent; typically, a brush is drawn into only one element at a time.

Parameters:

selection - the selection to draw the brush in

Returns:

the current brush

apply

public final Brush apply(Transition transition)

Draws or redraws this brush into the specified transition of elements. The brush will perform an automatic transition. Use event(Transition) to dispatch brush events during the transition for animated brushing.

The brush may be drawn into multiple elements simultaneously, but note that these brushes would share the same backing extent; typically, a brush is drawn into only one element at a time.

Parameters:

transition - the transition to draw the brush in

Returns:

the current brush

extent

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

Get the current brush’s extent.

The definition of the extent depends on the associated scales.
If both an x- and y-scale are available, then the extent is the two-dimensional array [‍[x0, y0], [x1, y1]], where x0 and y0 are the lower bounds of the extent, and x1 and y1 are the upper bounds of the extent. If only the x-scale is available, then the extent is defined as the one-dimensional array [x0, x1]; likewise, if only the y-scale is available, then the extent is [y0, y1]. If neither scale is available, then the extent is null.

When the extent is set to values, the resulting extent is preserved exactly. However, as soon as the brush is moved by the user (on mousemove following a mousedown), then the extent will be recomputed by calling ContinuousQuantitativeScale.invert(double). Note that, in this case, the values may be slightly imprecise due to the limited precision of pixels.

Note that this does not automatically redraw the brush or dispatch any events to listeners. To redraw the brush, call apply(Selection) or apply(Transition); to dispatch events, use event(Selection) or event(Transition).

Returns:

the current brush’s extent.

extent

public final <T> Brush extent(Array<T> array)

Set the current brush’s extent.

The definition of the extent depends on the associated scales.
If both an x- and y-scale are available, then the extent is the two-dimensional array [‍[x0, y0], [x1, y1]], where x0 and y0 are the lower bounds of the extent, and x1 and y1 are the upper bounds of the extent. If only the x-scale is available, then the extent is defined as the one-dimensional array [x0, x1]; likewise, if only the y-scale is available, then the extent is [y0, y1]. If neither scale is available, then the extent is null.

When the extent is set to values, the resulting extent is preserved exactly. However, as soon as the brush is moved by the user (on mousemove following a mousedown), then the extent will be recomputed by calling ContinuousQuantitativeScale.invert(double). Note that, in this case, the values may be slightly imprecise due to the limited precision of pixels.

Note that this does not automatically redraw the brush or dispatch any events to listeners. To redraw the brush, call apply(Selection) or apply(Transition); to dispatch events, use on(BrushEvent, DatumFunction).

Returns:

the current brush

extent

public final <T> Brush extent(double min,
               double max)

Set the current brush’s extent for a one-dimensional brush (defined by its x scale, or by its y scale, but not both).

When the extent is set to values, the resulting extent is preserved exactly. However, as soon as the brush is moved by the user (on mousemove following a mousedown), then the extent will be recomputed by calling ContinuousQuantitativeScale.invert(double). Note that, in this case, the values may be slightly imprecise due to the limited precision of pixels.

Note that this does not automatically redraw the brush or dispatch any events to listeners. To redraw the brush, call apply(Selection) or apply(Transition); to dispatch events, use event(Selection) or event(Transition).

Parameters:

min - the lowest value of the brush's extent

max - the highest value of the brush's extent

Returns:

the current brush

extent

public final <T> Brush extent(double x0,
               double y0,
               double x1,
               double y1)

Set the current brush’s extent for a two-dimensional brush (defined by both its x scale and its y scale.

When the extent is set to values, the resulting extent is preserved exactly. However, as soon as the brush is moved by the user (on mousemove following a mousedown), then the extent will be recomputed by calling ContinuousQuantitativeScale.invert(double). Note that, in this case, the values may be slightly imprecise due to the limited precision of pixels.

Note that this does not automatically redraw the brush or dispatch any events to listeners. To redraw the brush, call apply(Selection) or apply(Transition); to dispatch events, use event(Selection) or event(Transition).

Parameters:

x0 - the lowest value of the x scale

y0 - the lowest value of the y scale

x1 - the highest value of the x scale

y1 - the highest value of the y scale

Returns:

the current brush

on

public final Brush on(Brush.BrushEvent event,
       DatumFunction<Void> listener)

Set the listener for the specified event type.

Brushes support three types of events:

• Brush.BrushEvent.BRUSH_START - on mousedown
• Brush.BrushEvent.BRUSH - on mousemove, if the brush extent has changed
• Brush.BrushEvent.BRUSH_END - on mouseup

Note that when clicking on the background, a mousedown also triggers a "brush" event, since the brush extent is immediately cleared to start a new extent.

Parameters:

event - the event.

listener - the event listener.

Returns:

the current brush.

event

public final Brush event(Selection selection)

Dispatch a brush gesture to registered listeners as a three event sequence: Brush.BrushEvent.BRUSH_START, Brush.BrushEvent.BRUSH, and Brush.BrushEvent.BRUSH_END.

This can be useful in triggering listeners after setting the brush extent programatically. If selection is a transition, registers the appropriate tweens so that the brush dispatches events over the course of the transition: a brushstart event when the transition starts from the previously-set extent, brush events for each tick of the transition, and finally a brushend event when the transition ends. Note that the transition will be interrupted if the user starts brushing before the transition ends.

Parameters:

selection -

Returns:

event

public final IsFunction event()

Same as event(Selection) or event(Transition), but allows the use of EnteringSelection.call(IsFunction).

Returns:

a function object to pass to EnteringSelection.call(IsFunction)

event

public final Brush event(Transition transition)

Registers the appropriate tweens so that the brush dispatches events over the course of the transition: a Brush.BrushEvent.BRUSH_START event when the transition starts from the previously-set extent, Brush.BrushEvent.BRUSH events for each tick of the transition, and finally a Brush.BrushEvent.BRUSH_END event when the transition ends.

Note that the transition will be interrupted if the user starts brushing before the transition ends.

Parameters:

transition -

Returns:

the Brush

clear

public final Brush clear()

Clears the extent, making the brush extent empty().

Returns:

the current Brush

clamp

public final Brush clamp(boolean clamp)

Sets the current clamping behavior., for a brush where only one of the x-scale and y-scale are available.

Parameters:

clamp - true if the one-dimensional extent should be clamped to its scale

Returns:

the current brush

clamp

public final Brush clamp(boolean clampX,
          boolean clampY)

Sets the current clamping behavior, for a brush where both an x- and y-scale are available.

Parameters:

clampX - true if the x-extent should be clamped to its scale

clampY - true if the Y-extent should be clamped to its scale

Returns:

the current brush

clamp

public final Array<Boolean> clamp()

Gets the current clamping behavior.

The clamping behavior definition depends on the associated scales.
If both an x- and y-scale are available, then the clamping behavior is an array [ x, y ], where x and y are booleans that determine whether the each dimension of the two-dimensional extent should be clamped to its respective x- and y-scale. If only one of the x-scale and y-scale are available, then the clamping behavior is a boolean referring to whether the one-dimensional extent should be clamped to that scale. If neither scale is available, then the clamping behavior is null.

Returns:

the current brush

empty

public final boolean empty()

Returns true if and only if the brush extent is empty.

When a brush is created, it is initially empty; the brush may also become empty with a single click on the background without moving, or if the extent is clear()ed.

A brush is considered empty if it has zero-width or zero-height. When the brush is empty, its extent() is not strictly defined.

Returns:

true if the brush extent is empty.