DynamicAnimation

public abstract class DynamicAnimation<T extends DynamicAnimation<T>>

Known direct subclasses
FlingAnimation

Fling animation is an animation that continues an initial momentum (most often from gesture velocity) and gradually slows down.
SpringAnimation

SpringAnimation is an animation that is driven by a SpringForce.

This class is the base class of physics-based animations. It manages the animation's lifecycle such as start and cancel. This base class also handles the common setup for all the subclass animations. For example, DynamicAnimation supports adding OnAnimationEndListener and OnAnimationUpdateListener so that the important animation events can be observed through the callbacks. The start conditions for any subclass of DynamicAnimation can be set using setStartValue and setStartVelocity.

Parameters
<T extends DynamicAnimation<T>>

subclass of DynamicAnimation

Summary

Nested types

An animation listener that receives end notifications from an animation.

Implementors of this interface can add themselves as update listeners to an DynamicAnimation instance to receive callbacks on every animation frame, after the current frame's values have been calculated for that DynamicAnimation.

ViewProperty holds the access of a property of a View.

Constants
static final DynamicAnimation.ViewProperty

View's alpha property.
static final float

The minimum visible change in alpha that can be visible to users.
static final float

The minimum visible change in pixels that can be visible to users.
static final float

The minimum visible change in degrees that can be visible to users.
static final float

The minimum visible change in scale that can be visible to users.
static final DynamicAnimation.ViewProperty

View's rotation property.
static final DynamicAnimation.ViewProperty

View's rotationX property.
static final DynamicAnimation.ViewProperty

View's rotationY property.
static final DynamicAnimation.ViewProperty

View's scaleX property.
static final DynamicAnimation.ViewProperty

View's scaleY property.
static final DynamicAnimation.ViewProperty

View's scrollX property.
static final DynamicAnimation.ViewProperty

View's scrollY property.
static final DynamicAnimation.ViewProperty

View's translationX property.
static final DynamicAnimation.ViewProperty

View's translationY property.
static final DynamicAnimation.ViewProperty

View's translationZ property.
static final DynamicAnimation.ViewProperty

View's x property.
static final DynamicAnimation.ViewProperty

View's y property.
static final DynamicAnimation.ViewProperty

View's z property.

Public methods
T

Adds an end listener to the animation for receiving onAnimationEnd callbacks.
T

Adds an update listener to the animation for receiving per-frame animation update callbacks.
void

Cancels the on-going animation.
float

Returns the minimum change in the animation property that could be visibly different to users.
boolean

Returns whether the animation is currently running.
void

Removes the end listener from the animation, so as to stop receiving animation end callbacks.
void

Removes the update listener from the animation, so as to stop receiving animation update callbacks.
T
setMaxValue(float max)

Sets the max value of the animation.
T
setMinValue(float min)

Sets the min value of the animation.
T
setMinimumVisibleChange(
    @FloatRange(from = 0.0, fromInclusive = false) float minimumVisibleChange
)

This method sets the minimal change of animation value that is visible to users, which helps determine a reasonable threshold for the animation's termination condition.
T
setStartValue(float startValue)

Sets the start value of the animation.
T
setStartVelocity(float startVelocity)

Start velocity of the animation.
void

Starts an animation.

Constants

ALPHA

Added in 1.0.0
public static final DynamicAnimation.ViewProperty ALPHA

View's alpha property.

MIN_VISIBLE_CHANGE_ALPHA

Added in 1.0.0
public static final float MIN_VISIBLE_CHANGE_ALPHA = 0.00390625f

The minimum visible change in alpha that can be visible to users.

MIN_VISIBLE_CHANGE_PIXELS

Added in 1.0.0
public static final float MIN_VISIBLE_CHANGE_PIXELS = 1.0f

The minimum visible change in pixels that can be visible to users.

MIN_VISIBLE_CHANGE_ROTATION_DEGREES

Added in 1.0.0
public static final float MIN_VISIBLE_CHANGE_ROTATION_DEGREES = 0.1f

