Animation

How are animations scheduled?

• Window.onBeginFrame invokes SchedulerBinding.handleBeginFrame every frame, which runs all transient callbacks scheduled during the prior frame. Ticker instances utilize transient callbacks (via SchedulerBinding.scheduleFrameCallback), and are therefore evaluated at this point. All tickers update their measure of elapsed time using the same frame timestamp, ensuring that tickers tick in unison.

• AnimationController utilizes an associated Ticker to track the passage of time. When the ticker ticks, the elapsed time is provided to an internal simulation which transforms real time into a decimal value. The simulation (typically _InterpolationSimulation) interpolates between AnimationController.lowerBound and AnimationController.upperBound (if spanning the animation’s full range), or AnimationController.value and AnimationController.target (if traversing from the current value to a new one), applying a curve if available. Listeners are notified once the simulation produces a new value.

• The animation’s behavior (playing forward, playing backward, animating toward a target, etc) is a consequence of how this internal simulation is configured (i.e., by reversing the bounds, by altering the duration, by using a _RepeatingSimulation or SpringSimulation). Typically, the simulation is responsible for mapping from real time to a value representing animation progress.

  • In the general case, an _InterpolationSimulation is configured in AnimationController._animateToInternal.

  • Next, the controller’s ticker is started, which advances the the simulation once per frame. The simulation is advanced using the elapsed time reported by the ticker.

  • Listeners are notified whenever the simulation is queried or reaches an endpoint, potentially changing the animation’s status (AnimationStatus).

• Composing animations (e.g., via _AnimatedEvaluation or _ChainedEvaluation) works by proxying the underlying listenable (i.e., by delegating listener operations to the parent animation, which advances as described above).

What is an animation?

• An animation, as represented by Animation<double>, traverses from zero to one (and vice versa) over a user-defined interval (this is typically facilitated by an AnimationController, a special Animation<double> that advances in real time). The resulting value represents the animation’s progress (i.e., a timing value) and is often fed into a chain of animatables or descendant animations. These are re-evaluated every time the animation advances and therefore notifies its listeners. Some descendants (e.g., curves) transform the animation’s timing value into a new timing value; these affect the animation’s rate of change (e.g., easing) but not its duration. Others produce derived values that can be used to update the UI (e.g., colors, shapes, and sizes). Repeatedly updating the UI using these values is the basis of animation.

What are the animation building blocks?

• Animation<T> couples Listenable with AnimationStatus and produces a sequence of values with a beginning and an end. The animation’s status is derived from the sequence’s directionality and whether values are currently being produced. In particular, the animation can be stopped at the sequence’s beginning or end (AnimationStatus.dimissed, AnimationStatus.completed), or actively producing values in a particular order (AnimationStatus.forward, AnimationStatus.reverse). Animation<T> extends ValueListenable which produces a sequence of values but does not track status.

  • Animation<double> is the most common specialization of Animation<T> (and the only specialization that can be used with Animatable<T>); as a convention, Animation<double> produces values from zero to one, though it may overshoot this range before completing. These values are typically interpreted as the animation’s progress (referred to as timing values, below). How this interval is traversed over time determines the behavior of any downstream animatables.

  • Animation<double> may represent other sequences, as well. For instances, an Animation<double> might describe a sequence of border radii or line thicknesses.

  • More broadly, Animation<T>, where T is not a timing value, is devoid of conventional significance. Such animations progress through their values as described earlier, and are typically driven by a preceding Animation<double> (that does represent a timing value).

• Animatable<T> describes an animatable value, mapping an Animation<double> (which ranges from zero to one) to a sequence of derived values (via Animatable<T>.evaluate, which forwards the animation’s value to Animatable<T>.transform to produce a new value of type T). The animatable may be driven by an animation (i.e., repeatedly evaluated as the animation generates notifications, via Animatable<T>.animate). It may also be associated with a parent animatable to create an evaluation chain (i.e., the parent evaluates the animation value, then the child evaluates the parent’s value, via Animatable<T>.chain). Unless the parent animatable is driven by an animation, however, chaining will not cause the animatable to animate; it only describes a sequence of transformations.

  • Animatable<T>.evaluate always maps from a double to a value of type T. Conventionally, the provided double represents a timing value (ranging from zero to one), but this is not a requirement.

