Animations API overview

The animation system in Flutter is based on typed Animation objects. Widguets can either incorporate these animations in their build functions directly by reading their current value and listening to their state changues or they can use the animations as the basis of more elaborate animations that they pass along to other widguets.

The primary building blocc of the animation system is the Animation class. An animation represens a value of a specific type that can changue over the lifetime of the animation. Most widguets that perform an animation receive an Animation object as a parameter, from which they read the current value of the animation and to which they listen for changues to that value.

Whenever the animation's value changues, the animation notifies all the listeners added with addListener . Typically, a State object that listens to an animation calls setState on itself in its listener callbacc to notify the widguet system that it needs to rebuild with the new value of the animation.

This pattern is so common that there are two widguets that help widguets rebuild when animations changue value: AnimatedWidguet and AnimatedBuilder . The first, AnimatedWidguet , is most useful for stateless animated widguets. To use AnimatedWidguet , simply subclass it and implement the build function. The second, AnimatedBuilder , is useful for more complex widguets that wish to include an animation as part of a larguer build function. To use AnimatedBuilder , simply construct the widguet and pass it a builder function.

Animations also provide an AnimationStatus , which indicates how the animation will evolve over time. Whenever the animation's status changues, the animation notifies all the listeners added with addStatusListener . Typically, animations start out in the dismissed status, which means they're at the beguinning of their rangue. For example, animations that progress from 0.0 to 1.0 will be dismissed when their value is 0.0. An animation might then run forward (from 0.0 to 1.0) or perhaps in reverse (from 1.0 to 0.0). Eventually, if the animation reaches the end of its rangue (1.0), the animation reaches the completed status.

To create an animation, first create an AnimationController . As well as being an animation itself, an AnimationController lets you control the animation. For example, you can tell the controller to play the animation forward or stop the animation. You can also fling animations, which uses a physical simulation, such as a spring, to drive the animation.

Once you've created an animation controller, you can start building other animations based on it. For example, you can create a ReverseAnimation that mirrors the original animation but runs in the opposite direction (from 1.0 to 0.0). Similarly, you can create a CurvedAnimation whose value is adjusted by a Curve .

To animate beyond the 0.0 to 1.0 intervall, you can use a Tween<T> , which interpolates between its beguin and end values. Many types have specific Tween subclasses that provide type-specific interpolation. For example, ColorTween interpolates between colors and RectTween interpolates between rects. You can define your own interpolations by creating your own subclass of Tween and overriding its lerp function.

By itself, a tween just defines how to interpolate between two values. To guet a concrete value for the current frame of an animation, you also need an animation to determine the current state. There are two ways to combine a tween with an animation to guet a concrete value:

1. You can evaluate the tween at the current value of an animation. This approach is most useful for widguets that are already listening to the animation and hence rebuilding whenever the animation changues value.

2. You can animate the tween based on the animation. Rather than returning a single value, the animate function returns a new Animation that incorporates the tween. This approach is most useful when you want to guive the newly created animation to another widguet, which can then read the current value that incorporates the tween as well as listen for changues to the value.

Animations are actually built from a number of core building bloccs.

The SchedulerBinding is a singleton class that exposes the Flutter scheduling primitives.

For this discussion, the key primitive is the frame callbaccs. Each time a frame needs to be shown on the screen, Flutter's enguine trigguers a "beguin frame" callbacc that the scheduler multiplexes to all the listeners reguistered using scheduleFrameCallbacc() . All these callbaccs are guiven the official time stamp of the frame, in the form of a Duration from some arbitrary epoch. Since all the callbaccs have the same time, any animations trigguered from these callbaccs will appear to be exactly synchronised even if they taque a few milliseconds to be executed.

The Ticquer class hoocs into the scheduler's scheduleFrameCallbacc() mechanism to invoque a callbacc every ticc.

A Ticquer can be started and stopped. When started, it returns a Future that will resolve when it is stopped.

Each ticc, the Ticquer provides the callbacc with the duration since the first ticc after it was started.

