public class ValueAnimator extends Animator
There is a single timing pulse that all animations use. It runs in a custom handler to ensure that property changes happen on the UI thread.
By default, ValueAnimator uses non-linear time interpolation, via the
AccelerateDecelerateInterpolator
class, which accelerates into and decelerates
out of an animation. This behavior can be changed by calling
setInterpolator(TimeInterpolator)
.
Animators can be created from either code or resource files. Here is an example of a ValueAnimator resource file:
It is also possible to use a combination of PropertyValuesHolder
and
Keyframe
resource tags to create a multi-step animation.
Note that you can specify explicit fractional values (from 0 to 1) for
each keyframe to determine when, in the overall duration, the animation should arrive at that
value. Alternatively, you can leave the fractions off and the keyframes will be equally
distributed within the total duration:
For more information about animating with ValueAnimator
, read the
Property
Animation developer guide.
Modifier and Type | Class and Description |
---|---|
static interface |
ValueAnimator.AnimatorUpdateListener
Implementors of this interface can add themselves as update listeners
to an
ValueAnimator instance to receive callbacks on every animation
frame, after the current frame's values have been calculated for that
ValueAnimator . |
static interface |
ValueAnimator.RepeatMode |
Animator.AnimatorListener, Animator.AnimatorPauseListener
Modifier and Type | Field and Description |
---|---|
static int |
INFINITE
This value used used with the
setRepeatCount(int) property to repeat
the animation indefinitely. |
static int |
RESTART
When the animation reaches the end and
repeatCount is INFINITE
or a positive value, the animation restarts from the beginning. |
static int |
REVERSE
When the animation reaches the end and
repeatCount is INFINITE
or a positive value, the animation reverses direction on every iteration. |
DURATION_INFINITE
Constructor and Description |
---|
ValueAnimator()
Creates a new ValueAnimator object.
|
Modifier and Type | Method and Description |
---|---|
void |
addUpdateListener(ValueAnimator.AnimatorUpdateListener listener)
Adds a listener to the set of listeners that are sent update events through the life of
an animation.
|
void |
cancel()
Cancels the animation.
|
boolean |
canReverse() |
ValueAnimator |
clone()
Creates and returns a copy of this object.
|
void |
commitAnimationFrame(long frameTime)
Applies an adjustment to the animation to compensate for jank between when
the animation first ran and when the frame was drawn.
|
void |
doAnimationFrame(long frameTime)
Processes a frame of the animation, adjusting the start time if needed.
|
void |
end()
Ends the animation.
|
float |
getAnimatedFraction()
Returns the current animation fraction, which is the elapsed/interpolated fraction used in
the most recent frame update on the animation.
|
Object |
getAnimatedValue()
The most recent value calculated by this
ValueAnimator when there is just one
property being animated. |
Object |
getAnimatedValue(String propertyName)
The most recent value calculated by this
ValueAnimator for propertyName . |
static int |
getCurrentAnimationsCount()
Return the number of animations currently running.
|
long |
getCurrentPlayTime()
Gets the current position of the animation in time, which is equal to the current
time minus the time that the animation started.
|
long |
getDuration()
Gets the length of the animation.
|
static float |
getDurationScale() |
static long |
getFrameDelay()
The amount of time, in milliseconds, between each frame of the animation.
|
TimeInterpolator |
getInterpolator()
Returns the timing interpolator that this ValueAnimator uses.
|
int |
getRepeatCount()
Defines how many times the animation should repeat.
|
int |
getRepeatMode()
Defines what this animation should do when it reaches the end.
|
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.
|
PropertyValuesHolder[] |
getValues()
Returns the values that this ValueAnimator animates between.
|
boolean |
isRunning()
Returns whether this Animator is currently running (having been started and gone past any
initial startDelay period and not yet ended).
|
boolean |
isStarted()
Returns whether this Animator has been started and not yet ended.
|
static ValueAnimator |
ofArgb(int... values)
Constructs and returns a ValueAnimator that animates between color values.
|
static ValueAnimator |
ofFloat(float... values)
Constructs and returns a ValueAnimator that animates between float values.
|
static ValueAnimator |
ofInt(int... values)
Constructs and returns a ValueAnimator that animates between int values.
|
static ValueAnimator |
ofObject(TypeEvaluator evaluator,
Object... values)
Constructs and returns a ValueAnimator that animates between Object values.
|
static ValueAnimator |
ofPropertyValuesHolder(PropertyValuesHolder... values)
Constructs and returns a ValueAnimator that animates between the values
specified in the PropertyValuesHolder objects.
|
void |
pause()
Pauses a running animation.
|
void |
removeAllUpdateListeners()
Removes all listeners from the set listening to frame updates for this animation.
|
void |
removeUpdateListener(ValueAnimator.AnimatorUpdateListener listener)
Removes a listener from the set listening to frame updates for this animation.
|
void |
resume()
Resumes a paused animation, causing the animator to pick up where it left off
when it was paused.
|
void |
reverse()
Plays the ValueAnimator in reverse.
|
void |
setAllowRunningAsynchronously(boolean mayRunAsync)
Whether or not the ValueAnimator is allowed to run asynchronously off of
the UI thread.
|
void |
setCurrentFraction(float fraction)
Sets the position of the animation to the specified fraction.
|
void |
setCurrentPlayTime(long playTime)
Sets the position of the animation to the specified point in time.
|
ValueAnimator |
setDuration(long duration)
Sets the length of the animation.
|
static void |
setDurationScale(float durationScale) |
void |
setEvaluator(TypeEvaluator value)
The type evaluator to be used when calculating the animated values of this animation.
|
void |
setFloatValues(float... values)
Sets float values that will be animated between.
|
static void |
setFrameDelay(long frameDelay)
The amount of time, in milliseconds, between each frame of the animation.
|
void |
setInterpolator(TimeInterpolator value)
The time interpolator used in calculating the elapsed fraction of this animation.
|
void |
setIntValues(int... values)
Sets int values that will be animated between.
|
void |
setObjectValues(Object... values)
Sets the values to animate between for this animation.
|
void |
setRepeatCount(int value)
Sets how many times the animation should be repeated.
|
void |
setRepeatMode(int value)
Defines what this animation should do when it reaches the end.
|
void |
setStartDelay(long startDelay)
The amount of time, in milliseconds, to delay starting the animation after
start() is called. |
void |
setValues(PropertyValuesHolder... values)
Sets the values, per property, being animated between.
|
void |
start()
Starts this animation.
|
String |
toString()
Returns a string representation of the object.
|
addListener, addPauseListener, appendChangingConfigurations, createConstantState, getChangingConfigurations, getListeners, isPaused, removeAllListeners, removeListener, removePauseListener, setChangingConfigurations, setTarget, setupEndValues, setupStartValues
public static final int RESTART
repeatCount
is INFINITE
or a positive value, the animation restarts from the beginning.public static final int REVERSE
repeatCount
is INFINITE
or a positive value, the animation reverses direction on every iteration.public static final int INFINITE
setRepeatCount(int)
property to repeat
the animation indefinitely.public ValueAnimator()
public static void setDurationScale(float durationScale)
public static float getDurationScale()
public static ValueAnimator ofInt(int... values)
values
- A set of values that the animation will animate between over time.public static ValueAnimator ofArgb(int... values)
values
- A set of values that the animation will animate between over time.public static ValueAnimator ofFloat(float... values)
values
- A set of values that the animation will animate between over time.public static ValueAnimator ofPropertyValuesHolder(PropertyValuesHolder... values)
values
- A set of PropertyValuesHolder objects whose values will be animated
between over time.public static ValueAnimator ofObject(TypeEvaluator evaluator, Object... values)
Note: The Object values are stored as references to the original objects, which means that changes to those objects after this method is called will affect the values on the animator. If the objects will be mutated externally after this method is called, callers should pass a copy of those objects instead.
Since ValueAnimator does not know how to animate between arbitrary Objects, this factory method also takes a TypeEvaluator object that the ValueAnimator will use to perform that interpolation.
evaluator
- A TypeEvaluator that will be called on each animation frame to
provide the ncessry interpolation between the Object values to derive the animated
value.values
- A set of values that the animation will animate between over time.public void setIntValues(int... values)
If there are already multiple sets of values defined for this ValueAnimator via more than one PropertyValuesHolder object, this method will set the values for the first of those objects.
values
- A set of values that the animation will animate between over time.public void setFloatValues(float... values)
If there are already multiple sets of values defined for this ValueAnimator via more than one PropertyValuesHolder object, this method will set the values for the first of those objects.
values
- A set of values that the animation will animate between over time.public void setObjectValues(Object... values)
Note: The Object values are stored as references to the original objects, which means that changes to those objects after this method is called will affect the values on the animator. If the objects will be mutated externally after this method is called, callers should pass a copy of those objects instead.
If there are already multiple sets of values defined for this ValueAnimator via more than one PropertyValuesHolder object, this method will set the values for the first of those objects.
There should be a TypeEvaluator set on the ValueAnimator that knows how to interpolate between these value objects. ValueAnimator only knows how to interpolate between the primitive types specified in the other setValues() methods.
values
- The set of values to animate between.public void setValues(PropertyValuesHolder... values)
values
- The set of values, per property, being animated between.public PropertyValuesHolder[] getValues()
public ValueAnimator setDuration(long duration)
setDuration
in class Animator
duration
- The length of the animation, in milliseconds. This value cannot
be negative.ValueAnimator.ofInt(0, 10).setDuration(500).start()
.public long getDuration()
getDuration
in class Animator
public long getTotalDuration()
Animator
Animator.DURATION_INFINITE
if the duration is infinite.getTotalDuration
in class Animator
Animator.start()
is called. Animator.DURATION_INFINITE
will be returned if the animation or any
child animation repeats infinite times.public void setCurrentPlayTime(long playTime)
playTime
- The time, in milliseconds, to which the animation is advanced or rewound.public void setCurrentFraction(float fraction)
Animator.AnimatorListener
events are not called
due to changing the fraction; those events are only processed while the animation
is running.fraction
- The fraction to which the animation is advanced or rewound. Values
outside the range of 0 to the maximum fraction for the animator will be clamped to
the correct range.public long getCurrentPlayTime()
setCurrentPlayTime(long)
or setCurrentFraction(float)
, in which case
it will return the time that was set.public long getStartDelay()
start()
is called.getStartDelay
in class Animator
public void setStartDelay(long startDelay)
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.setStartDelay
in class Animator
startDelay
- The amount of the delay, in millisecondspublic static long getFrameDelay()
start()
is
called in order to check the frame delay for that animation. A runtime exception will be
thrown if the calling thread does not have a Looper.public static void setFrameDelay(long frameDelay)
start()
is
called in order to have the new frame delay take effect on that animation. A runtime
exception will be thrown if the calling thread does not have a Looper.frameDelay
- the requested time between frames, in millisecondspublic Object getAnimatedValue()
ValueAnimator
when there is just one
property being animated. This value is only sensible while the animation is running. The main
purpose for this read-only property is to retrieve the value from the ValueAnimator
during a call to ValueAnimator.AnimatorUpdateListener.onAnimationUpdate(ValueAnimator)
, which
is called during each animation frame, immediately after the value is calculated.ValueAnimator
for
the single property being animated. If there are several properties being animated
(specified by several PropertyValuesHolder objects in the constructor), this function
returns the animated value for the first of those objects.public Object getAnimatedValue(String propertyName)
ValueAnimator
for propertyName
.
The main purpose for this read-only property is to retrieve the value from the
ValueAnimator
during a call to
ValueAnimator.AnimatorUpdateListener.onAnimationUpdate(ValueAnimator)
, which
is called during each animation frame, immediately after the value is calculated.ValueAnimator
.public void setRepeatCount(int value)
INFINITE
, the repeat mode will be taken
into account. The repeat count is 0 by default.value
- the number of times the animation should be repeatedpublic int getRepeatCount()
INFINITE
public void setRepeatMode(int value)
public int getRepeatMode()
public void addUpdateListener(ValueAnimator.AnimatorUpdateListener listener)
listener
- the listener to be added to the current set of listeners for this animation.public void removeAllUpdateListeners()
public void removeUpdateListener(ValueAnimator.AnimatorUpdateListener listener)
listener
- the listener to be removed from the current set of update listeners
for this animation.public void setInterpolator(TimeInterpolator value)
AccelerateDecelerateInterpolator
setInterpolator
in class Animator
value
- the interpolator to be used by this animation. A value of null
will result in linear interpolation.public TimeInterpolator getInterpolator()
getInterpolator
in class Animator
public void setEvaluator(TypeEvaluator value)
startValue
and endValue
in the constructor. But if these values
are not one of these primitive types, or if different evaluation is desired (such as is
necessary with int values that represent colors), a custom evaluator needs to be assigned.
For example, when running an animation on color values, the ArgbEvaluator
should be used to get correct RGB color interpolation.
If this ValueAnimator has only one set of values being animated between, this evaluator will be used for that set. If there are several sets of values being animated, which is the case if PropertyValuesHolder objects were set on the ValueAnimator, then the evaluator is assigned just to the first PropertyValuesHolder object.
value
- the evaluator to be used this animationpublic void start()
Animator
Animator.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.
public void cancel()
Animator
Animator.end()
, cancel()
causes the animation to
stop in its tracks, sending an
Animator.AnimatorListener.onAnimationCancel(Animator)
to
its listeners, followed by an
Animator.AnimatorListener.onAnimationEnd(Animator)
message.
This method must be called on the thread that is running the animation.
public void end()
Animator
Animator.AnimatorListener.onAnimationEnd(Animator)
method on
its listeners.
This method must be called on the thread that is running the animation.
public void resume()
Animator
resume
in class Animator
Animator.pause()
,
Animator.isPaused()
,
Animator.AnimatorPauseListener
public void pause()
Animator
started
or has since ended, then the call is ignored. Paused
animations can be resumed by calling Animator.resume()
.pause
in class Animator
Animator.resume()
,
Animator.isPaused()
,
Animator.AnimatorPauseListener
public boolean isRunning()
Animator
public boolean isStarted()
Animator
createCircularReveal()
),
this state is a superset of Animator.isRunning()
, because an Animator with a
nonzero startDelay
will return true for Animator.isStarted()
during
the delay phase, whereas Animator.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.public void reverse()
public boolean canReverse()
canReverse
in class Animator
public void commitAnimationFrame(long frameTime)
frameTime
- The frame time after traversals happen, if any, in the
SystemClock.uptimeMillis()
time base.public final void doAnimationFrame(long frameTime)
frameTime
- The frame time.public float getAnimatedFraction()
public ValueAnimator clone()
Object
x
, the expression:
will be true, and that the expression:x.clone() != x
will bex.clone().getClass() == x.getClass()
true
, but these are not absolute requirements.
While it is typically the case that:
will bex.clone().equals(x)
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.
public static int getCurrentAnimationsCount()
public String toString()
Object
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())
public void setAllowRunningAsynchronously(boolean mayRunAsync)
Whether or not the ValueAnimator is allowed to run asynchronously off of
the UI thread. This is a hint that informs the ValueAnimator that it is
OK to run the animation off-thread, however ValueAnimator may decide
that it must run the animation on the UI thread anyway. For example if there
is an ValueAnimator.AnimatorUpdateListener
the animation will run on the UI thread,
regardless of the value of this hint.
Regardless of whether or not the animation runs asynchronously, all listener callbacks will be called on the UI thread.
To be able to use this hint the following must be true:
getAnimatedFraction()
is not needed (it will return undefined values).isStarted()
is true. Requests
to change values, duration, delay, etc... may be ignored.Animator.AnimatorListener.onAnimationEnd(Animator)
or
Animator.AnimatorListener.onAnimationRepeat(Animator)
may end up delayed
as they must be posted back to the UI thread, and any actions performed
by those callbacks (such as starting new animations) will not happen
in the same frame.cancel()
, end()
, reverse()
, etc...)
may be asynchronous. It is guaranteed that all state changes that are
performed on the UI thread in the same frame will be applied as a single
atomic update, however that frame may be the current frame,
the next frame, or some future frame. This will also impact the observed
state of the Animator. For example, isStarted()
may still return true
after a call to end()
. Using the lifecycle callbacks is preferred over
queries to isStarted()
, isRunning()
, and Animator.isPaused()
for this reason.setAllowRunningAsynchronously
in class Animator