packages/flutter/lib/animation.dart - mirrors/flutter - Git at Google

 // 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;

 // AnimationController can throw TickerCanceled
 export 'package:flutter/scheduler.dart' show TickerCanceled;

 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';
	// 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;

	// AnimationController can throw TickerCanceled
	export 'package:flutter/scheduler.dart' show TickerCanceled;

	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';