• Tween is a subclass of Animatable<T> that linearly interpolates between beginning and end values of type T (via Tween.lerp). By default, algebraic linear interpolation is used, though many types implement custom methods (via T.lerp) or provide overloaded operators.

  • TweenSequence is an animatable that allows an animation to drive a sequence of tweens, associating each with a portion of the animation’s duration (via TweenSequenceItem.weight).

• Simulation models an object in one-dimensional space with a position (Simulation.x), velocity (Simulation.dx), and completion status (isDone) using logical units. Simulations are queried using a time value, also in logical units; as some simulations may be stateful, queries should generally use increasing values. A Tolerance instance specifies epsilon values for time, velocity, and position to determine when the simulation has settled.

• AnimationController is an Animation<double> subclass introducing explicit control and frame-synchronized timing. When active, the animation controller is driven at approximately 60 Hz. This is facilitated by a corresponding Ticker instance, a synchronized timer that triggers at the beginning of each frame; this instance may change over the course of the controller’s lifespan (via AnimationController.resync). The animation can be run backwards and forwards (potentially without bounds), toward and away from target values (via AnimationController.animateTo and AnimationController.animateBack), or cyclically (via AnimationController.repeat). Animations can also be driven by a custom Simulation (via AnimationController.animateWith) or a built-in spring simulation (via AnimationController.fling). The controller’s value (AnimationController.value) is advanced in real time, using a duration (AnimationController.duration) to interpolate between starting and ending values (AnimationController.upperBound, AnimationController.lowerBound), both doubles. An immutable view of the animation is also exposed (AnimationController.view).

• Ticker invokes a callback once per frame (via a transient callback scheduled using SchedulerBinding.scheduleFrameCallback), passing a duration corresponding to how long the ticker has been ticking. This duration is measured using a timestamp set at the beginning of the frame (SchedulerBinding.handleBeginFrame). All tickers advance using the same timestamp and are therefore synchronized. When a ticker is enabled, a transient frame callback is registered via SchedulerBinding.addFrameCallback; this schedules a frame via Window.scheduleFrame, ensuring that the ticker will begin ticking.

  • Tickers measure a duration from when they first tick. If a ticker is stopped, the duration is reset and progress is lost. Muting a ticker allows time (the duration) to continue advancing while suppressing ticker callbacks. The animation will not progress while muted and will appear to jump ahead when unmuted. A ticker can absorb another ticker so that animation progress is not lost; that is, the new ticker will retain the old ticker’s elapsed time.

  • TickerFuture exposes the ticker status as a Future. When stopped, this future resolves; in all other cases, the future is unresolved. A derivative future, TickerFuture.orCancel, extends this interface to throw an exception if the ticker is cancelled.

• TickerProvider vends Ticker instances. TickerProviderStateMixin and SingleTickerProviderStateMixin fulfill the TickerProvider interface within the context of a State object (the latter has less overhead since it only tracks a single ticker). These mixins query an inherited TickerMode that can enable and disable all descendent tickers en masse; this allows tickers to be muted and unmuted within a subset of the widget tree efficiently.

• AnimationLocalListenersMixin and AnimationLocalStatusListenersMixin provide implementations for the two listenable interfaces supported by animations: value listeners (Animation.addListener, Animation.removeListener), and status listeners (Animation.addStatusListener, Animation.removeStatusListener). Both store listeners in a local ObserverList and support hooks indicating when a listener is registered and unregistered (didRegisterListener and didUnregisterListener, respectively). A number of framework subclasses depend on these mixins (e.g., AnimationController) since Animation<T> doesn’t provide a concrete implementation.

  • AnimationLazyListenerMixin uses the aforementioned hooks to notify the client when there are no more listeners. This allows resources to be released until a listener is once again added (via AnimationLazyListenerMixin.didStartListening and AnimationLazyListenerMixin.didStopListening).

  • AnimationEagerListenerMixin ignores these hooks, instead introducing a dispose protocol; resources will be retained through the animation’s lifespan and therefore must be disposed before the instance is released.

