Most visited

Recently visited

Added in API level 11

AnimatorSet

public final class AnimatorSet
extends Animator

java.lang.Object
   ↳ android.animation.Animator
     ↳ android.animation.AnimatorSet


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(Animator) 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.

Developer Guides

For more information about animating with AnimatorSet, read the Property Animation developer guide.

Summary

Nested classes

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. 

Inherited constants

From class android.animation.Animator

Public constructors

AnimatorSet()

Public methods

void cancel()

Cancels the animation.

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

AnimatorSet clone()

Creates and returns a copy of this object.

void end()

Ends the animation.

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

ArrayList<Animator> getChildAnimations()

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

long getDuration()

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

TimeInterpolator getInterpolator()

Returns the timing interpolator that this animation uses.

long getStartDelay()

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

long getTotalDuration()

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

boolean isRunning()

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

boolean isStarted()

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

void pause()

Pauses a running animation.

AnimatorSet.Builder play(Animator anim)

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

void playSequentially(List<Animator> items)

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

void playSequentially(Animator... items)

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

void playTogether(Collection<Animator> items)

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

void playTogether(Animator... items)

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

void resume()

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

AnimatorSet setDuration(long duration)

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

void setInterpolator(TimeInterpolator interpolator)

Sets the TimeInterpolator 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 setTarget(Object target)

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

void setupEndValues()

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

void setupStartValues()

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

void start()

Starts this animation.

Starting this AnimatorSet will, in turn, start the animations for which it is responsible.

String toString()

Returns a string representation of the object.

Inherited methods

From class android.animation.Animator
From class java.lang.Object

Public constructors

AnimatorSet

Added in API level 11
AnimatorSet ()

Public methods

cancel

Added in API level 11
void cancel ()

Cancels the animation. Unlike end(), cancel() causes the animation to stop in its tracks, sending an onAnimationCancel(Animator) to its listeners, followed by an 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

Added in API level 11
AnimatorSet clone ()

Creates and returns a copy of this object. The precise meaning of "copy" may depend on the class of the object. The general intent is that, for any object x, the expression:

 x.clone() != x
will be true, and that the expression:
 x.clone().getClass() == x.getClass()
will be true, but these are not absolute requirements. While it is typically the case that:
 x.clone().equals(x)
will be true, this is not an absolute requirement.

By convention, the returned object should be obtained by calling super.clone. If a class and all of its superclasses (except Object) obey this convention, it will be the case that x.clone().getClass() == x.getClass().

By convention, the object returned by this method should be independent of this object (which is being cloned). To achieve this independence, it may be necessary to modify one or more fields of the object returned by super.clone before returning it. Typically, this means copying any mutable objects that comprise the internal "deep structure" of the object being cloned and replacing the references to these objects with references to the copies. If a class contains only primitive fields or references to immutable objects, then it is usually the case that no fields in the object returned by super.clone need to be modified.

The method clone for class Object performs a specific cloning operation. First, if the class of this object does not implement the interface Cloneable, then a CloneNotSupportedException is thrown. Note that all arrays are considered to implement the interface Cloneable and that the return type of the clone method of an array type T[] is T[] where T is any reference or primitive type. Otherwise, this method creates a new instance of the class of this object and initializes all its fields with exactly the contents of the corresponding fields of this object, as if by assignment; the contents of the fields are not themselves cloned. Thus, this method performs a "shallow copy" of this object, not a "deep copy" operation.

The class Object does not itself implement the interface Cloneable, so calling the clone method on an object whose class is Object will result in throwing an exception at run time.

Returns
AnimatorSet a clone of this instance.

end

Added in API level 11
void end ()

Ends the animation. This causes the animation to assign the end value of the property being animated, then calling the 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

Added in API level 11
ArrayList<Animator> getChildAnimations ()

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
ArrayList<Animator> ArrayList The list of child animations of this AnimatorSet.

getDuration

Added in API level 11
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

Added in API level 18
TimeInterpolator getInterpolator ()

Returns the timing interpolator that this animation uses.

Returns
TimeInterpolator The timing interpolator for this animation.

getStartDelay

Added in API level 11
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

Added in API level 24
long getTotalDuration ()

Gets the total duration of the animation, accounting for animation sequences, start delay, and repeating. Return DURATION_INFINITE if the duration is infinite.

Returns
long Total time an animation takes to finish, starting from the time start() is called. DURATION_INFINITE will be returned if the animation or any child animation repeats infinite times.

isRunning

Added in API level 11
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(long).

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

Added in API level 14
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

Added in API level 19
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

Added in API level 11
AnimatorSet.Builder play (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
anim Animator: 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
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

Added in API level 11
void playSequentially (List<Animator> items)

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

Parameters
items List: The animations that will be started one after another.

playSequentially

Added in API level 11
void playSequentially (Animator... items)

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

Parameters
items Animator: The animations that will be started one after another.

playTogether

Added in API level 11
void playTogether (Collection<Animator> items)

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

Parameters
items Collection: The animations that will be started simultaneously.

playTogether

Added in API level 11
void playTogether (Animator... items)

Sets up this AnimatorSet to play all of the supplied animations at the same time. This is equivalent to calling play(Animator) with the first animator in the set and then with(Animator) 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
items Animator: The animations that will be started simultaneously.

resume

Added in API level 19
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.

setDuration

Added in API level 11
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
duration long: The length of the animation, in milliseconds, of each of the child animations of this AnimatorSet.
Returns
AnimatorSet

setInterpolator

Added in API level 11
void setInterpolator (TimeInterpolator interpolator)

Sets the TimeInterpolator 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
interpolator TimeInterpolator: the interpolator to be used by each child animation of this AnimatorSet

setStartDelay

Added in API level 11
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
startDelay long: The amount of the delay, in milliseconds

setTarget

Added in API level 11
void setTarget (Object target)

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

Parameters
target Object: The object being animated

setupEndValues

Added in API level 11
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

Added in API level 11
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

Added in API level 11
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 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.

toString

Added in API level 11
String toString ()

Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())
 

Returns
String a string representation of the object.

Hooray!