public class Transition
extends com.google.gwt.core.client.JavaScriptObject
Selection.transition() operator. While
transitions generally support the same operators as selections (such as
#attr(String) and #style(String)), not all operators are
supported; for example, you must #append(String) elements before a
transition starts. A remove() operator is provided for convenient
removal of elements when the transition ends.
Transitions may have per-element #delay and duration(DatumFunction),
computed using functions of data similar to other operators. This makes it
easy to stagger a transition for different elements, either based on data or
index. For example, you can sort elements and then stagger the transition for
better perception of element reordering during the transition. For more
details on these techniques, see
"Animated Transitions in Statistical Data Graphics" by Heer & Robertson.
D3 has many built-in interpolators to simplify the transitioning of arbitrary values. For instance, you can transition from the font string "500 12px sans-serif" to "300 42px sans-serif", and D3 will find the numbers embedded within the string, interpolating both font size and weight automatically. You can even interpolate arbitrary nested objects and arrays or SVG path data. D3 allows custom interpolators should you find the built-in ones insufficient, using the attrTween and styleTween operators. D3's interpolators provide the basis for scales and can be used outside of transitions; an interpolator is a function that maps a parametric value t in the domain [0,1] to a color, number or arbitrary value.
Only one transition may be active on a given element at a given time. However, multiple transitions may be scheduled on the same element; provided they are staggered in time, each transition will run in sequence. If a newer transition runs on a given element, it implicitly cancels any older transitions, including any that were scheduled but not yet run. This allows new transitions, such as those in response to a new user event, to supersede older transitions even if those older transitions are staged or have staggered delays. Multi-stage transitions (transitions that are created during the "end" event of an earlier transition) are considered the same "age" as the original transition; internally this is tracked by monotonically-increasing unique IDs which are inherited when multi-stage transitions are created.
For more on transitions, read the Working with Transitions tutorial.
| Modifier and Type | Class and Description |
|---|---|
static class |
Transition.EventType
Type of transition event.
|
| Modifier | Constructor and Description |
|---|---|
protected |
Transition() |
| Modifier and Type | Method and Description |
|---|---|
Transition |
attr(String name,
DatumFunction<?> callback)
Transitions the attribute with the specified name to the value returned
by the specified function on all selected elements.
|
Transition |
attr(String name,
double value)
See
attr(String, String). |
Transition |
attr(String name,
PathDataGenerator value)
Transitions the attribute with the specified name to the specified
PathDataGenerator value on all selected elements. |
<T> Transition |
attr(String name,
String value)
Transition the attribute with the specified name to the specified value
on all selected elements.
|
Transition |
attrTween(String name,
TweenFunction<?> tweenFunction)
Transitions the value of the attribute with the specified name according
to the specified tween function.
|
Transition |
call(IsFunction jsFunction)
Invokes the specified function once, passing in the current transition as
a single parameter.
|
Transition |
delay(DatumFunction<Integer> func)
Specifies the transition delay of each selected element.
|
Transition |
delay(int milliseconds)
Specifies the transition delay in milliseconds.
|
Transition |
duration(DatumFunction<Integer> func)
Specifies per-element duration in milliseconds of all elements, using the
given function.
|
Transition |
duration(int milliseconds)
Specifies transition duration in milliseconds of all elements.
|
Transition |
each(DatumFunction<Void> listener)
Behaves similarly to
Selection.each(DatumFunction): immediately
invokes the specified function for each element in the current
transition, passing in the current datum d and index i, with the this
context of the current DOM element. |
Transition |
each(Transition.EventType type,
DatumFunction<Void> listener)
Adds a listener for transition events.
|
Transition |
ease(EasingFunction callback)
Specifies the transition
EasingFunction to be used. |
boolean |
empty()
Returns true if the current transition is empty; a transition is empty if
it contains no non-null elements.
|
Transition |
filter(DatumFunction<com.google.gwt.dom.client.Element> datumFunction)
Filters the transition, returning a new transition that contains only the
elements for which the specified selector is true.
|
Transition |
filter(String selector)
Filters the transition, returning a new transition that contains only the
elements for which the specified selector is true.
|
com.google.gwt.dom.client.Element |
node()
Returns the first non-null element in the current transition.
|
Transition |
remove()
Remove the selected elements at the end of a transition.
|
Transition |
select(String selector)
For each element in the current selection, selects the first descendant
element that matches the specified selector string.
|
Transition |
selectAll(String selector)
For each element in the current transition, selects descendant elements
that match the specified selector string.
|
int |
size() |
Transition |
style(String name,
DatumFunction<?> callback)
See
Transition#style(String, T, boolean). |
Selection |
style(String name,
DatumFunction<?> callback,
boolean important)
Transitions the value of the CSS style property with the specified name
to the specified value.
|
Transition |
style(String name,
double value)
See
Transition#style(String, T, boolean). |
Transition |
style(String name,
String value)
Transitions the value of the CSS style property with the specified name
to the specified value.
|
Selection |
styleTween(String name,
TweenFunction<?> tweenFunction,
boolean important)
Transitions the value of the CSS style property with the specified name
according to the specified tween function.
|
Transition |
text(DatumFunction<String> callback)
The text operator is based on the textContent property; setting the text
content will replace any existing child elements.
|
<T> Transition |
text(String value)
The text operator is based on the textContent property; setting the text
content will replace any existing child elements.
|
Transition |
transition()
Creates a new transition on the same selected elements that starts with
this transition ends.
|
Transition |
tween(String name,
DatumFunction<Interpolator<?>> factory)
Registers a custom tween for the specified name.
|
public final Transition delay(int milliseconds)
All elements are given the same delay. The default delay is 0.
){kind=link}
milliseconds - the transition duration in millisecondspublic final Transition delay(DatumFunction<Integer> func)
The 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 set each element's delay. The default delay is 0.
Setting the delay to be a multiple of the index i is a convenient way to stagger transitions for elements. For example, if you used a fixed duration of duration, and have n elements in the current selection, you can stagger the transition over 2 * duration by saying:
.delay(function(d, i) { return i / n * duration; })
You may also compute the delay as a function of the data, thereby creating a data-driven animation.
milliseconds - the transition duration in millisecondspublic final Transition duration(int milliseconds)
milliseconds - the transition duration in millisecondspublic final Transition duration(DatumFunction<Integer> func)
func - the function returning a transition duration in millisecondspublic final Transition ease(EasingFunction callback)
EasingFunction to be used.
Built-in easing functions can be created using Easing factory or
you may provide a custom implementation.
Note that it is not possible to customize the easing function per-element
or per-attribute; however, if you use the "linear" easing function, you
can apply custom easing inside your interpolator using
attrTween(String, TweenFunction) or #styleTween()
callback - the easing functionpublic final <T> Transition attr(String name, String value)
The starting value of the transition is the current attribute value, and the ending value is the specified value.
A check is performed to see if the ending value represents a color of the
form /^(#|rgb\(|hsl\()/, or one of the CSS named colors; if so, the
starting value is coerced to an RGB color and
D3#interpolateRgb(Color, Color) is used. Otherwise,
interpolateString is used, which interpolates numbers embedded within
strings.
null values are not supported because the interpolator would be undefined; if you want to remove the attribute after the transition finishes, listen to the end event.
name - the name of the attributevalue - the new value to transition to, must not be nullpublic final Transition attr(String name, double value)
attr(String, String).
The startValue will be coerced to a number and interpolateNumber will be used to transition the attribute value.
name - value - public final Transition attr(String name, DatumFunction<?> callback)
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.
Null values are not supported because the interpolator would be undefined; if you want to remove the attribute after the transition finishes, listen to the end event.
An interpolator is selected automatically based on the ending value. If the ending value is a number, the starting value is coerced to a number and interpolateNumber is used. If the ending value is a string, a check is performed to see if the string represents a color of the form /^(#|rgb\(|hsl\()/, or one of the CSS named colors; if so, the starting value is coerced to an RGB color and interpolateRgb is used. Otherwise, interpolateString is used, which interpolates numbers embedded within strings.
name - the name of the attributecallback - the function used to compute the new value of the attributepublic final Transition attr(String name, PathDataGenerator value)
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.
name - the name of the attributevalue - the new value to assignpublic final Transition attrTween(String name, TweenFunction<?> tweenFunction)
The starting and ending value of the transition are determined by tweenFunction; the tween function is invoked when the transition starts on each element, being passed the current DOM element, the datum d, the current index i and the current attribute value a.
The return value of tween must be an interpolator: a function that maps a parametric value t in the domain [0,1] to a color, number or arbitrary value.
name - the name of the attribute to transitiontweenFunction - the function used to create an interpolatorpublic final Transition style(String name, String value)
The starting value of the transition is the current computed style property value, and the ending value is the specified value.
All elements are transitioned to the same style property value; Null values are not supported because the interpolator would be undefined; if you want to remove the style property after the transition finishes, listen to the end event. An interpolator is selected automatically based on the ending value. If the ending value is a number, the starting value is coerced to a number and interpolateNumber is used. If the ending value is a string, a check is performed to see if the string represents a color of the form /^(#|rgb\(|hsl\()/, or one of the CSS named colors; if so, the starting value is coerced to an RGB color and interpolateRgb is used. Otherwise, interpolateString is used, which interpolates numbers embedded within strings. Note that the computed starting 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.). Moreover, computed dimensions such as "font-size" and "line-height" are always in pixels, so you should specify the ending value in pixels too if appropriate.
name - the name of the style, such as font-sizevalue - the ending valuepublic final Transition style(String name, double value)
Transition#style(String, T, boolean).name - the name of the style, such as font-sizevalue - the ending valuepublic final Transition style(String name, DatumFunction<?> callback)
Transition#style(String, T, boolean).name - the name of the style, such as font-sizecallback - the callback to be calledpublic final Selection style(String name, DatumFunction<?> callback, boolean important)
The starting value of the transition is the current computed style property value, and the ending value is the specified value.
The 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 transition each element's style property. Null values are not supported because the interpolator would be undefined; if you want to remove the style property after the transition finishes, listen to the end event.
An interpolator is selected automatically based on the ending value. If the ending value is a number, the starting value is coerced to a number and interpolateNumber is used. If the ending value is a string, a check is performed to see if the string represents a color of the form /^(#|rgb\(|hsl\()/, or one of the CSS named colors; if so, the starting value is coerced to an RGB color and interpolateRgb is used. Otherwise, interpolateString is used, which interpolates numbers embedded within strings.
Note that the computed starting 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.). Moreover, computed dimensions such as "font-size" and "line-height" are always in pixels, so you should specify the ending value in pixels too if appropriate.
name - the name of the style to setcallback - the function to be called on each element and returning the
value of the styleimportant - true if the style value should be marked as !important, false
otherwisepublic final Selection styleTween(String name, TweenFunction<?> tweenFunction, boolean important)
The starting and ending value of the transition are determined by tweenFunction; the tween function is invoked when the transition starts on each element, being passed the current DOM element, the datum d, the current index i and the current attribute value a.
The return value of tween must be an interpolator: a function that maps a parametric value t in the domain [0,1] to a color, number or arbitrary value.
name - the name of the style to settweenFunction - the function to be called on each element and returning the
value of the styleimportant - true if the style value should be marked as !important, false
otherwisepublic final <T> Transition text(String value)
Set the text content to the specified value on all selected elements when the transition starts. All elements are given the same text content; a null value will clear the content.
value - the new text value to setpublic final Transition text(DatumFunction<String> callback)
The 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 set each element's text content.
A null value will clear the content.
callback - the function used to compute the new text propertypublic final Transition tween(String name, DatumFunction<Interpolator<?>> factory)
When the transition starts, the specified factory function will be invoked for each selected element in the transition, so as to compute the tween function. If the factory returns null, then the tween is not run on the selected element.
This method is used internally by the attr and style tweens, and can be used to interpolate other document content.
name - the name of the property to registerfactory - the function returning an Interpolatorpublic final Transition remove()
If a newer transition is scheduled on any of the selected elements, these elements will not be removed; however, the "end" event will still be dispatched.
public final Transition select(String selector)
If no element matches the specified selector for the current element, the
element at the current index will be null in the returned transition;
operators (with the exception of Selection.data()) automatically
skip null elements, thereby preserving the index of the existing
selection.
If the current element has associated data, this data is inherited by the returned subselection, and automatically bound to the newly selected elements.
If multiple elements match the selector, only the first matching element in document traversal order will be selected.
In addition, the returned new transition inherits easing, duration and delay from the current transition.
selector - the selectorpublic final Transition selectAll(String selector)
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 data was previously bound to the selected elements, that data will be available to operators.
In addition, the returned new transition inherits easing, duration and delay from the current transition. The duration and delay for each subelement is inherited from the duration and delay of the parent element in the current transition.
selector - public final Transition filter(String selector)
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.
If you want to preserve the index, use select instead.
selector - the CSS3 selector to be used as a filterpublic final Transition filter(DatumFunction<com.google.gwt.dom.client.Element> datumFunction)
As with other operators, the function is passed the current datum d and index i, with the this context as the current DOM 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. If you want to preserve the index, use select instead.
datumFunction - the function to be used as a filterpublic final Transition transition()
public final boolean empty()
public final com.google.gwt.dom.client.Element node()
public final int size()
public final Transition each(Transition.EventType type, DatumFunction<Void> listener)
The start event is invoked during the first asynchronous callback (tick) of the transition, before any tweens are invoked. For transitions with zero delay, this is typically about 17ms after the transition is scheduled. State events are useful for triggering instantaneous changes to each element, such as changing attributes that cannot be interpolated.
The end event is invoked during the last asynchronous callback (tick) after the transition duration and delay expires, after all tweens are invoked with t=1. Note that if the transition is superseded by a later-scheduled transition on a given element, no end event will be dispatched for that element; interrupted transitions do not trigger end events. For example, transition.remove schedules each element to be removed when the transition ends, but if the transition is interrupted, the element will not be removed. End events can be used as an alternative to transition.transition to create chained transitions by selecting the current element, this, and deriving a new transition.
Any transitions created during the end event will inherit the current transition parameters, including ID, time, easing, delay and duration. Thus, new transitions created within a parent transition.each will not the parent transition, similar to subtransitions.
type - the type of eventlistener - the listenerpublic final Transition each(DatumFunction<Void> listener)
Selection.each(DatumFunction): immediately
invokes the specified function for each element in the current
transition, passing in the current datum d and index i, with the this
context of the current DOM element.
Any transitions created during the end event will inherit the current transition parameters, including ID, time, easing, delay and duration.
Thus, new transitions created within a parent transition.each will not the parent transition, similar to subtransitions. The transition.each method can be used to chain transitions and apply shared timing across a set of transitions.
listener - public final Transition call(IsFunction jsFunction)
jsFunction - Copyright © 2015 gwt-d3. All rights reserved.