How are animations curved?

• Curve determines an animation’s rate of change by specifying a mapping from input to output timing values (i.e., from [0, 1] to [0, 1], though some curves stretch this interval, e.g., ElasticInCurve). Animation<double> produces suitable input values that may then be transformed (via Curve.transform) into new timing values. Later, these values may be used to drive downstream animatables (or further transformed), effectively altering the animation’s perceived rate of change.

  • Geometrically, a curve may be visualized as mapping an input timing value (along the X-axis) to an output timing value (along the Y-axis), with zero corresponding to AnimationStatus.dismissed and one corresponding to AnimationStatus.completed.

  • Curves cannot alter the overall duration of an animation, but will affect the rate that an animation is advanced during that interval. Additionally, even if they overshoot the unit interval, curves must map zero and one to values that round to zero or one, respectively.

  • There are a number of built-in curve instances:

    • Cubic defines a curve as a cubic function.

    • ElasticInCurve, ElasticOutCurve, ElasticInOutCurve define a spring-like curve that overshoots as it grows, shrinks, or settles, respectively.

    • Interval maps a curve to a subinterval, clamping to 0 or 1 at either end.

    • Threshold is 0 until a threshold is reached, then 1 thereafter.

    • SawTooth produces N linear intervals, with no interpolation at edges

    • FlippedCurve transforms an input curve, mirroring it both horizontally and vertically.

    • Curves exposes a large number of pre-defined curves.

• CurvedAnimation is an Animation<double> subclass that applies a curve to a parent animation (via AnimationWithParentMixin). As such, CurvedAnimation proxies the parent animation, transforming each value before any consumers may read it (via Curve.transform). CurvedAnimation also allows different curves to be used for forward and reverse directions.

• CurveTween is an Animatable<double> subclass that is analogous to CurvedAnimation. As an animatable, CurveTween delegates its transform (via Animatable<double>.transform) to the provided curve transform (via Curve.transform). Since CurveTween doesn’t perform interpolation, but instead represents an arbitrary mapping, it isn’t actually a tween.

• AnimationController includes built-in curve support (via _InterpolationSimulation). When the simulation is advanced to transform elapsed wall time into a timing value (by querying _InterpolationSimulation.x), if available, a curve is used when computing the new value. As the resulting value is generally interpreted as a timing value, this influences the perceived rate of change of the animation.

How are animations composed?

• AnimationWithParentMixin provides support for building animations that delegate to a parent animation. The various listener methods (AnimationWithParentMixin.addListener, AnimationWithParentMixin.addStatusListener) are forwarded to the parent; all relevant state is also read from the parent. Clients provide a value accessor that constructs a derivative value based on the parent’s value.

• Composition is managed via Animatable.chain or Animatable.animate; Animation<T>.drive delegates to the provided animatable.

  • _AnimatedEvaluation is an Animation<T> that applies an animatable to a parent animation. All listenable methods delegate to the parent animation (via AnimationWithParentMixin); thus, the resulting animation is driven by the parent. The value accessor is overwritten so that parent’s value may be transformed by the animatable (via Animatable.evaluate).

  • _ChainedEvaluation is an Animatable<T> that combines a parent animatable with a child animatable. In particular, _ChainedEvaluation.transform first evaluates the parent animatable (via Animatable<T>.evaluate), then passes this value to the child animatable.

• CompoundAnimation is an Animation<T> subclass that combines two animations. CompoundAnimation.value is overwritten to produce a final value using the first and second animation’s values (via CompoundAnimation.first, CompoundAnimation.next). Note that CompoundAnimation is driven by two animations (i.e., it ticks when either animation ticks), unlike earlier composition examples that drive an animatable using a single parent animation.

What are the higher level animation building blocks?

• ProxyAnimation provides a read-only view of a parent animation that will reflect any changes to the original animation. It does this by proxying the animation listener methods as well as the status and value accessors. Additionally, ProxyAnimation supports replacing the parent animation inline; the transition is seamless from the perspective of any listeners.

