Added in API level 12

Summary: Methods | Inherited Methods

ViewPropertyAnimator

---

Kotlin |Java

public class ViewPropertyAnimator
extends Object

java.lang.Object
↳	android.view.ViewPropertyAnimator

---

This class enables automatic and optimized animation of select properties on View objects. If only one or two properties on a View object are being animated, then using an ObjectAnimator is fine; the property setters called by ObjectAnimator are well equipped to do the right thing to set the property and invalidate the view appropriately. But if several properties are animated simultaneously, or if you just want a more convenient syntax to animate a specific property, then ViewPropertyAnimator might be more well-suited to the task.

This class may provide better performance for several simultaneous animations, because it will optimize invalidate calls to take place only once for several properties instead of each animated property independently causing its own invalidation. Also, the syntax of using this class could be easier to use because the caller need only tell the View object which property to animate, and the value to animate either to or by, and this class handles the details of configuring the underlying Animator class and starting it.

This class is not constructed by the caller, but rather by the View whose properties it will animate. Calls to View.animate() will return a reference to the appropriate ViewPropertyAnimator object for that View.

Summary

Public methods
ViewPropertyAnimator	alpha(float value) This method will cause the View's alpha property to be animated to the specified value.
ViewPropertyAnimator	alphaBy(float value) This method will cause the View's alpha property to be animated by the specified value.
void	cancel() Cancels all property animations that are currently running or pending.
long	getDuration() Returns the current duration of property animations.
TimeInterpolator	getInterpolator() Returns the timing interpolator that this animation uses.
long	getStartDelay() Returns the current startDelay of property animations.
ViewPropertyAnimator	rotation(float value) This method will cause the View's rotation property to be animated to the specified value.
ViewPropertyAnimator	rotationBy(float value) This method will cause the View's rotation property to be animated by the specified value.
ViewPropertyAnimator	rotationX(float value) This method will cause the View's rotationX property to be animated to the specified value.
ViewPropertyAnimator	rotationXBy(float value) This method will cause the View's rotationX property to be animated by the specified value.
ViewPropertyAnimator	rotationY(float value) This method will cause the View's rotationY property to be animated to the specified value.
ViewPropertyAnimator	rotationYBy(float value) This method will cause the View's rotationY property to be animated by the specified value.
ViewPropertyAnimator	scaleX(float value) This method will cause the View's scaleX property to be animated to the specified value.
ViewPropertyAnimator	scaleXBy(float value) This method will cause the View's scaleX property to be animated by the specified value.
ViewPropertyAnimator	scaleY(float value) This method will cause the View's scaleY property to be animated to the specified value.
ViewPropertyAnimator	scaleYBy(float value) This method will cause the View's scaleY property to be animated by the specified value.
ViewPropertyAnimator	setDuration(long duration) Sets the duration for the underlying animator that animates the requested properties.
ViewPropertyAnimator	setInterpolator(TimeInterpolator interpolator) Sets the interpolator for the underlying animator that animates the requested properties.
ViewPropertyAnimator	setListener(Animator.AnimatorListener listener) Sets a listener for events in the underlying Animators that run the property animations.
ViewPropertyAnimator	setStartDelay(long startDelay) Sets the startDelay for the underlying animator that animates the requested properties.
ViewPropertyAnimator	setUpdateListener(ValueAnimator.AnimatorUpdateListener listener) Sets a listener for update events in the underlying ValueAnimator that runs the property animations.
void	start() Starts the currently pending property animations immediately.
ViewPropertyAnimator	translationX(float value) This method will cause the View's translationX property to be animated to the specified value.
ViewPropertyAnimator	translationXBy(float value) This method will cause the View's translationX property to be animated by the specified value.
ViewPropertyAnimator	translationY(float value) This method will cause the View's translationY property to be animated to the specified value.
ViewPropertyAnimator	translationYBy(float value) This method will cause the View's translationY property to be animated by the specified value.
ViewPropertyAnimator	translationZ(float value) This method will cause the View's translationZ property to be animated to the specified value.
ViewPropertyAnimator	translationZBy(float value) This method will cause the View's translationZ property to be animated by the specified value.
ViewPropertyAnimator	withEndAction(Runnable runnable) Specifies an action to take place when the next animation ends.
ViewPropertyAnimator	withLayer() The View associated with this ViewPropertyAnimator will have its layer type set to View#LAYER_TYPE_HARDWARE for the duration of the next animation.
ViewPropertyAnimator	withStartAction(Runnable runnable) Specifies an action to take place when the next animation runs.
ViewPropertyAnimator	x(float value) This method will cause the View's x property to be animated to the specified value.
ViewPropertyAnimator	xBy(float value) This method will cause the View's x property to be animated by the specified value.
ViewPropertyAnimator	y(float value) This method will cause the View's y property to be animated to the specified value.
ViewPropertyAnimator	yBy(float value) This method will cause the View's y property to be animated by the specified value.
ViewPropertyAnimator	z(float value) This method will cause the View's z property to be animated to the specified value.
ViewPropertyAnimator	zBy(float value) This method will cause the View's z property to be animated by the specified value.

