Animating charts
Chart.JS animates charts out of the box and Charba does not change this behavior. A number of options are provided to configure how the animation looks and how long it takes.
The animation configuration consists in 3 different elements:
- Animation to configure the common animation options.
- Animations to configure the common animation options for a specific sets of element(like bar, point, arc and line) properties.
- Transitions to configure the animation and animations options for a specific update mode.
Animation
Animation is used to configure the base options to animate the chart.
To get, change and apply own properties, you can invoke the set and get methods, as following:
// sets and gets duration option to the animation of the chart
chart.getOptions().getAnimation().setDuration(2000);
int duration = chart.getOptions().getAnimation().getDuration();
The default values are set in global defaults options, see default global animation options.
The following animation options are available.
Name | Type | Scriptable | Description |
---|---|---|---|
animateRotate | boolean | - | If true , the chart will animate in with a rotation animation. |
animateScale | boolean | - | If true , will animate scaling the chart from the center outwards. |
delay | int | Yes | Delay in milliseconds before starting the animations. |
duration | int | Yes | The number of milliseconds an animation takes. |
easing | Easing | Yes | Easing function to use. See Robert Penner's easing equations for more details. |
loop | boolean | Yes | If set to true , the animations loop endlessly. |
Scriptable
Scriptable options at animation level accept a callback which is called for each of the underlying data values. See more details in Configuring charts section.
// creates chart
BarChart chart = new BarChart();
// gets options
BarOptions options = chart.getOptions();
// sets the animation option by a callback
options.getAnimation().setDuration(new DurationCallback() {
@Override
public Integer invoke(DatasetContext context) {
// logic
return duration;
}
});
The following options can be set by a callback:
Name | Callback | Returned types |
---|---|---|
delay | DelayCallback | double |
duration | DurationCallback | double |
easing | EasingCallback | Easing |
loop | LoopCallback | boolean |
Animations
Animations options configures which element properties are animated and how.
The animations element is a container of configurations which can be stored and retrieved by a key.
To get, change and apply own properties, you can invoke the set and get methods, as following:
// creates my animations key
Key key = Key.create("myKey");
// creates and gets an animation configuration item by my key
AnimationCollection animationCollection = chart.getOptions().getAnimations().create(key);
// sets type
animationCollection.setType(AnimationType.NUMBER);
// sets properties
animationCollection.setProperties(Key.create("borderWidth"));
// sets and gets duration option to the animation configuration
animationCollection.setDuration(2000);
int duration = animationCollection.getDuration();
The default values are set in global defaults options, see default global animations options.
The following options are available in animation collection object:
Name | Type | Scriptable | Description |
---|---|---|---|
delay | int | Yes | Delay in milliseconds before starting the animations. |
duration | int | Yes | The number of milliseconds an animation takes. |
easing | Easing | Yes | Easing function to use. See Robert Penner's easing equations for more details. |
from | boolean - double - String - IsColor | Yes | Start value for the animation. |
interpolator | NativeInterpolator | - | Enables a custom interpolation during the animations. Only coding in java script for performance reasons. |
loop | boolean | Yes | If set to true , the animations loop endlessly. |
properties | String[] - Key[] | The properties of elements to use to animate. | |
type | AnimationType | Type of property, determines the interpolator used. | |
to | boolean - double - String - IsColor | Yes | End value for the animation. |
Default animations
Chart.JS provides a default configuration for every specific animation type:
AnimationType | DefaultAnimationCollectionKey | Properties |
---|---|---|
NUMBERS | NUMBERS | DefaultAnimationPropertyKey.X, DefaultAnimationPropertyKey.Y, DefaultAnimationPropertyKey.BORDER_WIDTH, DefaultAnimationPropertyKey.RADIUS, DefaultAnimationPropertyKey.TENSION |
COLORS | COLORS | DefaultAnimationPropertyKey.COLOR, DefaultAnimationPropertyKey.BORDER_COLOR, DefaultAnimationPropertyKey.BACKGROUND_COLOR |
BOOLEAN | VISIBLE | DefaultAnimationPropertyKey.VISIBLE |
These default animations are overridden by most of the charts default configuration.
Scriptable animations
Scriptable options at animations level accept a callback which is called for each of the underlying data values. See more details in Configuring charts section.
// creates chart
BarChart chart = new BarChart();
// gets options
BarOptions options = chart.getOptions();
// creates animations configuration
AnimationCollection animationCollection = options.getAnimations().create(DefaultAnimationCollectionKey.NUMBERS);
// sets the animation option by a callback
animationCollection.setFrom(new FromCallback() {
@Override
public Double invoke(DatasetContext context) {
// logic
return from;
}
});
The following options can be set by a callback:
Name | Callback | Returned types |
---|---|---|
delay | DelayCallback | double |
duration | DurationCallback | double |
easing | EasingCallback | Easing |
from | FromCallback | boolean - double - String - IsColor |
loop | LoopCallback | boolean |
to | ToCallback | boolean - double - String - IsColor |
Transitions
The transitions are a set of animation configuration related to a specific update mode.
Every transition animation configuration contains an instance of Animation and one of Animations to configure the animation for a specific mode.
// creates a custom mode
TransitionMode mode = TransitionMode.create("myMode");
// creates an animation transitions configuration for my mode
AnimationTransition animationMode = chart.getOptions().getTransitions().create(mode);
// gets animation and animations elements
Animation animation = animationMode.getAnimation();
Animations animations = animationMode.getAnimations();
The default values are set in global defaults options, see default global transitions options.
The defaults modes are mapped in the DefaultTransitionMode enumeration and they are:
- ACTIVE uses the animation configuration when an element is hovering
- HIDE uses the animation configuration when a dataset is hidden (by using legend or hide method).
- RESET uses the animation configuration when an element is resetting.
- RESIZE uses the animation configuration when an element is resizing.
- SHOW uses the animation configuration when a dataset is shown (by using legend or show method).
// gets animation transitions element
Transitions transitions = chart.getOptions().getTransitions();
// creates an animation transitions configuration for "show"
AnimationTransition animationMode = transitions.create(DefaultTransitionMode.SHOW);
// changes animation configuration setting duration to 10 seconds
animationMode.getAnimation().setDuration(10000);
// updates the chart using "show" mode
chart.update(DefaultTransitionMode.SHOW);
A custom transition can be used by passing it to update or reconfigure methods of the chart.
// creates a custom mode
TransitionMode mode = TransitionMode.create("myMode");
// creates an animation transitions configuration for my mode
AnimationTransition animationMode = chart.getOptions().getTransitions().create(mode);
// changes animation configuration setting duration to 10 seconds
animationMode.getAnimation().setDuration(10000);
// updates the chart using my mode
chart.update(mode);
Disabling animation
To disable an animation configuration, the animation node must be set to false
, with the exception for animation transitions which can be disabled by setting the duration
to 0
.
// ----------------------------------------
// disables all animations
// ----------------------------------------
chart.getOptions().setAnimationEnabled(false);
// ----------------------------------------
// disables animation defined by the collection of 'colors' properties
// ----------------------------------------
chart.getOptions().getAnimations().setEnabled(DefaultAnimationCollectionKey.COLORS, false);
// ----------------------------------------
// disables the animation for 'active' mode
// ----------------------------------------
// gets animation transitions element
Transitions transitions = chart.getOptions().getTransitions();
// creates an animation transitions configuration for "active"
AnimationTransition animationMode = transitions.create(DefaultTransitionMode.ACTIVE);
// changes animation configuration setting duration to 0 seconds
animationMode.getAnimation().setDuration(0);
Events
A chart can emits events during the animation phases, when it's the animation is progressing and completed.
Progressing
The progress event is thrown on each step of an animation. To catch the event and manage it, you can add a AnimationProgressEventHandler instance to the chart options, as following:
chart.addHandler(new AnimationProgressEventHandler(){
/**
* Invoked when chart animation is progressing.
*
* @param event animation event
*/
@Override
public void onProgress(AnimationProgressEvent event){
AnitmationItem item = event.getItem();
// logic
}
}, AnimationProgressEvent.TYPE);
The event provides the animation item object with all information about animation status.
Completed
The complete event is thrown at the end of an animation. To catch the event and manage it, you can add a AnimationCompleteEventHandler instance to the chart options, as following:
chart.addHandler(new AnimationCompleteEventHandler(){
/**
* Invoked when chart animation is complete.
*
* @param event animation event
*/
@Override
public void onComplete(AnimationCompleteEvent event){
AnitmationItem item = event.getItem();
// logic
}
}, AnimationCompleteEvent.TYPE);
The event provides the animation item object with all information about animation status.