The minimum visible change in degrees that can be visible to users.

MIN_VISIBLE_CHANGE_SCALE

Added in 1.0.0
public static final float MIN_VISIBLE_CHANGE_SCALE = 0.002f

The minimum visible change in scale that can be visible to users.

ROTATION

Added in 1.0.0
public static final DynamicAnimation.ViewProperty ROTATION

View's rotation property.

ROTATION_X

Added in 1.0.0
public static final DynamicAnimation.ViewProperty ROTATION_X

View's rotationX property.

ROTATION_Y

Added in 1.0.0
public static final DynamicAnimation.ViewProperty ROTATION_Y

View's rotationY property.

SCALE_X

Added in 1.0.0
public static final DynamicAnimation.ViewProperty SCALE_X

View's scaleX property.

SCALE_Y

Added in 1.0.0
public static final DynamicAnimation.ViewProperty SCALE_Y

View's scaleY property.

SCROLL_X

Added in 1.0.0
public static final DynamicAnimation.ViewProperty SCROLL_X

View's scrollX property.

SCROLL_Y

Added in 1.0.0
public static final DynamicAnimation.ViewProperty SCROLL_Y

View's scrollY property.

TRANSLATION_X

Added in 1.0.0
public static final DynamicAnimation.ViewProperty TRANSLATION_X

View's translationX property.

TRANSLATION_Y

Added in 1.0.0
public static final DynamicAnimation.ViewProperty TRANSLATION_Y

View's translationY property.

TRANSLATION_Z

Added in 1.0.0
public static final DynamicAnimation.ViewProperty TRANSLATION_Z

View's translationZ property.

X

Added in 1.0.0
public static final DynamicAnimation.ViewProperty X

View's x property.

Y

Added in 1.0.0
public static final DynamicAnimation.ViewProperty Y

View's y property.

Z

Added in 1.0.0
public static final DynamicAnimation.ViewProperty Z

View's z property.

Public methods

addEndListener

Added in 1.0.0
public T addEndListener(DynamicAnimation.OnAnimationEndListener listener)

Adds an end listener to the animation for receiving onAnimationEnd callbacks. If the listener is null or has already been added to the list of listeners for the animation, no op.

Parameters
DynamicAnimation.OnAnimationEndListener listener

the listener to be added
Returns
T

the animation to which the listener is added

addUpdateListener

Added in 1.0.0
public T addUpdateListener(DynamicAnimation.OnAnimationUpdateListener listener)

Adds an update listener to the animation for receiving per-frame animation update callbacks. If the listener is null or has already been added to the list of listeners for the animation, no op.

Note that update listener should only be added before the start of the animation.

Parameters
DynamicAnimation.OnAnimationUpdateListener listener

the listener to be added
Returns
T

the animation to which the listener is added
Throws
java.lang.UnsupportedOperationException

if the update listener is added after the animation has started

cancel

Added in 1.0.0
@MainThread
public void cancel()

Cancels the on-going animation. If the animation hasn't started, no op. Note that this method should only be called on main thread.

Throws
android.util.AndroidRuntimeException

if this method is not called on the main thread

getMinimumVisibleChange

Added in 1.0.0
public float getMinimumVisibleChange()

Returns the minimum change in the animation property that could be visibly different to users.

Returns
float

minimum change in property value that is visible to users

isRunning

Added in 1.0.0
public boolean isRunning()

Returns whether the animation is currently running.

Returns
boolean

true if the animation is currently running, false otherwise

removeEndListener

Added in 1.0.0
public void removeEndListener(DynamicAnimation.OnAnimationEndListener listener)

Removes the end listener from the animation, so as to stop receiving animation end callbacks.

Parameters
DynamicAnimation.OnAnimationEndListener listener

the listener to be removed

removeUpdateListener

Added in 1.0.0
public void removeUpdateListener(
    DynamicAnimation.OnAnimationUpdateListener listener
)

