animated_cross_fade.dart 13.1 KB
Newer Older
1 2 3 4 5 6 7 8 9
// 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.

import 'package:flutter/rendering.dart';

import 'animated_size.dart';
import 'basic.dart';
import 'framework.dart';
10
import 'ticker_provider.dart';
11 12
import 'transitions.dart';

13
/// Specifies which of two children to show. See [AnimatedCrossFade].
14 15 16
///
/// The child that is shown will fade in, while the other will fade out.
enum CrossFadeState {
17 18
  /// Show the first child ([AnimatedCrossFade.firstChild]) and hide the second
  /// ([AnimatedCrossFade.secondChild]]).
19
  showFirst,
20

21 22 23
  /// Show the second child ([AnimatedCrossFade.secondChild]) and hide the first
  /// ([AnimatedCrossFade.firstChild]).
  showSecond,
24 25
}

26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59
/// Signature for the [AnimatedCrossFade.layoutBuilder] callback.
///
/// The `topChild` is the child fading in, which is normally drawn on top. The
/// `bottomChild` is the child fading out, normally drawn on the bottom.
///
/// For good performance, the returned widget tree should contain both the
/// `topChild` and the `bottomChild`; the depth of the tree, and the types of
/// the widgets in the tree, from the returned widget to each of the children
/// should be the same; and where there is a widget with multiple children, the
/// top child and the bottom child should be keyed using the provided
/// `topChildKey` and `bottomChildKey` keys respectively.
///
/// ## Sample code
///
/// ```dart
/// Widget defaultLayoutBuilder(Widget topChild, Key topChildKey, Widget bottomChild, Key bottomChildKey) {
///   return new Stack(
///     fit: StackFit.loose,
///     children: <Widget>[
///       new Positioned(
///         key: bottomChildKey,
///         left: 0.0,
///         top: 0.0,
///         right: 0.0,
///         child: bottomChild,
///       ),
///       new Positioned(
///         key: topChildKey,
///         child: topChild,
///       )
///     ],
///   );
/// }
/// ```
60
typedef Widget AnimatedCrossFadeBuilder(Widget topChild, Key topChildKey, Widget bottomChild, Key bottomChildKey);
61

62 63 64 65 66
/// A widget that cross-fades between two given children and animates itself
/// between their sizes.
///
/// The animation is controlled through the [crossFadeState] parameter.
/// [firstCurve] and [secondCurve] represent the opacity curves of the two
67 68
/// children. The [firstCurve] is inverted, i.e. it fades out when providing a
/// growing curve like [Curves.linear]. The [sizeCurve] is the curve used to
69 70
/// animate between the size of the fading-out child and the size of the
/// fading-in child.
71 72 73 74 75
///
/// This widget is intended to be used to fade a pair of widgets with the same
/// width. In the case where the two children have different heights, the
/// animation crops overflowing children during the animation by aligning their
/// top edge, which means that the bottom will be clipped.
76
///
77 78 79 80
/// The animation is automatically triggered when an existing
/// [AnimatedCrossFade] is rebuilt with a different value for the
/// [crossFadeState] property.
///
81 82 83
/// ## Sample code
///
/// This code fades between two representations of the Flutter logo. It depends
84
/// on a boolean field `_first`; when `_first` is true, the first logo is shown,
85 86 87
/// otherwise the second logo is shown. When the field changes state, the
/// [AnimatedCrossFade] widget cross-fades between the two forms of the logo
/// over three seconds.
88 89 90 91 92 93
///
/// ```dart
/// new AnimatedCrossFade(
///   duration: const Duration(seconds: 3),
///   firstChild: const FlutterLogo(style: FlutterLogoStyle.horizontal, size: 100.0),
///   secondChild: const FlutterLogo(style: FlutterLogoStyle.stacked, size: 100.0),
94
///   crossFadeState: _first ? CrossFadeState.showFirst : CrossFadeState.showSecond,
95 96 97 98 99 100 101
/// )
/// ```
///
/// See also:
///
///  * [AnimatedSize], the lower-level widget which [AnimatedCrossFade] uses to
///    automatically change size.
102
///  * [AnimatedSwitcher], which switches out a child for a new one with a
103
///    customizable transition.
104
class AnimatedCrossFade extends StatefulWidget {
105
  /// Creates a cross-fade animation widget.
106 107 108 109
  ///
  /// The [duration] of the animation is the same for all components (fade in,
  /// fade out, and size), and you can pass [Interval]s instead of [Curve]s in
  /// order to have finer control, e.g., creating an overlap between the fades.
110 111
  ///
  /// All the arguments other than [key] must be non-null.
112
  const AnimatedCrossFade({
113
    Key key,
114 115
    @required this.firstChild,
    @required this.secondChild,
116 117 118 119
    this.firstCurve = Curves.linear,
    this.secondCurve = Curves.linear,
    this.sizeCurve = Curves.linear,
    this.alignment = Alignment.topCenter,
120
    @required this.crossFadeState,
121
    @required this.duration,
122
    this.layoutBuilder = defaultLayoutBuilder,
123 124 125
  }) : assert(firstChild != null),
       assert(secondChild != null),
       assert(firstCurve != null),
126 127
       assert(secondCurve != null),
       assert(sizeCurve != null),
128 129 130 131
       assert(alignment != null),
       assert(crossFadeState != null),
       assert(duration != null),
       assert(layoutBuilder != null),
132
       super(key: key);
133

Ian Hickson's avatar
Ian Hickson committed
134 135 136
  /// The child that is visible when [crossFadeState] is
  /// [CrossFadeState.showFirst]. It fades out when transitioning
  /// [crossFadeState] from [CrossFadeState.showFirst] to
137
  /// [CrossFadeState.showSecond] and vice versa.
138 139
  final Widget firstChild;

Ian Hickson's avatar
Ian Hickson committed
140 141 142
  /// The child that is visible when [crossFadeState] is
  /// [CrossFadeState.showSecond]. It fades in when transitioning
  /// [crossFadeState] from [CrossFadeState.showFirst] to
143
  /// [CrossFadeState.showSecond] and vice versa.
144 145
  final Widget secondChild;

146
  /// The child that will be shown when the animation has completed.
147 148 149 150 151 152
  final CrossFadeState crossFadeState;

