Android APIs
public static abstract class

RecyclerView.ItemAnimator

extends Object
java.lang.Object
   ↳ android.support.v7.widget.RecyclerView.ItemAnimator
Known Direct Subclasses

Class Overview

This class defines the animations that take place on items as changes are made to the adapter. Subclasses of ItemAnimator can be used to implement custom animations for actions on ViewHolder items. The RecyclerView will manage retaining these items while they are being animated, but implementors must call the appropriate "Finished" method when each item animation is done (dispatchRemoveFinished(ViewHolder), dispatchMoveFinished(ViewHolder), or dispatchAddFinished(ViewHolder)).

By default, RecyclerView uses DefaultItemAnimator

Summary

Nested Classes
interface RecyclerView.ItemAnimator.ItemAnimatorFinishedListener This interface is used to inform listeners when all pending or running animations in an ItemAnimator are finished. 
Public Constructors
RecyclerView.ItemAnimator()
Public Methods
abstract boolean animateAdd(RecyclerView.ViewHolder holder)
Called when an item is added to the RecyclerView.
abstract boolean animateMove(RecyclerView.ViewHolder holder, int fromX, int fromY, int toX, int toY)
Called when an item is moved in the RecyclerView.
abstract boolean animateRemove(RecyclerView.ViewHolder holder)
Called when an item is removed from the RecyclerView.
final void dispatchAddFinished(RecyclerView.ViewHolder item)
Method to be called by subclasses when an add animation is done.
final void dispatchAnimationsFinished()
This method should be called by ItemAnimator implementations to notify any listeners that all pending and active item animations are finished.
final void dispatchMoveFinished(RecyclerView.ViewHolder item)
Method to be called by subclasses when a move animation is done.
final void dispatchRemoveFinished(RecyclerView.ViewHolder item)
Method to be called by subclasses when a remove animation is done.
abstract void endAnimation(RecyclerView.ViewHolder item)
Method called when an animation on a view should be ended immediately.
abstract void endAnimations()
Method called when all item animations should be ended immediately.
long getAddDuration()
Gets the current duration for which all add animations will run.
long getMoveDuration()
Gets the current duration for which all move animations will run.
long getRemoveDuration()
Gets the current duration for which all remove animations will run.
final boolean isRunning(RecyclerView.ItemAnimator.ItemAnimatorFinishedListener listener)
Like isRunning(), this method returns whether there are any item animations currently running.
abstract boolean isRunning()
Method which returns whether there are any item animations currently running.
abstract void runPendingAnimations()
Called when there are pending animations waiting to be started.
void setAddDuration(long addDuration)
Sets the current duration for which all add animations will run.
void setMoveDuration(long moveDuration)
Sets the current duration for which all move animations will run.
void setRemoveDuration(long removeDuration)
Sets the current duration for which all remove animations will run.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public RecyclerView.ItemAnimator ()

Public Methods

public abstract boolean animateAdd (RecyclerView.ViewHolder holder)

Called when an item is added to the RecyclerView. Implementors can choose whether and how to animate that change, but must always call dispatchAddFinished(ViewHolder) when done, either immediately (if no animation will occur) or after the animation actually finishes. The return value indicates whether an animation has been set up and whether the ItemAnimators runPendingAnimations() method should be called at the next opportunity. This mechanism allows ItemAnimator to set up individual animations as separate calls to animateAdd(), animateMove(), and animateRemove() come in one by one, then start the animations together in the later call to runPendingAnimations().

This method may also be called for appearing items which were already in the RecyclerView, but for which the system does not have enough information to animate them into view. In that case, the default animation for adding items is run on those items as well.

Parameters
holder The item that is being added.
Returns

public abstract boolean animateMove (RecyclerView.ViewHolder holder, int fromX, int fromY, int toX, int toY)

Called when an item is moved in the RecyclerView. Implementors can choose whether and how to animate that change, but must always call dispatchMoveFinished(ViewHolder) when done, either immediately (if no animation will occur) or after the animation actually finishes. The return value indicates whether an animation has been set up and whether the ItemAnimators runPendingAnimations() method should be called at the next opportunity. This mechanism allows ItemAnimator to set up individual animations as separate calls to animateAdd(), animateMove(), and animateRemove() come in one by one, then start the animations together in the later call to runPendingAnimations().