Inherited methods

From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Public methods

alpha

Added in API level 12

public ViewPropertyAnimator alpha (float value)

This method will cause the View's alpha property to be animated to the specified value. Animations already running on the property will be canceled.

Parameters
value	float: The value to be animated to. Value is between 0.0f and 1.0f inclusive

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

See also:

• View.setAlpha(float)

alphaBy

Added in API level 12

public ViewPropertyAnimator alphaBy (float value)

This method will cause the View's alpha property to be animated by the specified value. Animations already running on the property will be canceled.

Parameters
value	float: The amount to be animated by, as an offset from the current value.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

See also:

• View.setAlpha(float)

cancel

Added in API level 14

public void cancel ()

Cancels all property animations that are currently running or pending.

getDuration

Added in API level 14

public long getDuration ()

Returns the current duration of property animations. If the duration was set on this object, that value is returned. Otherwise, the default value of the underlying Animator is returned.

Returns
long	The duration of animations, in milliseconds.

See also:

• setDuration(long)

getInterpolator

Added in API level 18

public TimeInterpolator getInterpolator ()

Returns the timing interpolator that this animation uses.

Returns
TimeInterpolator	The timing interpolator for this animation. This value may be null.

getStartDelay

Added in API level 14

public long getStartDelay ()

Returns the current startDelay of property animations. If the startDelay was set on this object, that value is returned. Otherwise, the default value of the underlying Animator is returned.

Returns
long	The startDelay of animations, in milliseconds.

See also:

• setStartDelay(long)

rotation

Added in API level 12

public ViewPropertyAnimator rotation (float value)

This method will cause the View's rotation property to be animated to the specified value. Animations already running on the property will be canceled.

Parameters
value	float: The value to be animated to.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

See also:

• View.setRotation(float)

rotationBy

Added in API level 12

public ViewPropertyAnimator rotationBy (float value)

This method will cause the View's rotation property to be animated by the specified value. Animations already running on the property will be canceled.

Parameters
value	float: The amount to be animated by, as an offset from the current value.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

See also:

• View.setRotation(float)

rotationX

Added in API level 12

public ViewPropertyAnimator rotationX (float value)

This method will cause the View's rotationX property to be animated to the specified value. Animations already running on the property will be canceled.

Parameters
value	float: The value to be animated to.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

See also:

• View.setRotationX(float)

rotationXBy

Added in API level 12

public ViewPropertyAnimator rotationXBy (float value)

This method will cause the View's rotationX property to be animated by the specified value. Animations already running on the property will be canceled.

Parameters
value	float: The amount to be animated by, as an offset from the current value.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

See also:

• View.setRotationX(float)

rotationY

Added in API level 12

public ViewPropertyAnimator rotationY (float value)

This method will cause the View's rotationY property to be animated to the specified value. Animations already running on the property will be canceled.

Parameters
value	float: The value to be animated to.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

See also:

• View.setRotationY(float)

rotationYBy

Added in API level 12

public ViewPropertyAnimator rotationYBy (float value)

This method will cause the View's rotationY property to be animated by the specified value. Animations already running on the property will be canceled.

Parameters
value	float: The amount to be animated by, as an offset from the current value.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

See also:

• View.setRotationY(float)

scaleX

Added in API level 12

public ViewPropertyAnimator scaleX (float value)

This method will cause the View's scaleX property to be animated to the specified value. Animations already running on the property will be canceled.

Parameters
value	float: The value to be animated to.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

See also:

• View.setScaleX(float)

scaleXBy

Added in API level 12

public ViewPropertyAnimator scaleXBy (float value)

