RecyclerView.ItemAnimator

public static abstract class RecyclerView.ItemAnimator
extends Object

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


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 dispatchAnimationFinished(ViewHolder) when a ViewHolder's animation is finished. In other words, there must be a matching dispatchAnimationFinished(ViewHolder) call for each animateAppearance(), animateChange() animatePersistence(), and animateDisappearance() call.

By default, RecyclerView uses DefaultItemAnimator.

Summary

Nested classes

@interface RecyclerView.ItemAnimator.AdapterChanges

The set of flags that might be passed to RecyclerView.ItemAnimator.recordPreLayoutInformation(State, ViewHolder, int, List)

interface RecyclerView.ItemAnimator.ItemAnimatorFinishedListener

This interface is used to inform listeners when all pending or running animations in an ItemAnimator are finished. 

class RecyclerView.ItemAnimator.ItemHolderInfo

A simple data structure that holds information about an item's bounds. 

Constants

int FLAG_APPEARED_IN_PRE_LAYOUT

This ViewHolder was not laid out but has been added to the layout in pre-layout state by the RecyclerView.LayoutManager.

int FLAG_CHANGED

The Item represented by this ViewHolder is updated.

int FLAG_INVALIDATED

Adapter RecyclerView.Adapter.notifyDataSetChanged() has been called and the content represented by this ViewHolder is invalid.

int FLAG_MOVED

The position of the Item represented by this ViewHolder has been changed.

int FLAG_REMOVED

The Item represented by this ViewHolder is removed from the adapter.

Public constructors

ItemAnimator()

Public methods

abstract boolean animateAppearance(RecyclerView.ViewHolder viewHolder, RecyclerView.ItemAnimator.ItemHolderInfo preLayoutInfo, RecyclerView.ItemAnimator.ItemHolderInfo postLayoutInfo)

Called by the RecyclerView when a ViewHolder is added to the layout.

abstract boolean animateChange(RecyclerView.ViewHolder oldHolder, RecyclerView.ViewHolder newHolder, RecyclerView.ItemAnimator.ItemHolderInfo preLayoutInfo, RecyclerView.ItemAnimator.ItemHolderInfo postLayoutInfo)

Called by the RecyclerView when an adapter item is present both before and after the layout and RecyclerView has received a RecyclerView.Adapter.notifyItemChanged(int) call for it.

abstract boolean animateDisappearance(RecyclerView.ViewHolder viewHolder, RecyclerView.ItemAnimator.ItemHolderInfo preLayoutInfo, RecyclerView.ItemAnimator.ItemHolderInfo postLayoutInfo)

Called by the RecyclerView when a ViewHolder has disappeared from the layout.

abstract boolean animatePersistence(RecyclerView.ViewHolder viewHolder, RecyclerView.ItemAnimator.ItemHolderInfo preLayoutInfo, RecyclerView.ItemAnimator.ItemHolderInfo postLayoutInfo)

Called by the RecyclerView when a ViewHolder is present in both before and after the layout and RecyclerView has not received a RecyclerView.Adapter.notifyItemChanged(int) call for it or a RecyclerView.Adapter.notifyDataSetChanged() call.

boolean canReuseUpdatedViewHolder(RecyclerView.ViewHolder viewHolder)

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.

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.

final void dispatchAnimationFinished(RecyclerView.ViewHolder viewHolder)

Method to be called by subclasses when an animation is finished.

final void dispatchAnimationStarted(RecyclerView.ViewHolder viewHolder)

Method to be called by subclasses when an animation is started.

final void dispatchAnimationsFinished()

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

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 getChangeDuration()

Gets the current duration for which all change 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.

abstract boolean isRunning()

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

final boolean isRunning(RecyclerView.ItemAnimator.ItemAnimatorFinishedListener listener)

Like isRunning(), this method returns whether there are any item animations currently running.

RecyclerView.ItemAnimator.ItemHolderInfo obtainHolderInfo()

Returns a new RecyclerView.ItemAnimator.ItemHolderInfo which will be used to store information about the ViewHolder.

void onAnimationFinished(RecyclerView.ViewHolder viewHolder)

Called after dispatchAnimationFinished(ViewHolder) is called by the ItemAnimator.

void onAnimationStarted(RecyclerView.ViewHolder viewHolder)

Called when a new animation is started on the given ViewHolder.

RecyclerView.ItemAnimator.ItemHolderInfo recordPostLayoutInformation(RecyclerView.State state, RecyclerView.ViewHolder viewHolder)

Called by the RecyclerView after the layout is complete.

RecyclerView.ItemAnimator.ItemHolderInfo recordPreLayoutInformation(RecyclerView.State state, RecyclerView.ViewHolder viewHolder, int changeFlags, List<Object> payloads)

Called by the RecyclerView before the layout begins.

abstract void runPendingAnimations()

Called when there are pending animations waiting to be started.

void setAddDuration(long addDuration)

Sets the duration for which all add animations will run.

void setChangeDuration(long changeDuration)

Sets the duration for which all change animations will run.

void setMoveDuration(long moveDuration)

Sets the duration for which all move animations will run.

void setRemoveDuration(long removeDuration)

Sets the duration for which all remove animations will run.

Inherited methods

Constants

FLAG_APPEARED_IN_PRE_LAYOUT

public static final int FLAG_APPEARED_IN_PRE_LAYOUT

This ViewHolder was not laid out but has been added to the layout in pre-layout state by the RecyclerView.LayoutManager. This means that the item was already in the Adapter but invisible and it may become visible in the post layout phase. LayoutManagers may prefer to add new items in pre-layout to specify their virtual location when they are invisible (e.g. to specify the item should animate in from below the visible area).

Constant Value: 4096 (0x00001000)

FLAG_CHANGED

