added in version 1.0.0
belongs to Maven artifact androidx.recyclerview:recyclerview:1.0.0-beta01

DefaultItemAnimator

public class DefaultItemAnimator
extends SimpleItemAnimator

java.lang.Object
   ↳ androidx.recyclerview.widget.RecyclerView.ItemAnimator
     ↳ androidx.recyclerview.widget.SimpleItemAnimator
       ↳ androidx.recyclerview.widget.DefaultItemAnimator


This implementation of RecyclerView.ItemAnimator provides basic animations on remove, add, and move events that happen to the items in a RecyclerView. RecyclerView uses a DefaultItemAnimator by default.

Summary

Inherited constants

Public constructors

DefaultItemAnimator()

Public methods

boolean animateAdd(RecyclerView.ViewHolder holder)

Called when an item is added to the RecyclerView.

boolean animateChange(RecyclerView.ViewHolder oldHolder, RecyclerView.ViewHolder newHolder, int fromX, int fromY, int toX, int toY)

Called when an item is changed in the RecyclerView, as indicated by a call to RecyclerView.Adapter.notifyItemChanged(int) or RecyclerView.Adapter.notifyItemRangeChanged(int, int).

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

Called when an item is moved in the RecyclerView.

boolean animateRemove(RecyclerView.ViewHolder holder)

Called when an item is removed from the RecyclerView.

boolean canReuseUpdatedViewHolder(RecyclerView.ViewHolder viewHolder, List<Object> payloads)