Parameters
holder The item that is being moved.
Returns

public abstract boolean animateRemove (RecyclerView.ViewHolder holder)

Called when an item is removed from the RecyclerView. Implementors can choose whether and how to animate that change, but must always call dispatchRemoveFinished(ViewHolder) when done, either immediately (if no animation will occur) or after the animation actually finishes. The return value indicates whether an animation has been set up and whether the ItemAnimators runPendingAnimations() method should be called at the next opportunity. This mechanism allows ItemAnimator to set up individual animations as separate calls to animateAdd(), animateMove(), and animateRemove() come in one by one, then start the animations together in the later call to runPendingAnimations().

This method may also be called for disappearing items which continue to exist in the RecyclerView, but for which the system does not have enough information to animate them out of view. In that case, the default animation for removing items is run on those items as well.

Parameters
holder The item that is being removed.
Returns

public final void dispatchAddFinished (RecyclerView.ViewHolder item)

Method to be called by subclasses when an add animation is done.

Parameters
item The item which has been added

public final void dispatchAnimationsFinished ()

This method should be called by ItemAnimator implementations to notify any listeners that all pending and active item animations are finished.

public final void dispatchMoveFinished (RecyclerView.ViewHolder item)

Method to be called by subclasses when a move animation is done.

Parameters
item The item which has been moved

public final void dispatchRemoveFinished (RecyclerView.ViewHolder item)

Method to be called by subclasses when a remove animation is done.

Parameters
item The item which has been removed

public abstract void endAnimation (RecyclerView.ViewHolder item)

Method called when an animation on a view should be ended immediately. This could happen when other events, like scrolling, occur, so that animating views can be quickly put into their proper end locations. Implementations should ensure that any animations running on the item are canceled and affected properties are set to their end values. Also, appropriate dispatch methods (e.g., dispatchAddFinished(ViewHolder) should be called since the animations are effectively done when this method is called.

Parameters
item The item for which an animation should be stopped.

public abstract void endAnimations ()

Method called when all item animations should be ended immediately. This could happen when other events, like scrolling, occur, so that animating views can be quickly put into their proper end locations. Implementations should ensure that any animations running on any items are canceled and affected properties are set to their end values. Also, appropriate dispatch methods (e.g., dispatchAddFinished(ViewHolder) should be called since the animations are effectively done when this method is called.

public long getAddDuration ()

Gets the current duration for which all add animations will run.

Returns
  • The current add duration

public long getMoveDuration ()

Gets the current duration for which all move animations will run.

Returns
  • The current move duration

public long getRemoveDuration ()

Gets the current duration for which all remove animations will run.

Returns
  • The current remove duration

public final boolean isRunning (RecyclerView.ItemAnimator.ItemAnimatorFinishedListener listener)

Like isRunning(), this method returns whether there are any item animations currently running. Addtionally, the listener passed in will be called when there are no item animations running, either immediately (before the method returns) if no animations are currently running, or when the currently running animations are finished.

Note that the listener is transient - it is either called immediately and not stored at all, or stored only until it is called when running animations are finished sometime later.

Parameters
listener A listener to be called immediately if no animations are running or later when currently-running animations have finished. A null listener is equivalent to calling isRunning().
Returns
  • true if there are any item animations currently running, false otherwise.

public abstract boolean isRunning ()

Method which returns whether there are any item animations currently running. This method can be used to determine whether to delay other actions until animations end.

Returns
  • true if there are any item animations currently running, false otherwise.

public abstract void runPendingAnimations ()

Called when there are pending animations waiting to be started. This state is governed by the return values from animateAdd(), animateMove(), and animateRemove(), which inform the RecyclerView that the ItemAnimator wants to be called later to start the associated animations. runPendingAnimations() will be scheduled to be run on the next frame.

public void setAddDuration (long addDuration)

Sets the current duration for which all add animations will run.

Parameters
addDuration The current add duration

public void setMoveDuration (long moveDuration)

Sets the current duration for which all move animations will run.

Parameters
moveDuration The current move duration

public void setRemoveDuration (long removeDuration)

Sets the current duration for which all remove animations will run.

Parameters
removeDuration The current remove duration