Stay organized with collections Save and categorize content based on your preferences.
added in version 24.1.0
belongs to Maven artifact com.android.support:recyclerview-v7:28.0.0-alpha1

SimpleItemAnimator

public abstract class SimpleItemAnimator
extends RecyclerView.ItemAnimator

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


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

Inherited constants

From class android.support.v7.widget.RecyclerView.ItemAnimator

Public constructors

SimpleItemAnimator()

Public methods

abstract boolean animateAdd(RecyclerView.ViewHolder holder)

Called when an item is added to the RecyclerView.

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, int fromLeft, int fromTop, int toLeft, int toTop)

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

boolean animateChange(RecyclerView.ViewHolder oldHolder, RecyclerView.ViewHolder newHolder, RecyclerView.ItemAnimator.ItemHolderInfo preInfo, RecyclerView.ItemAnimator.ItemHolderInfo postInfo)

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

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 animateMove(RecyclerView.ViewHolder holder, int fromX, int fromY, int toX, int toY)

Called when an item is moved in the RecyclerView.

boolean animatePersistence(RecyclerView.ViewHolder viewHolder, RecyclerView.ItemAnimator.ItemHolderInfo preInfo, RecyclerView.ItemAnimator.ItemHolderInfo postInfo)

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

abstract boolean animateRemove(RecyclerView.ViewHolder holder)

Called when an item is removed from the RecyclerView.

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.

final void dispatchAddFinished(RecyclerView.ViewHolder item)

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

final void dispatchAddStarting(RecyclerView.ViewHolder item)

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

final void dispatchChangeFinished(RecyclerView.ViewHolder item, boolean oldItem)

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

final void dispatchChangeStarting(RecyclerView.ViewHolder item, boolean oldItem)

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

final void dispatchMoveFinished(RecyclerView.ViewHolder item)

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

final void dispatchMoveStarting(RecyclerView.ViewHolder item)

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

final void dispatchRemoveFinished(RecyclerView.ViewHolder item)

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

final void dispatchRemoveStarting(RecyclerView.ViewHolder item)

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

boolean getSupportsChangeAnimations()

Returns whether this ItemAnimator supports animations of change events.

void onAddFinished(RecyclerView.ViewHolder item)

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

void onAddStarting(RecyclerView.ViewHolder item)

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 onMoveFinished(RecyclerView.ViewHolder item)

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

void onMoveStarting(RecyclerView.ViewHolder item)

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

void onRemoveFinished(RecyclerView.ViewHolder item)

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

void onRemoveStarting(RecyclerView.ViewHolder item)

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 methods

From class android.support.v7.widget.RecyclerView.ItemAnimator
From class java.lang.Object

Public constructors

SimpleItemAnimator

added in version 24.1.0
SimpleItemAnimator ()

Public methods

animateAdd

added in version 24.1.0
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 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(ViewHolder, ViewHolder, int, int, int, int) 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 RecyclerView.ViewHolder: The item that is being added.

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

animateAppearance

added in version 24.1.0
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

added in version 24.1.0
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(int) or notifyItemRangeChanged(int, int).

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

fromLeft int: Left of the old view holder

fromTop int: Top of the old view holder

toLeft int: Left of the new view holder

toTop int: Top of the new view holder

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

animateChange

added in version 24.1.0
boolean animateChange (RecyclerView.ViewHolder oldHolder, 
                RecyclerView.ViewHolder newHolder, 
                RecyclerView.ItemAnimator.ItemHolderInfo preInfo, 
                RecyclerView.ItemAnimator.ItemHolderInfo postInfo)

Called by the RecyclerView when an adapter item is present both before and after the layout and RecyclerView has received a notifyItemChanged(int) 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(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 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 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.

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

postInfo