animation.dart 4.14 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 11 12 13 14 15 16 17 18 19 20 21 22 23
/// 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,
}

24
/// Signature for listeners attached using [Animation.addStatusListener].
25 26
typedef void AnimationStatusListener(AnimationStatus status);

27
/// An animation with a value of type `T`.
28
///
29
/// An animation consists of a value (of type `T`) together with a status. The
30 31 32 33 34 35 36 37 38 39 40
/// 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].
41
abstract class Animation<T> extends Listenable implements ValueListenable<T> {
42 43
  /// Abstract const constructor. This constructor enables subclasses to provide
  /// const constructors so that they can be used in const expressions.
44 45
  const Animation();

46 47
  // keep these next five dartdocs in sync with the dartdocs in AnimationWithParentMixin<T>

48
  /// Calls the listener every time the value of the animation changes.
49 50
  ///
  /// Listeners can be removed with [removeListener].
51
  @override
52
  void addListener(VoidCallback listener);
53

54
  /// Stop calling the listener every time the value of the animation changes.
55 56
  ///
  /// Listeners can be added with [addListener].
57
  @override
58
  void removeListener(VoidCallback listener);
59

60
  /// Calls listener every time the status of the animation changes.
61 62
  ///
  /// Listeners can be removed with [removeStatusListener].
63
  void addStatusListener(AnimationStatusListener listener);
64

65
  /// Stops calling the listener every time the status of the animation changes.
66 67
  ///
  /// Listeners can be added with [addStatusListener].
68 69 70 71 72 73
  void removeStatusListener(AnimationStatusListener listener);

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

  /// The current value of the animation.
74
  @override
75 76 77 78 79 80 81 82
  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;

83
  @override
84
  String toString() {
85
    return '${describeIdentity(this)}(${toStringDetails()})';
86
  }
87 88 89 90 91 92 93 94 95 96 97 98 99 100 101

  /// 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)
102 103 104 105 106 107 108 109 110 111 112
  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
113
        icon = '\u23ED'; // >>|
114 115
        break;
      case AnimationStatus.dismissed:
Adam Barth's avatar
Adam Barth committed
116
        icon = '\u23EE'; // |<<
117 118 119 120 121 122
        break;
    }
    assert(icon != null);
    return '$icon';
  }
}