SVG Controls

Wiki ▸ API Reference ▸ SVG ▸ SVG Controls

Brush

# 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 note 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, in which case the brush will perform an automatic transition. Use brush.event to dispatch brush events during the transition for animated brushing.

# 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]. 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 scale.invert. 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 brush on a selection or transition; to dispatch events, use brush.event.

# brush.clamp([clamp])

Gets or sets the current clamping behavior. If clamp is specified, sets the clamping behavior and returns the brush; if clamp is not specified, returns 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.

# 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 "brush" event, since the brush extent is immediately cleared to start a new extent.

# brush.event(selection)

If selection is a selection, it dispatches a brush gesture to registered listeners as a three event sequence: brushstart, brush and brushend. 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.