SimpleItemAnimator

public abstract class SimpleItemAnimator extends RecyclerView.ItemAnimator

Known direct subclasses
DefaultItemAnimator

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


A wrapper class for ItemAnimator that records View bounds and decides whether it should run move, change, add or remove animations. This class also replicates the original ItemAnimator API.

It uses RecyclerView.ItemAnimator.ItemHolderInfo to track the bounds information of the Views. If you would like to extend this class, you can override obtainHolderInfo method to provide your own info class that extends RecyclerView.ItemAnimator.ItemHolderInfo.

Summary

Public constructors

Public methods

abstract boolean

Called when an item is added to the RecyclerView.

boolean

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

boolean

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

abstract boolean
animateChange(
    RecyclerView.ViewHolder oldHolder,
    RecyclerView.ViewHolder newHolder,
    int fromLeft,
    int fromTop,
    int toLeft,
    int toTop
)

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

boolean

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

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

Called when an item is moved in the RecyclerView.

boolean

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

abstract boolean

Called when an item is removed from the RecyclerView.

boolean

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).

final void

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

final void

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

final void

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

final void

Method to be called by subclasses when a change animation is being started.

final void

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

final void

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

final void

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

final void

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

boolean

Returns whether this ItemAnimator supports animations of change events.

void

Called when an add animation has ended on the given ViewHolder.

void

Called when an add animation is being started on the given ViewHolder.

void
onChangeFinished(RecyclerView.ViewHolder item, boolean oldItem)

Called when a change animation has ended on the given ViewHolder.

void
onChangeStarting(RecyclerView.ViewHolder item, boolean oldItem)

Called when a change animation is being started on the given ViewHolder.

void

Called when a move animation has ended on the given ViewHolder.

void

Called when a move animation is being started on the given ViewHolder.

void

Called when a remove animation has ended on the given ViewHolder.

void

Called when a remove animation is being started on the given ViewHolder.

void
setSupportsChangeAnimations(boolean supportsChangeAnimations)

Sets whether this ItemAnimator supports animations of item change events.

Inherited Constants

From androidx.recyclerview.widget.RecyclerView.ItemAnimator
static final int

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

static final int

The Item represented by this ViewHolder is updated.

static final int

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

static final int
FLAG_MOVED = 2048

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

static final int

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

Inherited methods

From androidx.recyclerview.widget.RecyclerView.ItemAnimator
boolean

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).

final void

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

final void

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

final void

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

abstract void

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

abstract void

Method called when all item animations should be ended immediately.

long

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

long

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

long

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

long

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

abstract boolean

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

final boolean

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

@NonNull RecyclerView.ItemAnimator.ItemHolderInfo

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

void

Called after dispatchAnimationFinished is called by the ItemAnimator.

void

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

@NonNull RecyclerView.ItemAnimator.ItemHolderInfo

Called by the RecyclerView after the layout is complete.

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

Called by the RecyclerView before the layout begins.

abstract void

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.

Public constructors

SimpleItemAnimator

Added in 1.0.0
public SimpleItemAnimator()

Public methods

animateAdd

Added in 1.0.0
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 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 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 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
RecyclerView.ViewHolder holder

The item that is being added.

Returns
boolean

true if a later call to runPendingAnimations is requested, false otherwise.

animateAppearance