Removes the update listener from the animation, so as to stop receiving animation update callbacks.

Parameters
DynamicAnimation.OnAnimationUpdateListener listener

the listener to be removed

setMaxValue

Added in 1.0.0
public T setMaxValue(float max)

Sets the max value of the animation. Animations will not animate beyond their max value. Whether or not animation will come to an end when max value is reached is dependent on the child animation's implementation.

Parameters
float max

maximum value of the property to be animated
Returns
T

the Animation whose max value is being set

setMinValue

Added in 1.0.0
public T setMinValue(float min)

Sets the min value of the animation. Animations will not animate beyond their min value. Whether or not animation will come to an end when min value is reached is dependent on the child animation's implementation.

Parameters
float min

minimum value of the property to be animated
Returns
T

the Animation whose min value is being set

setMinimumVisibleChange

Added in 1.0.0
public T setMinimumVisibleChange(
    @FloatRange(from = 0.0, fromInclusive = false) float minimumVisibleChange
)

This method sets the minimal change of animation value that is visible to users, which helps determine a reasonable threshold for the animation's termination condition. It is critical to set the minimal visible change for custom properties (i.e. non-ViewPropertys) unless the custom property is in pixels.

For custom properties, this minimum visible change defaults to change in pixel (i.e. MIN_VISIBLE_CHANGE_PIXELS. It is recommended to adjust this value that is reasonable for the property to be animated. A general rule of thumb to calculate such a value is: minimum visible change = range of custom property value / corresponding pixel range. For example, if the property to be animated is a progress (from 0 to 100) that corresponds to a 200-pixel change. Then the min visible change should be 100 / 200. (i.e. 0.5).

It's not necessary to call this method when animating ViewPropertys, as the minimum visible change will be derived from the property. For example, if the property to be animated is in pixels (i.e. TRANSLATION_X, TRANSLATION_Y, TRANSLATION_Z, @SCROLL_X or SCROLL_Y), the default minimum visible change is 1 (pixel). For ROTATION, ROTATION_X or ROTATION_Y, the animation will use MIN_VISIBLE_CHANGE_ROTATION_DEGREES as the min visible change, which is 1/10. Similarly, the minimum visible change for alpha ( i.e. MIN_VISIBLE_CHANGE_ALPHA is defined as 1 / 256.

Parameters
@FloatRange(from = 0.0, fromInclusive = false) float minimumVisibleChange

minimum change in property value that is visible to users
Returns
T

the animation whose min visible change is being set
Throws
java.lang.IllegalArgumentException

if the given threshold is not positive

setStartValue

Added in 1.0.0
public T setStartValue(float startValue)

Sets the start value of the animation. If start value is not set, the animation will get the current value for the view's property, and use that as the start value.

Parameters
float startValue

start value for the animation
Returns
T

the Animation whose start value is being set

setStartVelocity

Added in 1.0.0
public T setStartVelocity(float startVelocity)

Start velocity of the animation. Default velocity is 0. Unit: change in property per second (e.g. pixels per second, scale/alpha value change per second).

Note when using a fixed value as the start velocity (as opposed to getting the velocity through touch events), it is recommended to define such a value in dp/second and convert it to pixel/second based on the density of the screen to achieve a consistent look across different screens.

To convert from dp/second to pixel/second: 

float pixelPerSecond = TypedValue.applyDimension(TypedValue.COMPLEX_UNIT_DIP, dpPerSecond,
        getResources().getDisplayMetrics());
Parameters
float startVelocity

start velocity of the animation
Returns
T

the Animation whose start velocity is being set

start

Added in 1.0.0
@MainThread
public void start()

Starts an animation. If the animation has already been started, no op. Note that calling start will not immediately set the property value to start value of the animation. The property values will be changed at each animation pulse, which happens before the draw pass. As a result, the changes will be reflected in the next frame, the same as if the values were set immediately. This method should only be called on main thread.

Throws
android.util.AndroidRuntimeException

if this method is not called on the main thread