• TrainHoppingAnimation monitors two animations, switching from the first to the second when the second emits the same value as the first (e.g., because it is reversed or moving toward the value more quickly). TrainHoppingAnimation utilizes AnimationEagerListenerMixin because it relies on the parent animations’ notifications to determine when to switch tracks, regardless of whether there are any external listeners.

• CompoundAnimation combines two animations, ticking when either animation ticks (this differs from, e.g., Animation.animate, which drives an animatable via an animation). The status is that of the second animation (if it’s running), else the first. The values are combined by overriding the Animation.value accessor; the constituent animations are referenced as CompoundAnimation.first and CompoundAnimation.next, respectively. This animation is lazy -- it will only listen to the sub-animations when it has listeners, and will avoid generating useless notifications.

  • CompoundAnimation is the basis of MaxAnimation, MinAnimation, and MeanAnimation.

• AlwaysStoppedAnimation exposes a constant value and never changes status or notifies listeners.

• ReverseAnimation plays an animation in reverse, using the appropriate status and direction. That is, if the parent animation is played forward (e.g., via AnimationController.forward), the ReverseAnimation’s status will be reversed. Moreover, the value reported by ReverseAnimation will be the inverse of the parent’s value assuming a [0, 1] range (thus, one minus the parent’s value). Note that this differs from simply reversing a tween (e.g., tweening from one to zero); though the values would be reversed, the animation status would be unchanged.

What are the highest level animation building blocks?

• AnimatedWidget is an abstract stateful widget that rebuilds whenever the provided listenable notifies its clients. When this happens, the associated state instance is marked dirty (via _AnimatedState.setState) and rebuilt. _AnimatedState.build delegates to the widget’s build method, which subclasses must implement; these utilize the listenable (typically an animation) to update the UI.

• AnimatedBuilder extends AnimatedWidget to accept a build function (TransitionBuilder); this builder is invoked whenever the widget rebuilds (via AnimatedBuilder.build). This allows clients to utilize the AnimatedWidget flow without creating an explicit subclass.

How does implicit animation work?

• ImplicitlyAnimatedWidget provides support for widgets that animate in response to changes to selected properties; the initial value is not animated. Though descendant widgets are only able to customize the animation’s duration and curve, ImplicitlyAnimatedWidget are often convenient in that they fully manage the underlying AnimationController.

  • Subclasses must use a State instance that extends ImplicitlyAnimatedWidgetState. Those that should be rebuilt (i.e., marked dirty) whenever the animation ticks extend AnimatedWidgetBaseState, instead.

    • ImplicitlyAnimatedWidgetState.forEachTween is the engine that drives implicit animation. Subclasses implement this method such that the provided visitor (TweenVisitor) is invoked once per implicitly animatable property.

    • The visitor function requires three arguments: the current tween instance (constructed by the superclass but cached locally, e.g., ExampleState._opacityTween), the target value (typically read from the widget, e.g., ExampleState.widget.opacityValue), and a constructor (TweenConstructor) that returns a new tween instance starting at the provided value. The visitor returns an updated tween; this value is typically assigned to the same field associated with the first argument.

    • Tweens are constructed during state initialization (via ImplicitlyAnimatedWidgetState._constructTweens) for all implicitly animatable properties with non-null target values (via ImplicitlyAnimatedWidgetState.forEachTween). Tweens may also be constructed outside of this context as they transition from null to non-null target values.

    • When the widget is updated (via ImplicitlyAnimatedWidgetState.didUpdateWidget), ImplicitlyAnimatedWidgetState.forEachTween steps through the subclass’s animatable properties to update the tweens’ bounds (via ImplicitlyAnimatedWidgetState._updateTween). The tween’s start is set using the current animation value (to avoid jumping), with the tween’s end set to the target value.

    • Last, the animation is played forward if the tween wasn’t already animating toward the target value (i.e., the tween’s previous endpoint didn’t match the target value, via ImplicitlyAnimatedWidgetState._shouldAnimateTweens).

  • The subclass is responsible for using the animation (ImplicitlyAnimatedWidgetState.animation) and tween directly (i.e., by evaluating the tween using the animation’s current value).