RecyclerView.ItemAnimator

This package is part of the
Android support library which
is no longer maintained.
The support library has been superseded by AndroidX
which is part of Jetpack.
We recommend using the AndroidX libraries in all new projects. You should also consider
migrating existing projects to AndroidX.

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.

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.

Constants

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

FLAG_MOVED

The position of the Item represented by this ViewHolder has been changed. This flag is
not bound to 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).

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.

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.

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.

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.

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(State, ViewHolder, int, List).

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(State, ViewHolder) and the
response of that call will be passed to this method as the postLayoutInfo.

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(ViewHolder) and return
false.

canReuseUpdatedViewHolder

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

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

canReuseUpdatedViewHolder

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

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

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 returns true.

endAnimation

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

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

Like isRunning(), this method returns whether there are any item
animations currently running. Additionally, 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

RecyclerView.ItemAnimator.ItemAnimatorFinishedListener: 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

boolean

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

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.