// Copyright 2014 The Flutter Authors. All rights reserved. // Use of this source code is governed by a BSD-style license that can be // found in the LICENSE file. import 'package:flutter/foundation.dart'; import 'tween.dart'; export 'dart:ui' show VoidCallback; export 'tween.dart' show Animatable; // Examples can assume: // late AnimationController _controller; // late ValueNotifier<double> _scrollPosition; /// The status of an animation. enum AnimationStatus { /// The animation is stopped at the beginning. dismissed, /// The animation is running from beginning to end. forward, /// The animation is running backwards, from end to beginning. reverse, /// The animation is stopped at the end. completed, } /// Signature for listeners attached using [Animation.addStatusListener]. typedef AnimationStatusListener = void Function(AnimationStatus status); /// Signature for method used to transform values in [Animation.fromValueListenable]. typedef ValueListenableTransformer<T> = T Function(T); /// An animation with a value of type `T`. /// /// An animation consists of a value (of type `T`) together with a status. The /// status indicates whether the animation is conceptually running from /// beginning to end or from the end back to the beginning, although the actual /// value of the animation might not change monotonically (e.g., if the /// animation uses a curve that bounces). /// /// Animations also let other objects listen for changes to either their value /// or their status. These callbacks are called during the "animation" phase of /// the pipeline, just prior to rebuilding widgets. /// /// To create a new animation that you can run forward and backward, consider /// using [AnimationController]. /// /// See also: /// /// * [Tween], which can be used to create [Animation] subclasses that /// convert `Animation<double>`s into other kinds of [Animation]s. abstract class Animation<T> extends Listenable implements ValueListenable<T> { /// Abstract const constructor. This constructor enables subclasses to provide /// const constructors so that they can be used in const expressions. const Animation(); /// Create a new animation from a [ValueListenable]. /// /// The returned animation will always have an animations status of /// [AnimationStatus.forward]. The value of the provided listenable can /// be optionally transformed using the [transformer] function. /// /// {@tool snippet} /// /// This constructor can be used to replace instances of [ValueListenableBuilder] /// widgets with a corresponding animated widget, like a [FadeTransition]. /// /// Before: /// /// ```dart /// Widget build(BuildContext context) { /// return ValueListenableBuilder<double>( /// valueListenable: _scrollPosition, /// builder: (BuildContext context, double value, Widget? child) { /// final double opacity = (value / 1000).clamp(0, 1); /// return Opacity(opacity: opacity, child: child); /// }, /// child: const ColoredBox( /// color: Colors.red, /// child: Text('Hello, Animation'), /// ), /// ); /// } /// ``` /// /// {@end-tool} /// {@tool snippet} /// /// After: /// /// ```dart /// Widget build2(BuildContext context) { /// return FadeTransition( /// opacity: Animation<double>.fromValueListenable(_scrollPosition, transformer: (double value) { /// return (value / 1000).clamp(0, 1); /// }), /// child: const ColoredBox( /// color: Colors.red, /// child: Text('Hello, Animation'), /// ), /// ); /// } /// ``` /// {@end-tool} factory Animation.fromValueListenable(ValueListenable<T> listenable, { ValueListenableTransformer<T>? transformer, }) = _ValueListenableDelegateAnimation<T>; // keep these next five dartdocs in sync with the dartdocs in AnimationWithParentMixin<T> /// Calls the listener every time the value of the animation changes. /// /// Listeners can be removed with [removeListener]. @override void addListener(VoidCallback listener); /// Stop calling the listener every time the value of the animation changes. /// /// If `listener` is not currently registered as a listener, this method does /// nothing. /// /// Listeners can be added with [addListener]. @override void removeListener(VoidCallback listener); /// Calls listener every time the status of the animation changes. /// /// Listeners can be removed with [removeStatusListener]. void addStatusListener(AnimationStatusListener listener); /// Stops calling the listener every time the status of the animation changes. /// /// If `listener` is not currently registered as a status listener, this /// method does nothing. /// /// Listeners can be added with [addStatusListener]. void removeStatusListener(AnimationStatusListener listener); /// The current status of this animation. AnimationStatus get status; /// The current value of the animation. @override T get value; /// Whether this animation is stopped at the beginning. bool get isDismissed => status == AnimationStatus.dismissed; /// Whether this animation is stopped at the end. bool get isCompleted => status == AnimationStatus.completed; /// Chains a [Tween] (or [CurveTween]) to this [Animation]. /// /// This method is only valid for `Animation<double>` instances (i.e. when `T` /// is `double`). This means, for instance, that it can be called on /// [AnimationController] objects, as well as [CurvedAnimation]s, /// [ProxyAnimation]s, [ReverseAnimation]s, [TrainHoppingAnimation]s, etc. /// /// It returns an [Animation] specialized to the same type, `U`, as the /// argument to the method (`child`), whose value is derived by applying the /// given [Tween] to the value of this [Animation]. /// /// {@tool snippet} /// /// Given an [AnimationController] `_controller`, the following code creates /// an `Animation<Alignment>` that swings from top left to top right as the /// controller goes from 0.0 to 1.0: /// /// ```dart /// Animation<Alignment> alignment1 = _controller.drive( /// AlignmentTween( /// begin: Alignment.topLeft, /// end: Alignment.topRight, /// ), /// ); /// ``` /// {@end-tool} /// {@tool snippet} /// /// The `_alignment.value` could then be used in a widget's build method, for /// instance, to position a child using an [Align] widget such that the /// position of the child shifts over time from the top left to the top right. /// /// It is common to ease this kind of curve, e.g. making the transition slower /// at the start and faster at the end. The following snippet shows one way to /// chain the alignment tween in the previous example to an easing curve (in /// this case, [Curves.easeIn]). In this example, the tween is created /// elsewhere as a variable that can be reused, since none of its arguments /// vary. /// /// ```dart /// final Animatable<Alignment> tween = AlignmentTween(begin: Alignment.topLeft, end: Alignment.topRight) /// .chain(CurveTween(curve: Curves.easeIn)); /// // ... /// final Animation<Alignment> alignment2 = _controller.drive(tween); /// ``` /// {@end-tool} /// {@tool snippet} /// /// The following code is exactly equivalent, and is typically clearer when /// the tweens are created inline, as might be preferred when the tweens have /// values that depend on other variables: /// /// ```dart /// Animation<Alignment> alignment3 = _controller /// .drive(CurveTween(curve: Curves.easeIn)) /// .drive(AlignmentTween( /// begin: Alignment.topLeft, /// end: Alignment.topRight, /// )); /// ``` /// {@end-tool} /// {@tool snippet} /// /// This method can be paired with an [Animatable] created via /// [Animatable.fromCallback] in order to transform an animation with a /// callback function. This can be useful for performing animations that /// do not have well defined start or end points. This example transforms /// the current scroll position into a color that cycles through values /// of red. /// /// ```dart /// Animation<Color> color = Animation<double>.fromValueListenable(_scrollPosition) /// .drive(Animatable<Color>.fromCallback((double value) { /// return Color.fromRGBO(value.round() % 255, 0, 0, 1); /// })); /// ``` /// /// {@end-tool} /// /// See also: /// /// * [Animatable.animate], which does the same thing. /// * [AnimationController], which is usually used to drive animations. /// * [CurvedAnimation], an alternative to [CurveTween] for applying easing /// curves, which supports distinct curves in the forward direction and the /// reverse direction. /// * [Animatable.fromCallback], which allows creating an [Animatable] from an /// arbitrary transformation. @optionalTypeArgs Animation<U> drive<U>(Animatable<U> child) { assert(this is Animation<double>); return child.animate(this as Animation<double>); } @override String toString() { return '${describeIdentity(this)}(${toStringDetails()})'; } /// Provides a string describing the status of this object, but not including /// information about the object itself. /// /// This function is used by [Animation.toString] so that [Animation] /// subclasses can provide additional details while ensuring all [Animation] /// subclasses have a consistent [toString] style. /// /// The result of this function includes an icon describing the status of this /// [Animation] object: /// /// * "▶": [AnimationStatus.forward] ([value] increasing) /// * "◀": [AnimationStatus.reverse] ([value] decreasing) /// * "⏭": [AnimationStatus.completed] ([value] == 1.0) /// * "⏮": [AnimationStatus.dismissed] ([value] == 0.0) String toStringDetails() { switch (status) { case AnimationStatus.forward: return '\u25B6'; // > case AnimationStatus.reverse: return '\u25C0'; // < case AnimationStatus.completed: return '\u23ED'; // >>| case AnimationStatus.dismissed: return '\u23EE'; // |<< } } } // An implementation of an animation that delegates to a value listenable with a fixed direction. class _ValueListenableDelegateAnimation<T> extends Animation<T> { _ValueListenableDelegateAnimation(this._listenable, { ValueListenableTransformer<T>? transformer, }) : _transformer = transformer; final ValueListenable<T> _listenable; final ValueListenableTransformer<T>? _transformer; @override void addListener(VoidCallback listener) { _listenable.addListener(listener); } @override void addStatusListener(AnimationStatusListener listener) { // status will never change. } @override void removeListener(VoidCallback listener) { _listenable.removeListener(listener); } @override void removeStatusListener(AnimationStatusListener listener) { // status will never change. } @override AnimationStatus get status => AnimationStatus.forward; @override T get value => _transformer?.call(_listenable.value) ?? _listenable.value; }