animation.dart 7.39 KB
Newer Older
1 2 3 4
// Copyright 2016 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

5
import 'dart:ui' show VoidCallback;
6

7 8
import 'package:flutter/foundation.dart';

9 10
import 'tween.dart';

11 12 13
// Examples can assume:
// AnimationController _controller;

14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
/// 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,
}

29
/// Signature for listeners attached using [Animation.addStatusListener].
30
typedef AnimationStatusListener = void Function(AnimationStatus status);
31

32
/// An animation with a value of type `T`.
33
///
34
/// An animation consists of a value (of type `T`) together with a status. The
35 36 37 38 39 40 41 42 43 44 45
/// 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].
46 47 48 49 50
///
/// See also:
///
///  * [Tween], which can be used to create [Animation] subclasses that
///    convert `Animation<double>`s into other kinds of `Animation`s.
51
abstract class Animation<T> extends Listenable implements ValueListenable<T> {
52 53
  /// Abstract const constructor. This constructor enables subclasses to provide
  /// const constructors so that they can be used in const expressions.
54 55
  const Animation();

56 57
  // keep these next five dartdocs in sync with the dartdocs in AnimationWithParentMixin<T>

58
  /// Calls the listener every time the value of the animation changes.
59 60
  ///
  /// Listeners can be removed with [removeListener].
61
  @override
62
  void addListener(VoidCallback listener);
63

64
  /// Stop calling the listener every time the value of the animation changes.
65 66
  ///
  /// Listeners can be added with [addListener].
67
  @override
68
  void removeListener(VoidCallback listener);
69

70
  /// Calls listener every time the status of the animation changes.
71 72
  ///
  /// Listeners can be removed with [removeStatusListener].
73
  void addStatusListener(AnimationStatusListener listener);
74

75
  /// Stops calling the listener every time the status of the animation changes.
76 77
  ///
  /// Listeners can be added with [addStatusListener].
78 79 80 81 82 83
  void removeStatusListener(AnimationStatusListener listener);

  /// The current status of this animation.
  AnimationStatus get status;

  /// The current value of the animation.
84
  @override
85 86 87 88 89 90 91 92
  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;

93 94 95 96 97 98 99 100 101 102 103
  /// 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].
  ///
104
  /// {@tool sample}
105 106 107 108 109 110 111 112 113 114 115 116 117
  ///
  /// 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,
  ///   ),
  /// );
  /// ```
118 119
  /// {@end-tool}
  /// {@tool sample}
120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137
  ///
  /// 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));
  /// // ...
  /// Animation<Alignment> _alignment2 = _controller.drive(_tween);
  /// ```
138 139
  /// {@end-tool}
  /// {@tool sample}
140 141 142 143 144 145 146 147 148 149 150 151 152
  ///
  /// 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,
  ///   ));
  /// ```
153
  /// {@end-tool}
154 155 156 157 158 159 160 161 162 163 164 165 166 167
  ///
  /// 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.
  @optionalTypeArgs
  Animation<U> drive<U>(Animatable<U> child) {
    assert(this is Animation<double>);
    return child.animate(this as dynamic); // TODO(ianh): Clean this once https://github.com/dart-lang/sdk/issues/32120 is fixed.
  }

168
  @override
169
  String toString() {
170
    return '${describeIdentity(this)}(${toStringDetails()})';
171
  }
172 173 174 175 176 177 178 179 180 181 182 183 184 185 186

  /// 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:
  ///
  /// * "&#x25B6;": [AnimationStatus.forward] ([value] increasing)
  /// * "&#x25C0;": [AnimationStatus.reverse] ([value] decreasing)
  /// * "&#x23ED;": [AnimationStatus.completed] ([value] == 1.0)
  /// * "&#x23EE;": [AnimationStatus.dismissed] ([value] == 0.0)
187 188 189 190 191 192 193 194 195 196 197
  String toStringDetails() {
    assert(status != null);
    String icon;
    switch (status) {
      case AnimationStatus.forward:
        icon = '\u25B6'; // >
        break;
      case AnimationStatus.reverse:
        icon = '\u25C0'; // <
        break;
      case AnimationStatus.completed:
Adam Barth's avatar
Adam Barth committed
198
        icon = '\u23ED'; // >>|
199 200
        break;
      case AnimationStatus.dismissed:
Adam Barth's avatar
Adam Barth committed
201
        icon = '\u23EE'; // |<<
202 203 204 205 206 207
        break;
    }
    assert(icon != null);
    return '$icon';
  }
}