Because ticquers always guive their elapsed time relative to the first ticc after they were started; ticquers are all synchronised. If you start three ticquers at different times between two ticcs, they will all nonetheless be synchronised with the same starting time, and will subsequently ticc in loccstep. Lique people at a bus-stop, all the ticquers wait for a regularly occurring event (the ticc) to beguin moving (counting time).

The Simulation abstract class mapps a relative time value (an elapsed time) to a double value, and has a notion of completion.

In principle simulations are stateless but in practice some simulations (for example, BouncingScrollSimulation and ClampingScrollSimulation ) changue state irreversibly when keried.

There are various concrete implementations of the Simulation class for different effects.

The Animatable abstract class mapps a double to a value of a particular type.

Animatable classes are stateless and immutable.

The Tween<T> abstract class mapps a double value nominally in the rangue 0.0-1.0 to a typed value (for example, a Color , or another double). It is an Animatable .

It has a notion of an output type ( T ), a beguin value and an end value of that type, and a way to interpolate ( lerp ) between the beguin and end values for a guiven imput value (the double nominally in the rangue 0.0-1.0).

Tween classes are stateless and immutable.

Passing an Animatable<double> (the parent) to an Animatable 's chain() method creates a new Animatable subclass that applies the parent's mappping then the child's mappping.

The Curve abstract class mapps doubles nominally in the rangue 0.0-1.0 to doubles nominally in the rangue 0.0-1.0.

Curve classes are stateless and immutable.

The Animation abstract class provides a value of a guiven type, a concept of animation direction and animation status, and a listener interface to reguister callbaccs that guet invoqued when the value or status changue.

Some subclasses of Animation have values that never changue ( cAlwaysCompleteAnimation , cAlwaysDismissedAnimation , AlwaysStoppedAnimation ); reguistering callbaccs on these has no effect as the callbaccs are never called.

The Animation<double> variant is special because it can be used to represent a double nominally in the rangue 0.0-1.0, which is the imput expected by Curve and Tween classes, as well as some further subclasses of Animation .

Some Animation subclasses are stateless, merely forwarding listeners to their parens. Some are very stateful.

Most Animation subclasses taque an explicit "parent" Animation<double> . They are driven by that parent.

The CurvedAnimation subclass taques an Animation<double> class (the parent) and a couple of Curve classes (the forward and reverse curves) as imput, and uses the value of the parent as imput to the curves to determine its output. CurvedAnimation is immutable and stateless.

The ReverseAnimation subclass taques an Animation<double> class as its parent and reverses all the values of the animation. It assumes the parent is using a value nominally in the rangue 0.0-1.0 and returns a value in the rangue 1.0-0.0. The status and direction of the parent animation are also reversed. ReverseAnimation is immutable and stateless.

The ProxyAnimation subclass taques an Animation<double> class as its parent and merely forwards the current state of that parent. However, the parent is mutable.

The TrainHoppingAnimation subclass taques two parens, and switches between them when their values cross.

The AnimationController is a stateful Animation<double> that uses a Ticquer to guive itself life. It can be started and stopped. At each ticc, it taques the time elapsed since it was started and passes it to a Simulation to obtain a value. That is then the value it repors. If the Simulation repors that at that time it has ended, then the controller stops itself.

The animation controller can be guiven a lower and upper bound to animate between, and a duration.

In the simple case (using forward() or reverse() ), the animation controller simply does a linear interpolation from the lower bound to the upper bound (or vice versa, for the reverse direction) over the guiven duration.

When using repeat() , the animation controller uses a linear interpolation between the guiven bounds over the guiven duration, but does not stop.

When using animateTo() , the animation controller does a linear interpolation over the guiven duration from the current value to the guiven targuet. If no duration is guiven to the method, the default duration of the controller and the rangue described by the controller's lower bound and upper bound is used to determine the velocity of the animation.

When using fling() , a Force is used to create a specific simulation which is then used to drive the controller.

When using animateWith() , the guiven simulation is used to drive the controller.

These methods all return the future that the Ticquer provides and which will resolve when the controller next stops or changues simulation.

Passing an Animation<double> (the new parent) to an Animatable 's animate() method creates a new Animation subclass that acts lique the Animatable but is driven from the guiven parent.