  /// The duration of the whole orchestrated animation.
  final Duration duration;

  /// The fade curve of the first child.
153 154
  ///
  /// Defaults to [Curves.linear].
155 156 157
  final Curve firstCurve;

  /// The fade curve of the second child.
158 159
  ///
  /// Defaults to [Curves.linear].
160 161 162
  final Curve secondCurve;

  /// The curve of the animation between the two children's sizes.
163 164
  ///
  /// Defaults to [Curves.linear].
165 166
  final Curve sizeCurve;

167 168
  /// How the children should be aligned while the size is animating.
  ///
169
  /// Defaults to [Alignment.topCenter].
170 171 172 173 174 175 176
  ///
  /// See also:
  ///
  ///  * [Alignment], a class with convenient constants typically used to
  ///    specify an [AlignmentGeometry].
  ///  * [AlignmentDirectional], like [Alignment] for specifying alignments
  ///    relative to text direction.
177
  final AlignmentGeometry alignment;
178

179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221
  /// A builder that positions the [firstChild] and [secondChild] widgets.
  ///
  /// The widget returned by this method is wrapped in an [AnimatedSize].
  ///
  /// By default, this uses [AnimatedCrossFade.defaultLayoutBuilder], which uses
  /// a [Stack] and aligns the `bottomChild` to the top of the stack while
  /// providing the `topChild` as the non-positioned child to fill the provided
  /// constraints. This works well when the [AnimatedCrossFade] is in a position
  /// to change size and when the children are not flexible. However, if the
  /// children are less fussy about their sizes (for example a
  /// [CircularProgressIndicator] inside a [Center]), or if the
  /// [AnimatedCrossFade] is being forced to a particular size, then it can
  /// result in the widgets jumping about when the cross-fade state is changed.
  final AnimatedCrossFadeBuilder layoutBuilder;

  /// The default layout algorithm used by [AnimatedCrossFade].
  ///
  /// The top child is placed in a stack that sizes itself to match the top
  /// child. The bottom child is positioned at the top of the same stack, sized
  /// to fit its width but without forcing the height. The stack is then
  /// clipped.
  ///
  /// This is the default value for [layoutBuilder]. It implements
  /// [AnimatedCrossFadeBuilder].
  static Widget defaultLayoutBuilder(Widget topChild, Key topChildKey, Widget bottomChild, Key bottomChildKey) {
    return new Stack(
      overflow: Overflow.visible,
      children: <Widget>[
        new Positioned(
          key: bottomChildKey,
          left: 0.0,
          top: 0.0,
          right: 0.0,
          child: bottomChild,
        ),
        new Positioned(
          key: topChildKey,
          child: topChild,
        )
      ],
    );
  }

222 223
  @override
  _AnimatedCrossFadeState createState() => new _AnimatedCrossFadeState();
224 225

  @override
226 227 228 229
  void debugFillProperties(DiagnosticPropertiesBuilder properties) {
    super.debugFillProperties(properties);
    properties.add(new EnumProperty<CrossFadeState>('crossFadeState', crossFadeState));
    properties.add(new DiagnosticsProperty<AlignmentGeometry>('alignment', alignment, defaultValue: Alignment.topCenter));
230
  }
231 232
}

