TweenAnimationBuilderModifier<T extends Object?> class

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

{@tool dartpad} 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.

** See code in examples/api/lib/widgets/tween_animation_builder/tween_animation_builder.0.dart ** {@end-tool}

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
Available extensions

Constructors

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

Properties

builder → ValueWidgetBuilder<T>
Called every time the animation value changes.
final
curve → Curve
The curve to apply when animating the parameters of this container.
final
duration → Duration
The duration over which to animate the parameters of this container.
final
hashCode → int
The hash code for this object.
no setterinherited
key → Key?
Controls how one widget replaces another widget in the tree.
finalinherited
modifierKey → Key?
The actual key of the widget, which Modifier wrapped
finalinherited
onEnd → VoidCallback?
Called every time an animation completes.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
tween → Tween<T>
Defines the target value for the animation.
final

Methods

build(BuildContext context) → Widget
Describes the part of the user interface represented by this widget.
inherited
buildWithChild(BuildContext context, Widget? child) → Widget
A build method that receives an extra child parameter.
override
createElement() → SingleChildStatelessElement
Create a SingleChildStatelessElement
inherited
debugDescribeChildren() → List<DiagnosticsNode>
Returns a list of DiagnosticsNode objects describing this node's children.
inherited
debugFillProperties(DiagnosticPropertiesBuilder properties) → void
Add additional properties associated with the node.
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent 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.
inherited