public static final int FLAG_CHANGED

The Item represented by this ViewHolder is updated.

Constant Value: 2 (0x00000002)

FLAG_INVALIDATED

public static final int FLAG_INVALIDATED

Adapter RecyclerView.Adapter.notifyDataSetChanged() has been called and the content represented by this ViewHolder is invalid.

Constant Value: 4 (0x00000004)

FLAG_MOVED

public static final int FLAG_MOVED

The position of the Item represented by this ViewHolder has been changed. This flag is not bound to RecyclerView.Adapter.notifyItemMoved(int, int). It might be set in response to any adapter change that may have a side effect on this item. (e.g. The item before this one has been removed from the Adapter).

Constant Value: 2048 (0x00000800)

FLAG_REMOVED

public static final int FLAG_REMOVED

The Item represented by this ViewHolder is removed from the adapter.

Constant Value: 8 (0x00000008)

Public constructors

ItemAnimator

public ItemAnimator ()

Public methods

animateAppearance

public abstract boolean animateAppearance (RecyclerView.ViewHolder viewHolder, 
                RecyclerView.ItemAnimator.ItemHolderInfo preLayoutInfo, 
                RecyclerView.ItemAnimator.ItemHolderInfo postLayoutInfo)

Called by the RecyclerView when a ViewHolder is added to the layout.

In detail, this means that the ViewHolder was not a child when the layout started but has been added by the LayoutManager. It might be newly added to the adapter or simply become visible due to other factors.

ItemAnimator must call dispatchAnimationFinished(ViewHolder) when the animation is complete (or instantly call dispatchAnimationFinished(ViewHolder) if it decides not to animate the view).

Parameters
viewHolder RecyclerView.ViewHolder: The ViewHolder which should be animated

preLayoutInfo RecyclerView.ItemAnimator.ItemHolderInfo: The information that was returned from recordPreLayoutInformation(State, ViewHolder, int, List). Might be null if Item was just added to the adapter or LayoutManager does not support predictive animations or it could not predict that this ViewHolder will become visible.

postLayoutInfo RecyclerView.ItemAnimator.ItemHolderInfo: The information that was returned from recordPreLayoutInformation(State, ViewHolder, int, List).

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

animateChange

public abstract boolean animateChange (RecyclerView.ViewHolder oldHolder, 
                RecyclerView.ViewHolder newHolder, 
                RecyclerView.ItemAnimator.ItemHolderInfo preLayoutInfo, 
                RecyclerView.ItemAnimator.ItemHolderInfo postLayoutInfo)

Called by the RecyclerView when an adapter item is present both before and after the layout and RecyclerView has received a RecyclerView.Adapter.notifyItemChanged(int) call for it. This method may also be called when RecyclerView.Adapter.notifyDataSetChanged() is called and adapter has stable ids so that RecyclerView could still rebind views to the same ViewHolders. If viewType changes when RecyclerView.Adapter.notifyDataSetChanged() is called, this method will not be called, instead, animateAppearance(ViewHolder, ItemHolderInfo, ItemHolderInfo) will be called for the new ViewHolder and the old one will be recycled.

If this method is called due to a RecyclerView.Adapter.notifyDataSetChanged() call, there is a good possibility that item contents didn't really change but it is rebound from the adapter. DefaultItemAnimator will skip animating the View if its location on the screen didn't change and your animator should handle this case as well and avoid creating unnecessary animations.

When an item is updated, ItemAnimator has a chance to ask RecyclerView to keep the previous presentation of the item as-is and supply a new ViewHolder for the updated presentation (see: canReuseUpdatedViewHolder(ViewHolder, List). This is useful if you don't know the contents of the Item and would like to cross-fade the old and the new one (DefaultItemAnimator uses this technique).

When you are writing a custom item animator for your layout, it might be more performant and elegant to re-use the same ViewHolder and animate the content changes manually.

When RecyclerView.Adapter.notifyItemChanged(int) is called, the Item's view type may change. If the Item's view type has changed or ItemAnimator returned false for this ViewHolder when canReuseUpdatedViewHolder(ViewHolder, List) was called, the oldHolder and newHolder will be different ViewHolder instances which represent the same Item. In that case, only the new ViewHolder is visible to the LayoutManager but RecyclerView keeps old ViewHolder attached for animations.

ItemAnimator must call dispatchAnimationFinished(ViewHolder) for each distinct ViewHolder when their animation is complete (or instantly call dispatchAnimationFinished(ViewHolder) if it decides not to animate the view).

If oldHolder and newHolder are the same instance, you should call dispatchAnimationFinished(ViewHolder) only once.

Note that when a ViewHolder both changes and disappears in the same layout pass, the animation callback method which will be called by the RecyclerView depends on the ItemAnimator's decision whether to re-use the same ViewHolder or not, and also the LayoutManager's decision whether to layout the changed version of a disappearing ViewHolder or not. RecyclerView will call animateChange instead of animateDisappearance if and only if the ItemAnimator returns false from canReuseUpdatedViewHolder and the LayoutManager lays out a new disappearing view that holds the updated information. Built-in LayoutManagers try to avoid laying out updated versions of disappearing views.

Parameters
oldHolder RecyclerView.ViewHolder: The ViewHolder before the layout is started, might be the same instance with newHolder.

newHolder RecyclerView.ViewHolder: The ViewHolder after the layout is finished, might be the same instance with oldHolder.

preLayoutInfo RecyclerView.ItemAnimator.ItemHolderInfo: The information that was returned from recordPreLayoutInformation(State, ViewHolder, int, List).

postLayoutInfo RecyclerView.ItemAnimator.ItemHolderInfo: The information that was returned from recordPreLayoutInformation(State, ViewHolder, int, List).

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

animateDisappearance

public abs