public final class AnimatorSet extends Animator


This class plays a set of Animator objects in the specified order. Animations can be set up to play together, in sequence, or after a specified delay.

There are two different approaches to adding animations to a AnimatorSet: either the playTogether() or playSequentially() methods can be called to add a set of animations all at once, or the play can be used in conjunction with methods in the Builder class to add animations one by one.

It is possible to set up a AnimatorSet with circular dependencies between its animations. For example, an animation a1 could be set up to start before animation a2, a2 before a3, and a3 before a1. The results of this configuration are undefined, but will typically result in none of the affected animations being played. Because of this (and because circular dependencies do not make logical sense anyway), circular dependencies should be avoided, and the dependency flow of animations should only be in one direction.

Summary

Nested types

public inner class AnimatorSet.Builder

The Builder object is a utility class to facilitate adding animations to a AnimatorSet along with the relationships between the various animations.

Public constructors

Public methods

boolean

AnimatorSet is only reversible when the set contains no infinitely-repeating animation (e.g. a child animation with repeatCount = INFINITE

void

Cancels the animation.

@NonNull AnimatorSet
void
end()

Ends the animation.

@NonNull ArrayList<Animator>

Returns the current list of child Animator objects controlled by this AnimatorSet.

long

Returns the milliseconds elapsed since the start of the animation.

long

Gets the length of each of the child animations of this AnimatorSet.

@Nullable Interpolator

Returns the timing interpolator that this animation uses.

long

The amount of time, in milliseconds, to delay starting the animation after start is called.

long

Gets the total duration of the animation, accounting for animation sequences, start delay, and repeating.

boolean

Returns true if any of the child animations of this AnimatorSet have been started and have not yet ended.

boolean

Returns whether this Animator has been started and not yet ended.

void

Pauses a running animation.

@NonNull AnimatorSet.Builder

This method creates a Builder object, which is used to set up playing constraints.

void
playSequentially(@NonNull Animator[] items)

Sets up this AnimatorSet to play each of the supplied animations when the previous animation ends.

void

Sets up this AnimatorSet to play each of the supplied animations when the previous animation ends.

void
playTogether(@NonNull Animator[] items)

Sets up this AnimatorSet to play all of the supplied animations at the same time.

void

Sets up this AnimatorSet to play all of the supplied animations at the same time.

void

Resumes a paused animation, causing the animator to pick up where it left off when it was paused.

void

Plays the AnimatorSet in reverse.

void
setCurrentPlayTime(long playTime)

Sets the position of the animation to the specified point in time.

@NonNull AnimatorSet
setDuration(long duration)

Sets the length of each of the current child animations of this AnimatorSet.

void

Sets the Interpolator for all current child animations of this AnimatorSet.

void
setStartDelay(long startDelay)

The amount of time, in milliseconds, to delay starting the animation after start is called.

void

Sets the target object for all current child animations of this AnimatorSet that take targets (ObjectAnimator and AnimatorSet).

void

This method tells the object to use appropriate information to extract ending values for the animation.

void

This method tells the object to use appropriate information to extract starting values for the animation.

void

Starts this animation.

String

Inherited Constants

From androidx.core.animation.Animator
static final long

The value used to indicate infinite duration (e.g. when Animators repeat infinitely).

Inherited methods

From androidx.core.animation.Animator
void

Adds a listener to the set of listeners that are sent events through the life of an animation, such as start, repeat, and end.

void

Adds a pause listener to this animator.

void

Adds a listener to the set of listeners that are sent update events through the life of an animation.

boolean

Returns whether this animator is currently in a paused state.

void

Removes all listeners and pauseListeners from this object.

void

Removes all listeners from the set listening to frame updates for this animation.

void

Removes a listener from the set listening to this animation.

void

Removes a pause listener from the set listening to this animation.

void

Removes a listener from the set listening to frame updates for this animation.

Public constructors

AnimatorSet

public AnimatorSet()

Public methods

canReverse

public boolean canReverse()

AnimatorSet is only reversible when the set contains no infinitely-repeating animation (e.g. a child animation with repeatCount = INFINITE

Returns
boolean

true if the animator set is reversible, false otherwise.

cancel

public void cancel()

Cancels the animation. Unlike #end(), cancel() causes the animation to stop in its tracks, sending an AnimatorListener#onAnimationCancel(Animator) to its listeners, followed by an AnimatorListener#onAnimationEnd(Animator) message.

This method must be called on the thread that is running the animation.

Note that canceling a AnimatorSet also cancels all of the animations that it is responsible for.

clone

public @NonNull AnimatorSet clone()

end

public void end()

Ends the animation. This causes the animation to assign the end value of the property being animated, then calling the AnimatorListener#onAnimationEnd(Animator) method on its listeners.

This method must be called on the thread that is running the animation.

Note that ending a AnimatorSet also ends all of the animations that it is responsible for.

getChildAnimations

public @NonNull ArrayList<AnimatorgetChildAnimations()

Returns the current list of child Animator objects controlled by this AnimatorSet. This is a copy of the internal list; modifications to the returned list will not affect the AnimatorSet, although changes to the underlying Animator objects will affect those objects being managed by the AnimatorSet.

Returns
@NonNull ArrayList<Animator>

ArrayListThe list of child animations of this AnimatorSet.

getCurrentPlayTime

public long getCurrentPlayTime()

Returns the milliseconds elapsed since the start of the animation.

For ongoing animations, this method returns the current progress of the animation in terms of play time. For an animation that has not yet been started: if the animation has been seeked to a certain time via setCurrentPlayTime, the seeked play time will be returned; otherwise, this method will return 0.

Returns
long

the current position in time of the animation in milliseconds

getDuration

public long getDuration()

Gets the length of each of the child animations of this AnimatorSet. This value may be less than 0, which indicates that no duration has been set on this AnimatorSet and each of the child animations will use their own duration.

Returns
long

The length of the animation, in milliseconds, of each of the child animations of this AnimatorSet.

getInterpolator

public @Nullable Interpolator getInterpolator()

Returns the timing interpolator that this animation uses.

Returns
@Nullable Interpolator

The timing interpolator for this animation.

getStartDelay

public long getStartDelay()

The amount of time, in milliseconds, to delay starting the animation after start is called.

Returns
long

the number of milliseconds to delay running the animation

getTotalDuration

public long getTotalDuration()

Gets the total duration of the animation, accounting for animation sequences, start delay, and repeating.

When the animation repeats infinite times, or when any of the child animators does (via ValueAnimator#setRepeatCount(int)} to ValueAnimator#INFINITE), the total duration will be #DURATION_INFINITE. Otherwise, the total duration is the sum of start delay and animation running time (i.e. duration of one iteration multiplied by the number of iterations).

isRunning

public boolean isRunning()

Returns true if any of the child animations of this AnimatorSet have been started and have not yet ended. Child animations will not be started until the AnimatorSet has gone past its initial delay set through setStartDelay.

Returns
boolean

Whether this AnimatorSet has gone past the initial delay, and at least one child animation has been started and not yet ended.

isStarted

public boolean isStarted()

Returns whether this Animator has been started and not yet ended. For reusable Animators (which most Animators are, apart from the one-shot animator produced by createCircularReveal()), this state is a superset of isRunning, because an Animator with a nonzero startDelay will return true for isStarted during the delay phase, whereas isRunning will return true only after the delay phase is complete. Non-reusable animators will always return true after they have been started, because they cannot return to a non-started state.

Returns
boolean

Whether the Animator has been started and not yet ended.

pause

public void pause()

Pauses a running animation. This method should only be called on the same thread on which the animation was started. If the animation has not yet been started or has since ended, then the call is ignored. Paused animations can be resumed by calling resume.

play

public @NonNull AnimatorSet.Builder play(@NonNull Animator anim)

This method creates a Builder object, which is used to set up playing constraints. This initial play() method tells the Builder the animation that is the dependency for the succeeding commands to the Builder. For example, calling play(a1).with(a2) sets up the AnimatorSet to play a1 and a2 at the same time, play(a1).before(a2) sets up the AnimatorSet to play a1 first, followed by a2, and play(a1).after(a2) sets up the AnimatorSet to play a2 first, followed by a1.

Note that play() is the only way to tell the Builder the animation upon which the dependency is created, so successive calls to the various functions in Builder will all refer to the initial parameter supplied in play() as the dependency of the other animations. For example, calling play(a1).before(a2).before(a3) will play both a2 and a3 when a1 ends; it does not set up a dependency between a2 and a3.

Parameters
@NonNull Animator anim

The animation that is the dependency used in later calls to the methods in the returned Builder object. A null parameter will result in a null Builder return value.

Returns
@NonNull AnimatorSet.Builder

Builder The object that constructs the AnimatorSet based on the dependencies outlined in the calls to play and the other methods in the Builder

playSequentially

public void playSequentially(@NonNull Animator[] items)

Sets up this AnimatorSet to play each of the supplied animations when the previous animation ends.

Parameters
@NonNull Animator[] items

The animations that will be started one after another.

playSequentially

public void playSequentially(@NonNull List<Animator> items)

Sets up this AnimatorSet to play each of the supplied animations when the previous animation ends.

Parameters
@NonNull List<Animator> items

The animations that will be started one after another.

playTogether

public void playTogether(@NonNull Animator[] items)

Sets up this AnimatorSet to play all of the supplied animations at the same time. This is equivalent to calling play with the first animator in the set and then with with each of the other animators. Note that an Animator with a startDelay will not actually start until that delay elapses, which means that if the first animator in the list supplied to this constructor has a startDelay, none of the other animators will start until that first animator's startDelay has elapsed.

Parameters
@NonNull Animator[] items

The animations that will be started simultaneously.

playTogether

public void playTogether(@NonNull Collection<Animator> items)

Sets up this AnimatorSet to play all of the supplied animations at the same time.

Parameters
@NonNull Collection<Animator> items

The animations that will be started simultaneously.

resume

public void resume()

Resumes a paused animation, causing the animator to pick up where it left off when it was paused. This method should only be called on the same thread on which the animation was started. Calls to resume() on an animator that is not currently paused will be ignored.

reverse

public void reverse()

Plays the AnimatorSet in reverse. If the animation has been seeked to a specific play time using setCurrentPlayTime, it will play backwards from the point seeked when reverse was called. Otherwise, then it will start from the end and play backwards. This behavior is only set for the current animation; future playing of the animation will use the default behavior of playing forward.

Note: reverse is not supported for infinite AnimatorSet.

setCurrentPlayTime

public void setCurrentPlayTime(long playTime)

Sets the position of the animation to the specified point in time. This time should be between 0 and the total duration of the animation, including any repetition. If the animation has not yet been started, then it will not advance forward after it is set to this time; it will simply set the time to this value and perform any appropriate actions based on that time. If the animation is already running, then setCurrentPlayTime() will set the current playing time to this value and continue playing from that point.

Parameters
long playTime

The time, in milliseconds, to which the animation is advanced or rewound. Unless the animation is reversing, the playtime is considered the time since the end of the start delay of the AnimatorSet in a forward playing direction.

setDuration

public @NonNull AnimatorSet setDuration(long duration)

Sets the length of each of the current child animations of this AnimatorSet. By default, each child animation will use its own duration. If the duration is set on the AnimatorSet, then each child animation inherits this duration.

Parameters
long duration

The length of the animation, in milliseconds, of each of the child animations of this AnimatorSet.

setInterpolator

public void setInterpolator(@Nullable Interpolator interpolator)

Sets the Interpolator for all current child animations of this AnimatorSet. The default value is null, which means that no interpolator is set on this AnimatorSet. Setting the interpolator to any non-null value will cause that interpolator to be set on the child animations when the set is started.

Parameters
@Nullable Interpolator interpolator

the interpolator to be used by each child animation of this AnimatorSet

setStartDelay

public void setStartDelay(long startDelay)

The amount of time, in milliseconds, to delay starting the animation after start is called. Note that the start delay should always be non-negative. Any negative start delay will be clamped to 0 on N and above.

Parameters
long startDelay

The amount of the delay, in milliseconds

setTarget

public void setTarget(@Nullable Object target)

Sets the target object for all current child animations of this AnimatorSet that take targets (ObjectAnimator and AnimatorSet).

Parameters
@Nullable Object target

The object being animated

setupEndValues

public void setupEndValues()

This method tells the object to use appropriate information to extract ending values for the animation. For example, a AnimatorSet object will pass this call to its child objects to tell them to set up the values. A ObjectAnimator object will use the information it has about its target object and PropertyValuesHolder objects to get the start values for its properties. A ValueAnimator object will ignore the request since it does not have enough information (such as a target object) to gather these values.

setupStartValues

public void setupStartValues()

This method tells the object to use appropriate information to extract starting values for the animation. For example, a AnimatorSet object will pass this call to its child objects to tell them to set up the values. A ObjectAnimator object will use the information it has about its target object and PropertyValuesHolder objects to get the start values for its properties. A ValueAnimator object will ignore the request since it does not have enough information (such as a target object) to gather these values.

start

public void start()

Starts this animation. If the animation has a nonzero startDelay, the animation will start running after that delay elapses. A non-delayed animation will have its initial value(s) set immediately, followed by calls to AnimatorListener#onAnimationStart(Animator) for any listeners of this animator.

The animation started by calling this method will be run on the thread that called this method. This thread should have a Looper on it (a runtime exception will be thrown if this is not the case). Also, if the animation will animate properties of objects in the view hierarchy, then the calling thread should be the UI thread for that view hierarchy.

Starting this AnimatorSet will, in turn, start the animations for which it is responsible. The details of when exactly those animations are started depends on the dependency relationships that have been set up between the animations. Note: Manipulating AnimatorSet's lifecycle in the child animators' listener callbacks will lead to undefined behaviors. Also, AnimatorSet will ignore any seeking in the child animators once start is called.

toString

public String toString()