TweenAnimationBuilder<T extends Object?> class Null safety

Widget builder that animates a property of a Widget to a target value whenever the target value changes.

The type of the animated property (Color, Rect, double, etc.) is defined via the type of the provided tween (e.g. ColorTween, RectTween, Tween<double>, etc.).

The tween also defines the target value for the animation: When the widget first builds, it animates from Tween.begin to Tween.end. A new animation can be triggered anytime by providing a new tween with a new Tween.end value. The new animation runs from the current animation value (which may be Tween.end of the old tween, if that animation completed) to Tween.end of the new tween.

The animation is further customized by providing a curve and duration.

The current value of the animation along with the child is passed to the builder callback, which is expected to build a Widget based on the current animation value. The builder is called throughout the animation for every animation value until Tween.end is reached.

A provided onEnd callback is called whenever an animation completes. Registering an onEnd callback my be useful to trigger an action (like another animation) at the end of the current animation.

Performance optimizations

If your builder function contains a subtree that does not depend on the animation, it's more efficient to build that subtree once instead of rebuilding it on every animation tick.

If you pass the pre-built subtree as the child parameter, the AnimatedBuilder will pass it back to your builder function so that you can incorporate it into your build.

Using this pre-built child is entirely optional, but can improve performance significantly in some cases and is therefore a good practice.

Ownership of the Tween

The TweenAnimationBuilder takes full ownership of the provided tween instance and it will mutate it. Once a Tween has been passed to a TweenAnimationBuilder, its properties should not be accessed or changed anymore to avoid interference with the TweenAnimationBuilder.

It is good practice to never store a Tween provided to a TweenAnimationBuilder in an instance variable to avoid accidental modifications of the Tween.

Example Code

This example shows an IconButton that "zooms" in when the widget first builds (its size smoothly increases from 0 to 24) and whenever the button is pressed, it smoothly changes its size to the new target value of either 48 or 24.

To create a local project with this code sample, run:
flutter create --sample=widgets.TweenAnimationBuilder.1 mysample

Relationship to ImplicitlyAnimatedWidgets and AnimatedWidgets

The ImplicitlyAnimatedWidget has many subclasses that provide animated versions of regular widgets. These subclasses (like AnimatedOpacity, AnimatedContainer, AnimatedSize, etc.) animate changes in their properties smoothly and they are easier to use than this general-purpose builder. However, TweenAnimationBuilder (which itself is a subclass of ImplicitlyAnimatedWidget) is handy for animating any widget property to a given target value even when the framework (or third-party widget library) doesn't ship with an animated version of that widget.

Those ImplicitlyAnimatedWidgets (including this TweenAnimationBuilder) all manage an internal AnimationController to drive the animation. If you want more control over the animation than just setting a target value, duration, and curve, have a look at (subclasses of) AnimatedWidgets. For those, you have to manually manage an AnimationController giving you full control over the animation. An example of an AnimatedWidget is the AnimatedBuilder, which can be used similarly to this TweenAnimationBuilder, but unlike the latter it is powered by a developer-managed AnimationController.

Inheritance

Constructors

TweenAnimationBuilder({Key? key, required Tween<T> tween, required Duration duration, Curve curve = Curves.linear, required ValueWidgetBuilder<T> builder, VoidCallback? onEnd, Widget? child}): Creates a TweenAnimationBuilder.
const

Properties

builder → ValueWidgetBuilder<T>: Called every time the animation value changes.
final
child → Widget?: The child widget to pass to the builder.
final
curve → Curve: The curve to apply when animating the parameters of this container.
finalinherited
duration → Duration: The duration over which to animate the parameters of this container.
finalinherited
hashCode → int: The hash code for this object.
nonVirtual">@nonVirtualread-onlyinherited
key → Key?: Controls how one widget replaces another widget in the tree.
finalinherited
onEnd → VoidCallback?: Called every time an animation completes.
finalinherited
runtimeType → Type: A representation of the runtime type of the object.
read-onlyinherited
tween → Tween<T>: Defines the target value for the animation.
final

Methods

createElement() → StatefulElement: Creates a StatefulElement to manage this widget's location in the tree.
inherited
createState() → ImplicitlyAnimatedWidgetState<ImplicitlyAnimatedWidget>: Creates the mutable state for this widget at a given location in the tree.
override
debugDescribeChildren() → List<DiagnosticsNode>: Returns a list of DiagnosticsNode objects describing this node's children.
protected">@protectedinherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void: Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic: Invoked when a non-existent method or property is accessed.
inherited
toDiagnosticsNode({String? name, DiagnosticsTreeStyle? style}) → DiagnosticsNode: Returns a debug representation of the object that is used by debugging tools and by DiagnosticsNode.toStringDeep.
inherited
toString({DiagnosticLevel minLevel = DiagnosticLevel.info}) → String: A string representation of this object.
inherited
toStringDeep({String prefixLineOne = '', String? prefixOtherLines, DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String: Returns a string representation of this node and its descendants.
inherited
toStringShallow({String joiner = ', ', DiagnosticLevel minLevel = DiagnosticLevel.debug}) → String: Returns a one-line detailed description of the object.
inherited
toStringShort() → String: A short, textual description of this widget.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
nonVirtual">@nonVirtualinherited

Flutter
widgets
TweenAnimationBuilder<T extends Object?> class