SVG Controls - zziuni/d3 GitHub Wiki

Wiki ▸ API Reference ▸ SVG ▸ SVG Controls

# d3.svg.brush()

Constructs a new brush with no default x- and y-scale, and an empty extent.

# brush(selection)

Draws or redraws this brush into the specified selection of elements. The brush may be drawn into multiple elements simultaneously, but not that these brushes would share the same backing extent; typically, a brush is drawn into only one element at a time.

The selection can also be a transition; however, the brush does not yet support automatic transitions, so the redraw will happen instantaneously. In a subsequent release, the brush will smoothly transition to the new extent when redrawn after the extent is set.

# brush.x([scale])

Gets or sets the x-scale associated with the brush. If scale is specified, sets the x-scale to the specified scale and returns the brush; if scale is not specified, returns the current x-scale, which defaults to null. The scale is typically defined as a quantitative scale, in which case the extent is in data space from the scale's domain; however, it may instead be defined as an ordinal scale, where the extent is in pixel space from the scale's range extent.

# brush.y([scale])

Gets or sets the y-scale associated with the brush. If scale is specified, sets the y-scale to the specified scale and returns the brush; if scale is not specified, returns the current y-scale, which defaults to null. The scale is typically defined as a quantitative scale, in which case the extent is in data space from the scale's domain; however, it may instead be defined as an ordinal scale, where the extent is in pixel space from the scale's range extent.

# brush.extent([values])

Gets or sets the current brush extent. If values is specified, sets the extent to the specified values and returns the brush; if values is not specified, returns the current 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 ]. In 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 must be recomputed by calling scale.invert. Note that 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 brush on a selection or transition.

# brush.clear()

Clears the extent, making the brush extent empty.

# brush.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 cleared. A brush is considered empty if it has zero-width or zero-height. When the brush is empty, its extent is not strictly defined.

# brush.on(type[, listener])

Gets or sets the listener for the specified event type. Brushes support three types of events:

• brushstart - on mousedown
• brush - on mousemove, if the brush extent has changed
• brushend - on mouseup

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