From cbd0aa5bd3812ede6b010ecd61915911bf565160 Mon Sep 17 00:00:00 2001 From: Quddus Chong Date: Thu, 17 Mar 2016 15:10:14 -0700 Subject: [PATCH] docs: Updated descriptions for the Animation APIs. --- .../src/animation/animation_controller.dart | 15 ++++++++++---- .../flutter/lib/src/animation/animations.dart | 20 ++++++++++++++++--- packages/flutter/lib/src/animation/tween.dart | 12 +++++++++++ 3 files changed, 40 insertions(+), 7 deletions(-) diff --git a/packages/flutter/lib/src/animation/animation_controller.dart b/packages/flutter/lib/src/animation/animation_controller.dart index 5451216e13..2a5b3ff96c 100644 --- a/packages/flutter/lib/src/animation/animation_controller.dart +++ b/packages/flutter/lib/src/animation/animation_controller.dart @@ -24,10 +24,17 @@ enum _AnimationDirection { /// A controller for an animation. /// -/// An animation controller can drive an animation forward or backward and can -/// set the animation to a particular value. The controller also defines the -/// bounds of the animation and can drive an animation using a physics -/// simulation. +/// This class lets you perform tasks such as: +/// +/// * Play an animation [forward] or in [reverse], or [stop] an animation. +/// * Set the animation to a specific [value]. +/// * Define the [upperBound] and [lowerBound] values of an animation. +/// * Create a [fling] animation effect using a physics simulation. +/// +/// By default, an [AnimationController] linearly produces values that range from 0.0 to 1.0, during +/// a given duration. The animation controller generates a new value whenever the device running +/// your app is ready to display a new frame (typically, this rate is around 60 values per second). +/// class AnimationController extends Animation with AnimationEagerListenerMixin, AnimationLocalListenersMixin, AnimationLocalStatusListenersMixin { diff --git a/packages/flutter/lib/src/animation/animations.dart b/packages/flutter/lib/src/animation/animations.dart index 8daca9aef7..e92a6deedc 100644 --- a/packages/flutter/lib/src/animation/animations.dart +++ b/packages/flutter/lib/src/animation/animations.dart @@ -236,9 +236,23 @@ class ReverseAnimation extends Animation /// An animation that applies a curve to another animation. /// -/// [CurvedAnimation] is useful when you wish to apply a [Curve] and you already -/// have the underlying animation object. If you don't yet have an animation and -/// want to apply a [Curve] to a [Tween], consider using [CurveTween]. +/// [CurvedAnimation] is useful when you want to apply a non-linear [Curve] to +/// an animation object wrapped in the [CurvedAnimation]. +/// +/// For example, the following code snippet shows how you can apply a curve to a linear animation +/// produced by an [AnimationController]: +/// +/// ``` dart +/// final AnimationController controller = +/// new AnimationController(duration: const Duration(milliseconds: 500)); +/// final CurvedAnimation animation = +/// new CurvedAnimation(parent: controller, curve: Curves.ease); +///``` +/// Depending on the given curve, the output of the [CurvedAnimation] could have a wider range +/// than its input. For example, elastic curves such as [Curves.elasticIn] will significantly +/// overshoot or undershoot the default range of 0.0 to 1.0. +/// +/// If you want to apply a [Curve] to a [Tween], consider using [CurveTween]. class CurvedAnimation extends Animation with AnimationWithParentMixin { CurvedAnimation({ this.parent, diff --git a/packages/flutter/lib/src/animation/tween.dart b/packages/flutter/lib/src/animation/tween.dart index 6dd9c39c0b..405d35377e 100644 --- a/packages/flutter/lib/src/animation/tween.dart +++ b/packages/flutter/lib/src/animation/tween.dart @@ -55,6 +55,16 @@ class _ChainedEvaluation extends Animatable { } /// A linear interpolation between a beginning and ending value. +/// +/// [Tween] is useful if you want to interpolate across a range. +/// +/// To use a [Tween] object with an animation, call the [Tween] object's `animate()` method and +/// pass it the [Animation] object that you want to modify. +/// +/// You can chain [Tween] objects together using the `chain()` method, so that a single +/// [Animation] object is configured by multiple [Tween] objects called in succession. This is +/// different than calling the `animate()` method twice, which results in two [Animation] +/// separate objects, each configured with a single [Tween]. class Tween extends Animatable { Tween({ this.begin, this.end }); @@ -68,6 +78,8 @@ class Tween extends Animatable { T lerp(double t) => begin + (end - begin) * t; /// Returns the interpolated value for the current value of the given animation. + /// + /// This method returns `begin` and `end` when the animation values are 0.0 or 1.0, respectively. @override T evaluate(Animation animation) { if (end == null)