Platform Android Studio Google Play Jetpack Docs News
Overview Guides Reference Samples Design & Quality

DynamicAnimation

abstract class DynamicAnimation<T : DynamicAnimation<T>!> : AnimationFrameCallback
kotlin.Any
   ↳ androidx.dynamicanimation.animation.DynamicAnimation

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(float) and setStartVelocity(float).

Summary

Nested classes
abstract

An animation listener that receives end notifications from an animation.
abstract

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.
abstract

ViewProperty holds the access of a property of a View.

Constants
static Float

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

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

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

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

Public methods
open T

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

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

Cancels the on-going animation.
open Float

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

Returns whether the animation is currently running.
open Unit

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

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

Sets the max value of the animation.
open T

Sets the min value of the animation.
open T
setMinimumVisibleChange(minimumVisibleChange: Float)

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.
open T
setStartValue(startValue: Float)

Sets the start value of the animation.
open T
setStartVelocity(startVelocity: Float)

Start velocity of the animation.
open Unit

Starts an animation.

Properties
static DynamicAnimation.ViewProperty!

View's alpha property.
static DynamicAnimation.ViewProperty!

View's rotation property.
static DynamicAnimation.ViewProperty!

View's rotationX property.
static DynamicAnimation.ViewProperty!

View's rotationY property.
static DynamicAnimation.ViewProperty!

View's scaleX property.
static DynamicAnimation.ViewProperty!

View's scaleY property.
static DynamicAnimation.ViewProperty!

View's scrollX property.
static DynamicAnimation.ViewProperty!

View's scrollY property.
static DynamicAnimation.ViewProperty!

View's translationX property.
static DynamicAnimation.ViewProperty!

View's translationY property.
static DynamicAnimation.ViewProperty!

View's translationZ property.
static DynamicAnimation.ViewProperty!

View's x property.
static DynamicAnimation.ViewProperty!

View's y property.
static DynamicAnimation.ViewProperty!

View's z property.

Constants

MIN_VISIBLE_CHANGE_ALPHA

static val MIN_VISIBLE_CHANGE_ALPHA: Float

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

Value: 1f / 256f

MIN_VISIBLE_CHANGE_PIXELS

static val MIN_VISIBLE_CHANGE_PIXELS: Float

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

Value: 1f

MIN_VISIBLE_CHANGE_ROTATION_DEGREES

static val MIN_VISIBLE_CHANGE_ROTATION_DEGREES: Float

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

Value: 1f / 10f

MIN_VISIBLE_CHANGE_SCALE

static val MIN_VISIBLE_CHANGE_SCALE: Float

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

Value: 1f / 500f

Public methods

addEndListener

open fun addEndListener(listener: DynamicAnimation.OnAnimationEndListener!): T

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
listener DynamicAnimation.OnAnimationEndListener!: the listener to be added
Return
T: the animation to which the listener is added

addUpdateListener

open fun addUpdateListener(listener: DynamicAnimation.OnAnimationUpdateListener!): T

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
listener DynamicAnimation.OnAnimationUpdateListener!: the listener to be added
Return
T: the animation to which the listener is added
Exceptions
UnsupportedOperationException if the update listener is added after the animation has started

cancel

open fun cancel(): Unit

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

Exceptions
AndroidRuntimeException if this method is not called on the main thread

getMinimumVisibleChange

open fun getMinimumVisibleChange(): Float

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

Return
Float: minimum change in property value that is visible to users

isRunning

open fun isRunning(): Boolean

Returns whether the animation is currently running.

Return
Boolean: true if the animation is currently running, false otherwise

removeEndListener

open fun removeEndListener(listener: DynamicAnimation.OnAnimationEndListener!): Unit

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

Parameters
listener DynamicAnimation.OnAnimationEndListener!: the listener to be removed

removeUpdateListener

open fun removeUpdateListener(listener: DynamicAnimation.OnAnimationUpdateListener!): Unit

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

Parameters
listener DynamicAnimation.OnAnimationUpdateListener!: the listener to be removed

setMaxValue

open fun setMaxValue(max: Float): T

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
max Float: maximum value of the property to be animated
Return
T: the Animation whose max value is being set

setMinValue

open fun setMinValue(min: Float): T

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
min Float: minimum value of the property to be animated
Return
T: the Animation whose min value is being set

setMinimumVisibleChange

open fun setMinimumVisibleChange(minimumVisibleChange: Float): T

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
minimumVisibleChange Float: minimum change in property value that is visible to users
Return
T: the animation whose min visible change is being set
Exceptions
IllegalArgumentException if the given threshold is not positive

setStartValue

open fun setStartValue(startValue: Float): T

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
startValue Float: start value for the animation
Return
T: the Animation whose start value is being set

setStartVelocity

open fun setStartVelocity(startVelocity: Float): T

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
startVelocity Float: start velocity of the animation
Return
T: the Animation whose start velocity is being set

start

open fun start(): Unit

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.

Exceptions
AndroidRuntimeException if this method is not called on the main thread

Properties

ALPHA

static val ALPHA: DynamicAnimation.ViewProperty!

View's alpha property.

ROTATION

static val ROTATION: DynamicAnimation.ViewProperty!

View's rotation property.

ROTATION_X

static val ROTATION_X: DynamicAnimation.ViewProperty!

View's rotationX property.

ROTATION_Y

static val ROTATION_Y: DynamicAnimation.ViewProperty!

View's rotationY property.

SCALE_X

static val SCALE_X: DynamicAnimation.ViewProperty!

View's scaleX property.

SCALE_Y

static val SCALE_Y: DynamicAnimation.ViewProperty!

View's scaleY property.

SCROLL_X

static val SCROLL_X: DynamicAnimation.ViewProperty!

View's scrollX property.

SCROLL_Y

static val SCROLL_Y: DynamicAnimation.ViewProperty!

View's scrollY property.

TRANSLATION_X

static val TRANSLATION_X: DynamicAnimation.ViewProperty!

View's translationX property.

TRANSLATION_Y

static val TRANSLATION_Y: DynamicAnimation.ViewProperty!

View's translationY property.

TRANSLATION_Z

static val TRANSLATION_Z: DynamicAnimation.ViewProperty!

View's translationZ property.

X

static val X: DynamicAnimation.ViewProperty!

View's x property.

Y

static val Y: DynamicAnimation.ViewProperty!

View's y property.

Z

static val Z: DynamicAnimation.ViewProperty!

View's z property.