233
class _AnimatedCrossFadeState extends State<AnimatedCrossFade> with TickerProviderStateMixin {
234 235 236 237
  AnimationController _controller;
  Animation<double> _firstAnimation;
  Animation<double> _secondAnimation;

238 239 240
  @override
  void initState() {
    super.initState();
241 242
    _controller = new AnimationController(duration: widget.duration, vsync: this);
    if (widget.crossFadeState == CrossFadeState.showSecond)
243
      _controller.value = 1.0;
244 245
    _firstAnimation = _initAnimation(widget.firstCurve, true);
    _secondAnimation = _initAnimation(widget.secondCurve, false);
246 247
  }

248
  Animation<double> _initAnimation(Curve curve, bool inverted) {
249
    Animation<double> animation = new CurvedAnimation(
250
      parent: _controller,
251
      curve: curve,
252 253
    );

254 255
    if (inverted) {
      animation = new Tween<double>(
256 257
        begin: 1.0,
        end: 0.0,
258 259 260 261 262 263 264 265 266 267 268
      ).animate(animation);
    }

    animation.addStatusListener((AnimationStatus status) {
      setState(() {
        // Trigger a rebuild because it depends on _isTransitioning, which
        // changes its value together with animation status.
      });
    });

    return animation;
269 270 271 272 273 274 275 276 277
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
278 279 280 281 282 283 284 285 286 287
  void didUpdateWidget(AnimatedCrossFade oldWidget) {
    super.didUpdateWidget(oldWidget);
    if (widget.duration != oldWidget.duration)
      _controller.duration = widget.duration;
    if (widget.firstCurve != oldWidget.firstCurve)
      _firstAnimation = _initAnimation(widget.firstCurve, true);
    if (widget.secondCurve != oldWidget.secondCurve)
      _secondAnimation = _initAnimation(widget.secondCurve, false);
    if (widget.crossFadeState != oldWidget.crossFadeState) {
      switch (widget.crossFadeState) {
288 289 290 291 292 293 294 295 296 297
        case CrossFadeState.showFirst:
          _controller.reverse();
          break;
        case CrossFadeState.showSecond:
          _controller.forward();
          break;
      }
    }
  }

298 299
  /// Whether we're in the middle of cross-fading this frame.
  bool get _isTransitioning => _controller.status == AnimationStatus.forward || _controller.status == AnimationStatus.reverse;
300

301 302
  @override
  Widget build(BuildContext context) {
303 304
    const Key kFirstChildKey = ValueKey<CrossFadeState>(CrossFadeState.showFirst);
    const Key kSecondChildKey = ValueKey<CrossFadeState>(CrossFadeState.showSecond);
305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328
    final bool transitioningForwards = _controller.status == AnimationStatus.completed || _controller.status == AnimationStatus.forward;

    Key topKey;
    Widget topChild;
    Animation<double> topAnimation;
    Key bottomKey;
    Widget bottomChild;
    Animation<double> bottomAnimation;
    if (transitioningForwards) {
      topKey = kSecondChildKey;
      topChild = widget.secondChild;
      topAnimation = _secondAnimation;
      bottomKey = kFirstChildKey;
      bottomChild = widget.firstChild;
      bottomAnimation = _firstAnimation;
    } else {
      topKey = kFirstChildKey;
      topChild = widget.firstChild;
      topAnimation = _firstAnimation;
      bottomKey = kSecondChildKey;
      bottomChild = widget.secondChild;
      bottomAnimation = _secondAnimation;
    }

329 330 331 332 333 334 335 336
    bottomChild = new TickerMode(
      key: bottomKey,
      enabled: _isTransitioning,
      child: new ExcludeSemantics(
        excluding: true, // Always exclude the semantics of the widget that's fading out.
        child: new FadeTransition(
          opacity: bottomAnimation,
          child: bottomChild,
337
        ),
338
      ),
339 340 341 342 343 344 345 346 347
    );
    topChild = new TickerMode(
      key: topKey,
      enabled: true, // Top widget always has its animations enabled.
      child: new ExcludeSemantics(
        excluding: false, // Always publish semantics for the widget that's fading in.
        child: new FadeTransition(
          opacity: topAnimation,
          child: topChild,
348
        ),
349
      ),
350
    );
351 352
    return new ClipRect(
      child: new AnimatedSize(
353
        alignment: widget.alignment,
354 355
        duration: widget.duration,
        curve: widget.sizeCurve,
356
        vsync: this,
357
        child: widget.layoutBuilder(topChild, topKey, bottomChild, bottomKey),
358
      ),
359 360
    );
  }
361 362

  @override
363
  void debugFillProperties(DiagnosticPropertiesBuilder description) {
364 365 366
    super.debugFillProperties(description);
    description.add(new EnumProperty<CrossFadeState>('crossFadeState', widget.crossFadeState));
    description.add(new DiagnosticsProperty<AnimationController>('controller', _controller, showName: false));
367
    description.add(new DiagnosticsProperty<AlignmentGeometry>('alignment', widget.alignment, defaultValue: Alignment.topCenter));
368
  }
369
}