tween_sequence.dart 4.57 KB
Newer Older
1 2 3 4
// Copyright 2018 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 6 7 8 9
import 'package:flutter/foundation.dart';

import 'animation.dart';
import 'tween.dart';

10 11 12
// Examples can assume:
// AnimationController myAnimationController;

13 14
/// Enables creating an [Animation] whose value is defined by a sequence of
/// [Tween]s.
15
///
16 17 18
/// Each [TweenSequenceItem] has a weight that defines its percentage of the
/// animation's duration. Each tween defines the animation's value during the
/// interval indicated by its weight.
19
///
20 21 22 23
/// {@tool sample}
/// This example defines an animation that uses an easing curve to interpolate
/// between 5.0 and 10.0 during the first 40% of the animation, remains at 10.0
/// for the next 20%, and then returns to 5.0 for the final 40%.
24
///
25
/// ```dart
26
/// final Animation<double> animation = TweenSequence(
27
///   <TweenSequenceItem<double>>[
28 29 30
///     TweenSequenceItem<double>(
///       tween: Tween<double>(begin: 5.0, end: 10.0)
///         .chain(CurveTween(curve: Curves.ease)),
31 32
///       weight: 40.0,
///     ),
33 34
///     TweenSequenceItem<double>(
///       tween: ConstantTween<double>(10.0),
35 36
///       weight: 20.0,
///     ),
37 38 39
///     TweenSequenceItem<double>(
///       tween: Tween<double>(begin: 10.0, end: 5.0)
///         .chain(CurveTween(curve: Curves.ease)),
40 41 42 43
///       weight: 40.0,
///     ),
///   ],
/// ).animate(myAnimationController);
44
/// ```
45
/// {@end-tool}
46 47 48
class TweenSequence<T> extends Animatable<T> {
  /// Construct a TweenSequence.
  ///
49
  /// The [items] parameter must be a list of one or more [TweenSequenceItem]s.
50
  ///
51 52 53
  /// There's a small cost associated with building a `TweenSequence` so it's
  /// best to reuse one, rather than rebuilding it on every frame, when that's
  /// possible.
54 55 56
  TweenSequence(List<TweenSequenceItem<T>> items)
      : assert(items != null),
        assert(items.isNotEmpty) {
57 58 59 60 61 62 63 64 65 66
    _items.addAll(items);

    double totalWeight = 0.0;
    for (TweenSequenceItem<T> item in _items)
      totalWeight += item.weight;
    assert(totalWeight > 0.0);

    double start = 0.0;
    for (int i = 0; i < _items.length; i += 1) {
      final double end = i == _items.length - 1 ? 1.0 : start + _items[i].weight / totalWeight;
67
      _intervals.add(_Interval(start, end));
68 69 70 71 72 73 74 75 76 77
      start = end;
    }
  }

  final List<TweenSequenceItem<T>> _items = <TweenSequenceItem<T>>[];
  final List<_Interval> _intervals = <_Interval>[];

  T _evaluateAt(double t, int index) {
    final TweenSequenceItem<T> element = _items[index];
    final double tInterval = _intervals[index].value(t);
78
    return element.tween.transform(tInterval);
79 80 81
  }

  @override
82
  T transform(double t) {
83 84 85 86 87 88 89 90 91 92 93
    assert(t >= 0.0 && t <= 1.0);
    if (t == 1.0)
      return _evaluateAt(t, _items.length - 1);
    for (int index = 0; index < _items.length; index++) {
      if (_intervals[index].contains(t))
        return _evaluateAt(t, index);
    }
    // Should be unreachable.
    assert(false, 'TweenSequence.evaluate() could not find a interval for $t');
    return null;
  }
94 95 96

  @override
  String toString() => 'TweenSequence(${_items.length} items)';
97 98 99 100 101 102 103 104 105 106
}

/// A simple holder for one element of a [TweenSequence].
class TweenSequenceItem<T> {
  /// Construct a TweenSequenceItem.
  ///
  /// The [tween] must not be null and [weight] must be greater than 0.0.
  const TweenSequenceItem({
    @required this.tween,
    @required this.weight,
107 108 109
  }) : assert(tween != null),
       assert(weight != null),
       assert(weight > 0.0);
110 111 112 113 114

  /// Defines the value of the [TweenSequence] for the interval within the
  /// animation's duration indicated by [weight] and this item's position
  /// in the list of items.
  ///
115
  /// {@tool sample}
116
  ///
117 118
  /// The value of this item can be "curved" by chaining it to a [CurveTween].
  /// For example to create a tween that eases from 0.0 to 10.0:
119 120 121 122
  ///
  /// ```dart
  /// Tween<double>(begin: 0.0, end: 10.0)
  ///   .chain(CurveTween(curve: Curves.ease))
123
  /// ```
124
  /// {@end-tool}
125 126
  final Animatable<T> tween;

127
  /// An arbitrary value that indicates the relative percentage of a
128 129
  /// [TweenSequence] animation's duration when [tween] will be used.
  ///
130 131
  /// The percentage for an individual item is the item's weight divided by the
  /// sum of all of the items' weights.
132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147
  final double weight;
}

class _Interval {
  const _Interval(this.start, this.end) : assert(end > start);

  final double start;
  final double end;

  bool contains(double t) => t >= start && t < end;

  double value(double t) => (t - start) / (end - start);

  @override
  String toString() => '<$start, $end>';
}