This method will cause the View's scaleX property to be animated by the specified value. Animations already running on the property will be canceled.

Parameters
value	float: The amount to be animated by, as an offset from the current value.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

See also:

• View.setScaleX(float)

scaleY

Added in API level 12

public ViewPropertyAnimator scaleY (float value)

This method will cause the View's scaleY property to be animated to the specified value. Animations already running on the property will be canceled.

Parameters
value	float: The value to be animated to.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

See also:

• View.setScaleY(float)

scaleYBy

Added in API level 12

public ViewPropertyAnimator scaleYBy (float value)

This method will cause the View's scaleY property to be animated by the specified value. Animations already running on the property will be canceled.

Parameters
value	float: The amount to be animated by, as an offset from the current value.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

See also:

• View.setScaleY(float)

setDuration

Added in API level 12

public ViewPropertyAnimator setDuration (long duration)

Sets the duration for the underlying animator that animates the requested properties. By default, the animator uses the default value for ValueAnimator. Calling this method will cause the declared value to be used instead.

Parameters
duration	long: The length of ensuing property animations, in milliseconds. The value cannot be negative.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

setInterpolator

Added in API level 12

public ViewPropertyAnimator setInterpolator (TimeInterpolator interpolator)

Sets the interpolator for the underlying animator that animates the requested properties. By default, the animator uses the default interpolator for ValueAnimator. Calling this method will cause the declared object to be used instead.

Parameters
interpolator	TimeInterpolator: The TimeInterpolator to be used for ensuing property animations. A value of null will result in linear interpolation.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

setListener

Added in API level 12

public ViewPropertyAnimator setListener (Animator.AnimatorListener listener)

Sets a listener for events in the underlying Animators that run the property animations.

Parameters
listener	Animator.AnimatorListener: The listener to be called with AnimatorListener events. A value of null removes any existing listener.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

See also:

• Animator.AnimatorListener

setStartDelay

Added in API level 14

public ViewPropertyAnimator setStartDelay (long startDelay)

Sets the startDelay for the underlying animator that animates the requested properties. By default, the animator uses the default value for ValueAnimator. Calling this method will cause the declared value to be used instead.

Parameters
startDelay	long: The delay of ensuing property animations, in milliseconds. The value cannot be negative.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

setUpdateListener

Added in API level 19

public ViewPropertyAnimator setUpdateListener (ValueAnimator.AnimatorUpdateListener listener)

Sets a listener for update events in the underlying ValueAnimator that runs the property animations. Note that the underlying animator is animating between 0 and 1 (these values are then turned into the actual property values internally by ViewPropertyAnimator). So the animator cannot give information on the current values of the properties being animated by this ViewPropertyAnimator, although the view object itself can be queried to get the current values.

Parameters
listener	ValueAnimator.AnimatorUpdateListener: The listener to be called with update events. A value of null removes any existing listener.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

See also:

• ValueAnimator.AnimatorUpdateListener

start

Added in API level 14

public void start ()

Starts the currently pending property animations immediately. Calling start() is optional because all animations start automatically at the next opportunity. However, if the animations are needed to start immediately and synchronously (not at the time when the next event is processed by the hierarchy, which is when the animations would begin otherwise), then this method can be used.

translationX

Added in API level 12

public ViewPropertyAnimator translationX (float value)

This method will cause the View's translationX property to be animated to the specified value. Animations already running on the property will be canceled.

Parameters
value	float: The value to be animated to.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

See also:

• View.setTranslationX(float)

translationXBy

Added in API level 12

public ViewPropertyAnimator translationXBy (float value)

This method will cause the View's translationX property to be animated by the specified value. Animations already running on the property will be canceled.

Parameters
value	float: The amount to be animated by, as an offset from the current value.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

See also:

• View.setTranslationX(float)

translationY

Added in API level 12

public ViewPropertyAnimator translationY (float value)

This method will cause the View's translationY property to be animated to the specified value. Animations already running on the property will be canceled.

Parameters
value	float: The value to be animated to.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

See also:

• View.setTranslationY(float)

translationYBy

Added in API level 12

public ViewPropertyAnimator translationYBy (float value)

This method will cause the View's translationY property to be animated by the specified value. Animations already running on the property will be canceled.

Parameters
value	float: The amount to be animated by, as an offset from the current value.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

See also:

• View.setTranslationY(float)

translationZ

Added in API level 21

public ViewPropertyAnimator translationZ (float value)

