1// Copyright 2014 The Flutter Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5/// The Flutter animation system.
6///
7/// To use, import `package:flutter/animation.dart`.
8///
9/// This library provides basic building blocks for implementing animations in
10/// Flutter. Other layers of the framework use these building blocks to provide
11/// advanced animation support for applications. For example, the widget library
12/// includes [ImplicitlyAnimatedWidget]s and [AnimatedWidget]s that make it easy
13/// to animate certain properties of a [Widget]. If those animated widgets are
14/// not sufficient for a given use case, the basic building blocks provided by
15/// this library can be used to implement custom animated effects.
16///
17/// This library depends only on core Dart libraries and the `physics.dart`
18/// library.
19///
20///
21/// ### Foundations: the Animation class
22///
23/// Flutter represents an animation as a value that changes over a given
24/// duration, and that value may be of any type. For example, it could be a
25/// [double] indicating the current opacity of a [Widget] as it fades out. Or,
26/// it could be the current background [Color] of a widget that transitions
27/// smoothly from one color to another. The current value of an animation is
28/// represented by an [Animation] object, which is the central class of the
29/// animation library. In addition to the current animation value, the
30/// [Animation] object also stores the current [AnimationStatus]. The status
31/// indicates whether the animation is currently conceptually running from the
32/// beginning to the end or the other way around. It may also indicate that the
33/// animation is currently stopped at the beginning or the end.
34///
35/// Other objects can register listeners on an [Animation] to be informed
36/// whenever the animation value and/or the animation status changes. A [Widget]
37/// may register such a *value* listener via [Animation.addListener] to rebuild
38/// itself with the current animation value whenever that value changes. For
39/// example, a widget might listen to an animation to update its opacity to the
40/// animation's value every time that value changes. Likewise, registering a
41/// *status* listener via [Animation.addStatusListener] may be useful to trigger
42/// another action when the current animation has ended.
43///
44/// As an example, the following video shows the changes over time in the
45/// current animation status and animation value for the opacity animation of a
46/// widget. This [Animation] is driven by an [AnimationController] (see next
47/// section). Before the animation triggers, the animation status is "dismissed"
48/// and the value is 0.0. As the value runs from 0.0 to 1.0 to fade in the
49/// widget, the status changes to "forward". When the widget is fully faded in
50/// at an animation value of 1.0 the status is "completed". When the animation
51/// triggers again to fade the widget back out, the animation status changes to
52/// "reverse" and the animation value runs back to 0.0. At that point the widget
53/// is fully faded out and the animation status switches back to "dismissed"
54/// until the animation is triggered again.
55///
56/// {@animation 420 100 https://flutter.github.io/assets-for-api-docs/assets/animation/animation_status_value.mp4}
57///
58/// Although you can't instantiate [Animation] directly (it is an abstract
59/// class), you can create one using an [AnimationController].
60///
61///
62/// ### Powering animations: AnimationController
63///
64/// An [AnimationController] is a special kind of [Animation] that advances its
65/// animation value whenever the device running the application is ready to
66/// display a new frame (typically, this rate is around 60 values per second).
67/// An [AnimationController] can be used wherever an [Animation] is expected. As
68/// the name implies, an [AnimationController] also provides control over its
69/// [Animation]: It implements methods to stop the animation at any time and to
70/// run it forward as well as in the reverse direction.
71///
72/// By default, an [AnimationController] increases its animation value linearly
73/// over the given duration from 0.0 to 1.0 when run in the forward direction.
74/// For many use cases you might want the value to be of a different type,
75/// change the range of the animation values, or change how the animation moves
76/// between values. This is achieved by wrapping the animation: Wrapping it in
77/// an [Animatable] (see below) changes the range of animation values to a
78/// different range or type (for example to animate [Color]s or [Rect]s).
79/// Furthermore, a [Curve] can be applied to the animation by wrapping it in a
80/// [CurvedAnimation]. Instead of linearly increasing the animation value, a
81/// curved animation changes its value according to the provided curve. The
82/// framework ships with many built-in curves (see [Curves]). As an example,
83/// [Curves.easeOutCubic] increases the animation value quickly at the beginning
84/// of the animation and then slows down until the target value is reached:
85///
86/// {@animation 464 192 https://flutter.github.io/assets-for-api-docs/assets/animation/curve_ease_out_cubic.mp4}
87///
88///
89/// ### Animating different types: Animatable
90///
91/// An `Animatable<T>` is an object that takes an `Animation<double>` as input
92/// and produces a value of type `T`. Objects of these types can be used to
93/// translate the animation value range of an [AnimationController] (or any
94/// other [Animation] of type [double]) to a different range. That new range
95/// doesn't even have to be of type double anymore. With the help of an
96/// [Animatable] like a [Tween] or a [TweenSequence] (see sections below) an
97/// [AnimationController] can be used to smoothly transition [Color]s, [Rect]s,
98/// [Size]s and many more types from one value to another over a given duration.
99///
100///
101/// ### Interpolating values: Tweens
102///
103/// A [Tween] is applied to an [Animation] of type [double] to change the
104/// range and type of the animation value. For example, to transition the
105/// background of a [Widget] smoothly between two [Color]s, a [ColorTween] can
106/// be used. Each [Tween] specifies a start and an end value. As the animation
107/// value of the [Animation] powering the [Tween] progresses from 0.0 to 1.0 it
108/// produces interpolated values between its start and end value. The values
109/// produced by the [Tween] usually move closer and closer to its end value as
110/// the animation value of the powering [Animation] approaches 1.0.
111///
112/// The following video shows example values produced by an [IntTween], a
113/// `Tween<double>`, and a [ColorTween] as the animation value runs from 0.0 to
114/// 1.0 and back to 0.0:
115///
116/// {@animation 530 150 https://flutter.github.io/assets-for-api-docs/assets/animation/tweens.mp4}
117///
118/// An [Animation] or [AnimationController] can power multiple [Tween]s. For
119/// example, to animate the size and the color of a widget in parallel, create
120/// one [AnimationController] that powers a [SizeTween] and a [ColorTween].
121///
122/// The framework ships with many [Tween] subclasses ([IntTween], [SizeTween],
123/// [RectTween], etc.) to animate common properties.
124///
125///
126/// ### Staggered animations: TweenSequences
127///
128/// A [TweenSequence] can help animate a given property smoothly in stages. Each
129/// [Tween] in the sequence is responsible for a different stage and has an
130/// associated weight. When the animation runs, the stages execute one after
131/// another. For example, let's say you want to animate the background of a
132/// widget from yellow to green and then, after a short pause, to red. For this
133/// you can specify three tweens within a tween sequence: One [ColorTween]
134/// animating from yellow to green, one [ConstantTween] that just holds the color
135/// green, and another [ColorTween] animating from green to red. For each
136/// tween you need to pick a weight indicating the ratio of time spent on that
137/// tween compared to all other tweens. If we assign a weight of 2 to both of
138/// the [ColorTween]s and a weight of 1 to the [ConstantTween] the transition
139/// described by the [ColorTween]s would take twice as long as the
140/// [ConstantTween]. A [TweenSequence] is driven by an [Animation] just like a
141/// regular [Tween]: As the powering [Animation] runs from 0.0 to 1.0 the
142/// [TweenSequence] runs through all of its stages.
143///
144/// The following video shows the animation described in the previous paragraph:
145///
146/// {@animation 646 250 https://flutter.github.io/assets-for-api-docs/assets/animation/tween_sequence.mp4}
147///
148///
149/// See also:
150///
151/// * [Introduction to animations](https://docs.flutter.dev/ui/animations)
152/// on flutter.dev.
153/// * [Animations tutorial](https://docs.flutter.dev/ui/animations/tutorial)
154/// on flutter.dev.
155/// * [Sample app](https://github.com/flutter/samples/tree/main/animations),
156/// which showcases Flutter's animation features.
157/// * [ImplicitlyAnimatedWidget] and its subclasses, which are [Widget]s that
158/// implicitly animate changes to their properties.
159/// * [AnimatedWidget] and its subclasses, which are [Widget]s that take an
160/// explicit [Animation] to animate their properties.
161///
162/// @docImport 'package:flutter/material.dart';
163library animation;
164
165// AnimationController can throw TickerCanceled
166export 'package:flutter/scheduler.dart' show TickerCanceled;
167
168export 'src/animation/animation.dart';
169export 'src/animation/animation_controller.dart';
170export 'src/animation/animation_style.dart';
171export 'src/animation/animations.dart';
172export 'src/animation/curves.dart';
173export 'src/animation/listener_helpers.dart';
174export 'src/animation/tween.dart';
175export 'src/animation/tween_sequence.dart';
176