SchedulerBinding.handleBeginFrameevery 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.
AnimationControllerutilizes an associated
Tickerto 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.upperBound(if spanning the animation’s full range), or
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.
SpringSimulation). Typically, the simulation is responsible for mapping from real time to a value representing animation progress.
_InterpolationSimulationis configured in
_ChainedEvaluation) works by proxying the underlying listenable (i.e., by delegating listener operations to the parent animation, which advances as described above).
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.
AnimationStatusand 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.completed), or actively producing values in a particular order (
ValueListenablewhich 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.
Tis 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>.transformto 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>.evaluatealways 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.
Animatable<T>that linearly interpolates between beginning and end values of type
Tween.lerp). By default, algebraic linear interpolation is used, though many types implement custom methods (via
T.lerp) or provide overloaded operators.
TweenSequenceis an animatable that allows an animation to drive a sequence of tweens, associating each with a portion of the animation’s duration (via
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
Toleranceinstance specifies epsilon values for time, velocity, and position to determine when the simulation has settled.
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
Tickerinstance, 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.animateBack), or cyclically (via
AnimationController.repeat). Animations can also be driven by a custom
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.lowerBound), both doubles. An immutable view of the animation is also exposed (
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.
TickerFutureexposes 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.
TickerProviderinterface within the context of a
Stateobject (the latter has less overhead since it only tracks a single ticker). These mixins query an inherited
TickerModethat 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.
AnimationLocalStatusListenersMixinprovide implementations for the two listenable interfaces supported by animations: value listeners (
Animation.removeListener), and status listeners (
Animation.removeStatusListener). Both store listeners in a local
ObserverListand support hooks indicating when a listener is registered and unregistered (
didUnregisterListener, respectively). A number of framework subclasses depend on these mixins (e.g.,
Animation<T>doesn’t provide a concrete implementation.
AnimationLazyListenerMixinuses 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
AnimationEagerListenerMixinignores 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.
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.
AnimationStatus.dismissedand one corresponding to
ElasticInOutCurvedefine a spring-like curve that overshoots as it grows, shrinks, or settles, respectively.
SawToothproduces N linear intervals, with no interpolation at edges
FlippedCurvetransforms an input curve, mirroring it both horizontally and vertically.
Animation<double>subclass that applies a curve to a parent animation (via
AnimationWithParentMixin). As such,
CurvedAnimationproxies the parent animation, transforming each value before any consumers may read it (via
CurvedAnimationalso allows different curves to be used for forward and reverse directions.
Animatable<double>subclass that is analogous to
CurvedAnimation. As an animatable,
CurveTweendelegates its transform (via
Animatable<double>.transform) to the provided curve transform (via
CurveTweendoesn’t perform interpolation, but instead represents an arbitrary mapping, it isn’t actually a tween.
AnimationControllerincludes 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.
AnimationWithParentMixinprovides support for building animations that delegate to a parent animation. The various listener methods (
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.
Animation<T>.drivedelegates to the provided animatable.
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<T>that combines a parent animatable with a child animatable. In particular,
_ChainedEvaluation.transformfirst evaluates the parent animatable (via
Animatable<T>.evaluate), then passes this value to the child animatable.
Animation<T>subclass that combines two animations.
CompoundAnimation.valueis overwritten to produce a final value using the first and second animation’s values (via
CompoundAnimation.next). Note that
CompoundAnimationis 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.
ProxyAnimationprovides 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,
ProxyAnimationsupports replacing the parent animation inline; the transition is seamless from the perspective of any listeners.
TrainHoppingAnimationmonitors 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).
AnimationEagerListenerMixinbecause it relies on the parent animations’ notifications to determine when to switch tracks, regardless of whether there are any external listeners.
CompoundAnimationcombines 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.valueaccessor; the constituent animations are referenced as
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.
CompoundAnimationis the basis of
AlwaysStoppedAnimationexposes a constant value and never changes status or notifies listeners.
ReverseAnimationplays an animation in reverse, using the appropriate status and direction. That is, if the parent animation is played forward (e.g., via
ReverseAnimation’s status will be reversed. Moreover, the value reported by
ReverseAnimationwill 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.
AnimatedWidgetis 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.builddelegates to the widget’s build method, which subclasses must implement; these utilize the listenable (typically an animation) to update the UI.
AnimatedWidgetto accept a build function (
TransitionBuilder); this builder is invoked whenever the widget rebuilds (via
AnimatedBuilder.build). This allows clients to utilize the
AnimatedWidgetflow without creating an explicit subclass.
ImplicitlyAnimatedWidgetprovides 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,
ImplicitlyAnimatedWidgetare often convenient in that they fully manage the underlying
Stateinstance that extends
ImplicitlyAnimatedWidgetState. Those that should be rebuilt (i.e., marked dirty) whenever the animation ticks extend
ImplicitlyAnimatedWidgetState.forEachTweenis the engine that drives implicit animation. Subclasses implement this method such that the provided visitor (
TweenVisitor) is invoked once per implicitly animatable property.
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.
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.
ImplicitlyAnimatedWidgetState.forEachTweensteps 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.
ImplicitlyAnimatedWidgetState.animation) and tween directly (i.e., by evaluating the tween using the animation’s current value).