This method will cause the View's translationZ property to be animated to the specified value. Animations already running on the property will be canceled.

Parameters
value	float: The value to be animated to.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

See also:

• View.setTranslationZ(float)

translationZBy

Added in API level 21

public ViewPropertyAnimator translationZBy (float value)

This method will cause the View's translationZ property to be animated by the specified value. Animations already running on the property will be canceled.

Parameters
value	float: The amount to be animated by, as an offset from the current value.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

See also:

• View.setTranslationZ(float)

withEndAction

Added in API level 16

public ViewPropertyAnimator withEndAction (Runnable runnable)

Specifies an action to take place when the next animation ends. The action is only run if the animation ends normally; if the ViewPropertyAnimator is canceled during that animation, the runnable will not run. This method, along with withStartAction(java.lang.Runnable), is intended to help facilitate choreographing ViewPropertyAnimator animations with other animations or actions in the application.

For example, the following code animates a view to x=200 and then back to 0:

     Runnable endAction = new Runnable() {
         public void run() {
             view.animate().x(0);
         }
     };
     view.animate().x(200).withEndAction(endAction);
 

Parameters
runnable	Runnable: The action to run when the next animation ends.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

withLayer

Added in API level 16

public ViewPropertyAnimator withLayer ()

The View associated with this ViewPropertyAnimator will have its layer type set to View#LAYER_TYPE_HARDWARE for the duration of the next animation. As stated in the documentation for View#LAYER_TYPE_HARDWARE, the actual type of layer used internally depends on the runtime situation of the view. If the activity and this view are hardware-accelerated, then the layer will be accelerated as well. If the activity or the view is not accelerated, then the layer will effectively be the same as View#LAYER_TYPE_SOFTWARE.

This state is not persistent, either on the View or on this ViewPropertyAnimator: the layer type of the View will be restored when the animation ends to what it was when this method was called, and this setting on ViewPropertyAnimator is only valid for the next animation. Note that calling this method and then independently setting the layer type of the View (by a direct call to View#setLayerType(int, android.graphics.Paint)) will result in some inconsistency, including having the layer type restored to its pre-withLayer() value when the animation ends.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

See also:

• View.setLayerType(int, android.graphics.Paint)

withStartAction

Added in API level 16

public ViewPropertyAnimator withStartAction (Runnable runnable)

Specifies an action to take place when the next animation runs. If there is a startDelay set on this ViewPropertyAnimator, then the action will run after that startDelay expires, when the actual animation begins. This method, along with withEndAction(java.lang.Runnable), is intended to help facilitate choreographing ViewPropertyAnimator animations with other animations or actions in the application.

Parameters
runnable	Runnable: The action to run when the next animation starts.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

x

Added in API level 12

public ViewPropertyAnimator x (float value)

This method will cause the View's x property to be animated to the specified value. Animations already running on the property will be canceled.

Parameters
value	float: The value to be animated to.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

See also:

• View.setX(float)

xBy

Added in API level 12

public ViewPropertyAnimator xBy (float value)

This method will cause the View's x property to be animated by the specified value. Animations already running on the property will be canceled.

Parameters
value	float: The amount to be animated by, as an offset from the current value.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

See also:

• View.setX(float)

y

Added in API level 12

public ViewPropertyAnimator y (float value)

This method will cause the View's y property to be animated to the specified value. Animations already running on the property will be canceled.

Parameters
value	float: The value to be animated to.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

See also:

• View.setY(float)

yBy

Added in API level 12

public ViewPropertyAnimator yBy (float value)

This method will cause the View's y property to be animated by the specified value. Animations already running on the property will be canceled.

Parameters
value	float: The amount to be animated by, as an offset from the current value.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

See also:

• View.setY(float)

z

Added in API level 21

public ViewPropertyAnimator z (float value)

This method will cause the View's z property to be animated to the specified value. Animations already running on the property will be canceled.

Parameters
value	float: The value to be animated to.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

See also:

• View.setZ(float)

zBy

Added in API level 21

public ViewPropertyAnimator zBy (float value)

This method will cause the View's z property to be animated by the specified value. Animations already running on the property will be canceled.

Parameters
value	float: The amount to be animated by, as an offset from the current value.

Returns
ViewPropertyAnimator	This object, allowing calls to methods in this class to be chained. This value cannot be null.

See also:

• View.setZ(float)