Added in 1.4.0-alpha01
public boolean animateAppearance(
    @NonNull RecyclerView.ViewHolder viewHolder,
    @Nullable RecyclerView.ItemAnimator.ItemHolderInfo preLayoutInfo,
    @NonNull 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 when the animation is complete (or instantly call dispatchAnimationFinished if it decides not to animate the view).

Parameters
@NonNull RecyclerView.ViewHolder viewHolder

The ViewHolder which should be animated

@Nullable RecyclerView.ItemAnimator.ItemHolderInfo preLayoutInfo

The information that was returned from recordPreLayoutInformation. 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.

@NonNull RecyclerView.ItemAnimator.ItemHolderInfo postLayoutInfo

The information that was returned from recordPreLayoutInformation.

Returns
boolean

true if a later call to runPendingAnimations is requested, false otherwise.

animateChange

Added in 1.4.0-alpha01
public boolean animateChange(
    @NonNull RecyclerView.ViewHolder oldHolder,
    @NonNull RecyclerView.ViewHolder newHolder,
    @NonNull RecyclerView.ItemAnimator.ItemHolderInfo preLayoutInfo,
    @NonNull 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 notifyItemChanged call for it. This method may also be called when notifyDataSetChanged is called and adapter has stable ids so that RecyclerView could still rebind views to the same ViewHolders. If viewType changes when notifyDataSetChanged is called, this method will not be called, instead, animateAppearance will be called for the new ViewHolder and the old one will be recycled.

If this method is called due to a 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. 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 notifyItemChanged 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 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 for each distinct ViewHolder when their animation is complete (or instantly call dispatchAnimationFinished if it decides not to animate the view).

If oldHolder and newHolder are the same instance, you should call dispatchAnimationFinishedonly 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
@NonNull RecyclerView.ViewHolder oldHolder

The ViewHolder before the layout is started, might be the same instance with newHolder.

@NonNull RecyclerView.ViewHolder newHolder

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

@NonNull RecyclerView.ItemAnimator.ItemHolderInfo preLayoutInfo

The information that was returned from recordPreLayoutInformation.

@NonNull RecyclerView.ItemAnimator.ItemHolderInfo postLayoutInfo

The information that was returned from recordPreLayoutInformation.

Returns
boolean

true if a later call to runPendingAnimations is requested, false otherwise.

animateChange

Added in 1.0.0
public abstract boolean animateChange(
    RecyclerView.ViewHolder oldHolder,
    RecyclerView.ViewHolder newHolder,
    int fromLeft,
    int fromTop,
    int toLeft,
    int toTop
)

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

Implementers can choose whether and how to animate changes, but must always call dispatchChangeFinished 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 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 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 come in one by one, then start the animations together in the later call to runPendingAnimations.

Parameters
RecyclerView.ViewHolder oldHolder

The original item that changed.

RecyclerView.ViewHolder newHolder

The new item that was created with the changed content. Might be null

int fromLeft

Left of the old view holder

int fromTop

Top of the old view holder

int toLeft

Left of the new view holder

int toTop

Top of the new view holder

Returns
boolean

true if a later call to runPendingAnimations is requested, false otherwise.

animateDisappearance

Added in 1.4.0-alpha01
public boolean animateDisappearance(
    @NonNull RecyclerView.ViewHolder viewHolder,
    @NonNull RecyclerView.ItemAnimator.ItemHolderInfo preLayoutInfo,
    @Nullable RecyclerView.ItemAnimator.ItemHolderInfo postLayoutInfo
)

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

This means that the View was a child of the LayoutManager when layout started but has been removed by the LayoutManager. It might have been removed from the adapter or simply become invisible due to other factors. You can distinguish these two cases by checking the change flags that were passed to recordPreLayoutInformation.

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.

If LayoutManager supports predictive animations, it might provide a target disappear location for the View by laying it out in that location. When that happens, RecyclerView will call recordPostLayoutInformation and the response of that call will be passed to this method as the postLayoutInfo.

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

Parameters
@NonNull RecyclerView.ViewHolder viewHolder

The ViewHolder which should be animated

@NonNull RecyclerView.ItemAnimator.ItemHolderInfo preLayoutInfo

The information that was returned from recordPreLayoutInformation.

@Nullable RecyclerView.ItemAnimator.ItemHolderInfo postLayoutInfo

The information that was returned from recordPostLayoutInformation. Might be null if the LayoutManager did not layout the item.

Returns
boolean

true if a later call to runPendingAnimations is requested, false otherwise.

animateMove

Added in 1.0.0
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 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 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 come in one by one, then start the animations together in the later call to runPendingAnimations.

Parameters
RecyclerView.ViewHolder holder

The item that is being moved.

int fromX

x coordinate from which to start animation.

int fromY

y coordinate from which to start animation.

int toX

x coordinate at which to end animation.

int toY

y coordinate at which to end animation.

Returns
boolean

true if a later call to runPendingAnimations is requested, false otherwise.

animatePersistence

Added in 1.4.0-alpha01
public boolean animatePersistence(
    @NonNull RecyclerView.ViewHolder viewHolder,
    @NonNull RecyclerView.ItemAnimator.ItemHolderInfo preLayoutInfo,
    @NonNull 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 notifyItemChanged call for it or a notifyDataSetChanged call.

This ViewHolder still represents the same data that it was representing when the layout started but its position / size may be changed by the LayoutManager.

If the Item's layout position didn't change, RecyclerView still calls this method because it does not track this information (or does not necessarily know that an animation is not required). Your ItemAnimator should handle this case and if there is nothing to animate, it should call dispatchAnimationFinished and return false.

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

Parameters
@NonNull RecyclerView.ViewHolder viewHolder

The ViewHolder which should be animated

@NonNull RecyclerView.ItemAnimator.ItemHolderInfo preLayoutInfo

The information that was returned from recordPreLayoutInformation.

@NonNull RecyclerView.ItemAnimator.ItemHolderInfo postLayoutInfo

The information that was returned from recordPreLayoutInformation.

Returns
boolean

true if a later call to runPendingAnimations is requested, false otherwise.

animateRemove

Added in 1.0.0
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 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 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 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
RecyclerView.ViewHolder holder

The item that is being removed.

Returns
boolean

true if a later call to runPendingAnimations is requested, false otherwise.

canReuseUpdatedViewHolder

public boolean canReuseUpdatedViewHolder(@NonNull 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. cross-fade).

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

If your application is using change payloads, you can override #canReuseUpdatedViewHolder(ViewHolder, List) to decide based on payloads.

Returns
boolean

True if change animations are not supported or the ViewHolder is invalid, false otherwise.

dispatchAddFinished

Added in 1.0.0
public final void dispatchAddFinished(RecyclerView.ViewHolder item)

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

Parameters
RecyclerView.ViewHolder item

The item which has been added

dispatchAddStarting

Added in 1.0.0
public final void dispatchAddStarting(RecyclerView.ViewHolder item)

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

Parameters
RecyclerView.ViewHolder item

The item being added

dispatchChangeFinished

Added in 1.0.0
public final void dispatchChangeFinished(RecyclerView.ViewHolder item, boolean oldItem)

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

Parameters
RecyclerView.ViewHolder item

The item which has been changed (this method must be called for each non-null ViewHolder passed into animateChange).

boolean oldItem

true if this is the old item that was changed, false if it is the new item that replaced the old item.

See also
animateChange

dispatchChangeStarting

Added in 1.0.0
public final void dispatchChangeStarting(RecyclerView.ViewHolder item, boolean oldItem)

Method to be called by subclasses when a change animation is being started.

Parameters
RecyclerView.ViewHolder item

The item which has been changed (this method must be called for each non-null ViewHolder passed into animateChange).

boolean oldItem

true if this is the old item that was changed, false if it is the new item that replaced the old item.

dispatchMoveFinished

Added in 1.0.0
public final void dispatchMoveFinished(RecyclerView.ViewHolder item)

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

Parameters
RecyclerView.ViewHolder item

The item which has been moved

dispatchMoveStarting

Added in 1.0.0
public final void dispatchMoveStarting(RecyclerView.ViewHolder item)

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

Parameters
RecyclerView.ViewHolder item

The item being moved

dispatchRemoveFinished

Added in 1.0.0
public final void dispatchRemoveFinished(RecyclerView.ViewHolder item)

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

Parameters
RecyclerView.ViewHolder item

The item which has been removed

dispatchRemoveStarting

Added in 1.0.0
public final void dispatchRemoveStarting(RecyclerView.ViewHolder item)

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

Parameters
RecyclerView.ViewHolder item

The item being removed

getSupportsChangeAnimations

Added in 1.0.0
public boolean getSupportsChangeAnimations()

Returns whether this ItemAnimator supports animations of change events.

Returns
boolean

true if change animations are supported, false otherwise

onAddFinished

Added in 1.0.0
public void onAddFinished(RecyclerView.ViewHolder item)

Called when an add animation has ended on the given ViewHolder. The default implementation does nothing. Subclasses may wish to override this method to handle any ViewHolder-specific operations linked to animation lifecycles.

Parameters
RecyclerView.ViewHolder item

The ViewHolder being animated.

onAddStarting

Added in 1.0.0
public void onAddStarting(RecyclerView.ViewHolder item)

Called when an add animation is being started on the given ViewHolder. The default implementation does nothing. Subclasses may wish to override this method to handle any ViewHolder-specific operations linked to animation lifecycles.

Parameters
RecyclerView.ViewHolder item

The ViewHolder being animated.

onChangeFinished

Added in 1.0.0
public void onChangeFinished(RecyclerView.ViewHolder item, boolean oldItem)

Called when a change animation has ended on the given ViewHolder. The default implementation does nothing. Subclasses may wish to override this method to handle any ViewHolder-specific operations linked to animation lifecycles.

Parameters
RecyclerView.ViewHolder item

The ViewHolder being animated.

boolean oldItem

true if this is the old item that was changed, false if it is the new item that replaced the old item.

onChangeStarting

Added in 1.0.0
public void onChangeStarting(RecyclerView.ViewHolder item, boolean oldItem)

Called when a change animation is being started on the given ViewHolder. The default implementation does nothing. Subclasses may wish to override this method to handle any ViewHolder-specific operations linked to animation lifecycles.

Parameters
RecyclerView.ViewHolder item

The ViewHolder being animated.

boolean oldItem

true if this is the old item that was changed, false if it is the new item that replaced the old item.

onMoveFinished

Added in 1.0.0
public void onMoveFinished(RecyclerView.ViewHolder item)

Called when a move animation has ended on the given ViewHolder. The default implementation does nothing. Subclasses may wish to override this method to handle any ViewHolder-specific operations linked to animation lifecycles.

Parameters
RecyclerView.ViewHolder item

The ViewHolder being animated.

onMoveStarting

Added in 1.0.0
public void onMoveStarting(RecyclerView.ViewHolder item)

Called when a move animation is being started on the given ViewHolder. The default implementation does nothing. Subclasses may wish to override this method to handle any ViewHolder-specific operations linked to animation lifecycles.

Parameters
RecyclerView.ViewHolder item

The ViewHolder being animated.

onRemoveFinished

Added in 1.0.0
public void onRemoveFinished(RecyclerView.ViewHolder item)

Called when a remove animation has ended on the given ViewHolder. The default implementation does nothing. Subclasses may wish to override this method to handle any ViewHolder-specific operations linked to animation lifecycles.

Parameters
RecyclerView.ViewHolder item

The ViewHolder being animated.

onRemoveStarting

Added in 1.0.0
public void onRemoveStarting(RecyclerView.ViewHolder item)

Called when a remove animation is being started on the given ViewHolder. The default implementation does nothing. Subclasses may wish to override this method to handle any ViewHolder-specific operations linked to animation lifecycles.

Parameters
RecyclerView.ViewHolder item

The ViewHolder being animated.

setSupportsChangeAnimations

Added in 1.0.0
public void setSupportsChangeAnimations(boolean supportsChangeAnimations)

Sets whether this ItemAnimator supports animations of item change events. If you set this property to false, actions on the data set which change the contents of items will not be animated. What those animations do is left up to the discretion of the ItemAnimator subclass, in its animateChange implementation. The value of this property is true by default.

Parameters
boolean supportsChangeAnimations

true if change animations are supported by this ItemAnimator, false otherwise. If the property is false, the ItemAnimator will not receive a call to animateChange when changes occur.