// 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. /// The Flutter animation system. /// /// To use, import `package:flutter/animation.dart`. /// /// This library provides basic building blocks for implementing animations in /// Flutter. Other layers of the framework use these building blocks to provide /// advanced animation support for applications. For example, the widget library /// includes [ImplicitlyAnimatedWidget]s and [AnimatedWidget]s that make it easy /// to animate certain properties of a [Widget]. If those animated widgets are /// not sufficient for a given use case, the basic building blocks provided by /// this library can be used to implement custom animated effects. /// /// This library depends only on core Dart libraries and the `physics.dart` /// library. /// /// /// ### Foundations: the Animation class /// /// Flutter represents an animation as a value that changes over a given /// duration, and that value may be of any type. For example, it could be a /// [double] indicating the current opacity of a [Widget] as it fades out. Or, /// it could be the current background [Color] of a widget that transitions /// smoothly from one color to another. The current value of an animation is /// represented by an [Animation] object, which is the central class of the /// animation library. In addition to the current animation value, the /// [Animation] object also stores the current [AnimationStatus]. The status /// indicates whether the animation is currently conceptually running from the /// beginning to the end or the other way around. It may also indicate that the /// animation is currently stopped at the beginning or the end. /// /// Other objects can register listeners on an [Animation] to be informed /// whenever the animation value and/or the animation status changes. A [Widget] /// may register such a *value* listener via [Animation.addListener] to rebuild /// itself with the current animation value whenever that value changes. For /// example, a widget might listen to an animation to update its opacity to the /// animation's value every time that value changes. Likewise, registering a /// *status* listener via [Animation.addStatusListener] may be useful to trigger /// another action when the current animation has ended. /// /// As an example, the following video shows the changes over time in the /// current animation status and animation value for the opacity animation of a /// widget. This [Animation] is driven by an [AnimationController] (see next /// section). Before the animation triggers, the animation status is "dismissed" /// and the value is 0.0. As the value runs from 0.0 to 1.0 to fade in the /// widget, the status changes to "forward". When the widget is fully faded in /// at an animation value of 1.0 the status is "completed". When the animation /// triggers again to fade the widget back out, the animation status changes to /// "reverse" and the animation value runs back to 0.0. At that point the widget /// is fully faded out and the animation status switches back to "dismissed" /// until the animation is triggered again. /// /// {@animation 420 100 https://flutter.github.io/assets-for-api-docs/assets/animation/animation_status_value.mp4} /// /// Although you can't instantiate [Animation] directly (it is an abstract /// class), you can create one using an [AnimationController]. /// /// /// ### Powering animations: AnimationController /// /// An [AnimationController] is a special kind of [Animation] that advances its /// animation value whenever the device running the application is ready to /// display a new frame (typically, this rate is around 60 values per second). /// An [AnimationController] can be used wherever an [Animation] is expected. As /// the name implies, an [AnimationController] also provides control over its /// [Animation]: It implements methods to stop the animation at any time and to /// run it forward as well as in the reverse direction. /// /// By default, an [AnimationController] increases its animation value linearly /// over the given duration from 0.0 to 1.0 when run in the forward direction. /// For many use cases you might want the value to be of a different type, /// change the range of the animation values, or change how the animation moves /// between values. This is achieved by wrapping the animation: Wrapping it in /// an [Animatable] (see below) changes the range of animation values to a /// different range or type (for example to animate [Color]s or [Rect]s). /// Furthermore, a [Curve] can be applied to the animation by wrapping it in a /// [CurvedAnimation]. Instead of linearly increasing the animation value, a /// curved animation changes its value according to the provided curve. The /// framework ships with many built-in curves (see [Curves]). As an example, /// [Curves.easeOutCubic] increases the animation value quickly at the beginning /// of the animation and then slows down until the target value is reached: /// /// {@animation 464 192 https://flutter.github.io/assets-for-api-docs/assets/animation/curve_ease_out_cubic.mp4} /// /// /// ### Animating different types: Animatable /// /// An `Animatable<T>` is an object that takes an `Animation<double>` as input /// and produces a value of type `T`. Objects of these types can be used to /// translate the animation value range of an [AnimationController] (or any /// other [Animation] of type [double]) to a different range. That new range /// doesn't even have to be of type double anymore. With the help of an /// [Animatable] like a [Tween] or a [TweenSequence] (see sections below) an /// [AnimationController] can be used to smoothly transition [Color]s, [Rect]s, /// [Size]s and many more types from one value to another over a given duration. /// /// /// ### Interpolating values: Tweens /// /// A [Tween] is applied to an [Animation] of type [double] to change the /// range and type of the animation value. For example, to transition the /// background of a [Widget] smoothly between two [Color]s, a [ColorTween] can /// be used. Each [Tween] specifies a start and an end value. As the animation /// value of the [Animation] powering the [Tween] progresses from 0.0 to 1.0 it /// produces interpolated values between its start and end value. The values /// produced by the [Tween] usually move closer and closer to its end value as /// the animation value of the powering [Animation] approaches 1.0. /// /// The following video shows example values produced by an [IntTween], a /// `Tween<double>`, and a [ColorTween] as the animation value runs from 0.0 to /// 1.0 and back to 0.0: /// /// {@animation 530 150 https://flutter.github.io/assets-for-api-docs/assets/animation/tweens.mp4} /// /// An [Animation] or [AnimationController] can power multiple [Tween]s. For /// example, to animate the size and the color of a widget in parallel, create /// one [AnimationController] that powers a [SizeTween] and a [ColorTween]. /// /// The framework ships with many [Tween] subclasses ([IntTween], [SizeTween], /// [RectTween], etc.) to animate common properties. /// /// /// ### Staggered animations: TweenSequences /// /// A [TweenSequence] can help animate a given property smoothly in stages. Each /// [Tween] in the sequence is responsible for a different stage and has an /// associated weight. When the animation runs, the stages execute one after /// another. For example, let's say you want to animate the background of a /// widget from yellow to green and then, after a short pause, to red. For this /// you can specify three tweens within a tween sequence: One [ColorTween] /// animating from yellow to green, one [ConstantTween] that just holds the color /// green, and another [ColorTween] animating from green to red. For each /// tween you need to pick a weight indicating the ratio of time spent on that /// tween compared to all other tweens. If we assign a weight of 2 to both of /// the [ColorTween]s and a weight of 1 to the [ConstantTween] the transition /// described by the [ColorTween]s would take twice as long as the /// [ConstantTween]. A [TweenSequence] is driven by an [Animation] just like a /// regular [Tween]: As the powering [Animation] runs from 0.0 to 1.0 the /// [TweenSequence] runs through all of its stages. /// /// The following video shows the animation described in the previous paragraph: /// /// {@animation 646 250 https://flutter.github.io/assets-for-api-docs/assets/animation/tween_sequence.mp4} /// /// /// See also: /// /// * [Introduction to animations](https://flutter.dev/docs/development/ui/animations) /// on flutter.dev. /// * [Animations tutorial](https://flutter.dev/docs/development/ui/animations/tutorial) /// on flutter.dev. /// * [Sample app](https://github.com/flutter/samples/tree/master/animations), /// which showcases Flutter's animation features. /// * [ImplicitlyAnimatedWidget] and its subclasses, which are [Widget]s that /// implicitly animate changes to their properties. /// * [AnimatedWidget] and its subclasses, which are [Widget]s that take an /// explicit [Animation] to animate their properties. library animation; export 'src/animation/animation.dart'; export 'src/animation/animation_controller.dart'; export 'src/animation/animations.dart'; export 'src/animation/curves.dart'; export 'src/animation/listener_helpers.dart'; export 'src/animation/tween.dart'; export 'src/animation/tween_sequence.dart';