When an item is changed, ItemAnimator can decide whether it wants to re-use the same ViewHolder for animations or RecyclerView should create a copy of the item and ItemAnimator will use both to run the animation (e.g.

If the payload list is not empty, DefaultItemAnimator returns true.

void endAnimation(RecyclerView.ViewHolder item)

Method called when an animation on a view should be ended immediately.

void endAnimations()

Method called when all item animations should be ended immediately.

boolean isRunning()

Method which returns whether there are any item animations currently running.

void runPendingAnimations()

Called when there are pending animations waiting to be started.

Inherited methods

Public constructors

DefaultItemAnimator

added in version 1.0.0
public DefaultItemAnimator ()

Public methods

animateAdd

added in version 1.0.0
public 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(RecyclerView.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 ItemAnimator's RecyclerView.ItemAnimator.runPendingAnimations() method should be called at the next opportunity. This mechanism allows ItemAnimator to set up individual animations as separate calls to animateAdd(), animateMove(), animateRemove(), and animateChange(RecyclerView.ViewHolder, RecyclerView.ViewHolder, int, int, int, int) come in one by one, then start the animations together in the later call to RecyclerView.ItemAnimator.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 RecyclerView.ViewHolder: The item that is being added.

Returns
boolean true if a later call to RecyclerView.ItemAnimator.runPendingAnimations() is requested, false otherwise.

animateChange

added in version 1.0.0
public boolean animateChange (RecyclerView.ViewHolder oldHolder, 
                RecyclerView.ViewHolder newHolder, 
                int fromX, 
                int fromY, 
                int toX, 
                int toY)

Called when an item is changed in the RecyclerView, as indicated by a call to RecyclerView.Adapter.notifyItemChanged(int) or RecyclerView.Adapter.notifyItemRangeChanged(int, int).

Implementers can choose whether and how to animate changes, but must always call dispatchChangeFinished(RecyclerView.ViewHolder, boolean) for each non-null distinct ViewHolder, either immediately (if no animation will occur) or after the animation actually finishes. If the oldHolder is the same ViewHolder as the newHolder, you must call dispatchChangeFinished(RecyclerView.ViewHolder, boolean) once and only once. In that case, the second parameter of dispatchChangeFinished is ignored.

The return value indicates whether an animation has been set up and whether the ItemAnimator's RecyclerView.ItemAnimator.runPendingAnimations() method should be called at the next opportunity. This mechanism allows ItemAnimator to set up individual animations as separate calls to animateAdd(), animateMove(), animateRemove(), and animateChange(RecyclerView.ViewHolder, RecyclerView.ViewHolder, int, int, int, int) come in one by one, then start the animations together in the later call to RecyclerView.ItemAnimator.runPendingAnimations().

Parameters
oldHolder RecyclerView.ViewHolder: The original item that changed.

newHolder RecyclerView.ViewHolder: The new item that was created with the changed content. Might be null

fromX int: Left of the old view holder

fromY int: Top of the old view holder

toX int: Left of the new view holder

toY int: Top of the new view holder

Returns
boolean true if a later call to RecyclerView.ItemAnimator.runPendingAnimations() is requested, false otherwise.

animateMove

added in version 1.0.0
public 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(RecyclerView.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 ItemAnimator's RecyclerView.ItemAnimator.runPendingAnimations() method should be called at the next opportunity. This mechanism allows ItemAnimator to set up individual animations as separate calls to animateAdd(), animateMove(), animateRemove(), and animateChange(RecyclerView.ViewHolder, RecyclerView.ViewHolder, int, int, int, int) come in one by one, then start the animations together in the later call to RecyclerView.ItemAnimator.runPendingAnimations().

Parameters
holder RecyclerView.ViewHolder: The item that is being moved.

fromX int

fromY int

toX int

toY int

Returns
boolean true if a later call to RecyclerView.ItemAnimator.runPendingAnimations() is requested, false otherwise.

animateRemove

added in version 1.0.0
public 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(RecyclerView.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 ItemAnimator's RecyclerView.ItemAnimator.runPendingAnimations() method should be called at the next opportunity. This mechanism allows ItemAnimator to set up individual animations as separate calls to animateAdd(), animateMove(), animateRemove(), and animateChange(RecyclerView.ViewHolder, RecyclerView.ViewHolder, int, int, int, int) come in one by one, then start the animations together in the later call to RecyclerView.ItemAnimator.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 RecyclerView.ViewHolder: The item that is being removed.

Returns
boolean true if a later call to RecyclerView.ItemAnimator.runPendingAnimations() is requested, false otherwise.

canReuseUpdatedViewHolder

added in version 1.0.0
public boolean canReuseUpdatedViewHolder (RecyclerView.ViewHolder viewHolder, 
                List<Object> payloads)

When an item is changed, ItemAnimator can decide whether it wants to re-use the same ViewHolder for animations or RecyclerView should create a copy of the item and ItemAnimator will use both to run the animation (e.g. cross-fade).

Note that this method will only be called if the RecyclerView.ViewHolder still has the same type (RecyclerView.Adapter.getItemViewType(int)). Otherwise, ItemAnimator will always receive both RecyclerView.ViewHolders in the animateChange(ViewHolder, ViewHolder, ItemHolderInfo, ItemHolderInfo) method.

If the payload list is not empty, DefaultItemAnimator returns true. When this is the case:

Parameters
viewHolder RecyclerView.ViewHolder: The ViewHolder which represents the changed item's old content.

payloads List: A non-null list of merged payloads that were sent with change notifications. Can be empty if the adapter is invalidated via RecyclerView.Adapter.notifyDataSetChanged(). The same list of payloads will be passed into RecyclerView.Adapter.onBindViewHolder(ViewHolder, int, List) method if this method returns true.

Returns
boolean True if RecyclerView should just rebind to the same ViewHolder or false if RecyclerView should create a new ViewHolder and pass this ViewHolder to the ItemAnimator to animate. Default implementation calls canReuseUpdatedViewHolder(ViewHolder).

endAnimation

added in version 1.0.0
public 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, dispatchAnimationFinished(ViewHolder) should be called for each finished animation since the animations are effectively done when this method is called.

Parameters
item RecyclerView.ViewHolder: The item for which an animation should be stopped.

endAnimations

added in version 1.0.0
public 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, dispatchAnimationFinished(ViewHolder) should be called for each finished animation since the animations are effectively done when this method is called.

isRunning

added in version 1.0.0
public 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
boolean true if there are any item animations currently running, false otherwise.

runPendingAnimations

added in version 1.0.0
public void runPendingAnimations ()

Called when there are pending animations waiting to be started. This state is governed by the return values from animateAppearance(), animateChange() animatePersistence(), and animateDisappearance(), 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.