ItemAnimator

FLAG_APPEARED_IN_PRE_LAYOUT

static val FLAG_APPEARED_IN_PRE_LAYOUT: Int

This ViewHolder was not laid out but has been added to the layout in pre-layout state by the 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).

Value: ViewHolder.FLAG_APPEARED_IN_PRE_LAYOUT

FLAG_CHANGED

static val FLAG_CHANGED: Int

The Item represented by this ViewHolder is updated.

Value: ViewHolder.FLAG_UPDATE

FLAG_INVALIDATED

static val FLAG_INVALIDATED: Int

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

Value: ViewHolder.FLAG_INVALID

FLAG_MOVED

static val FLAG_MOVED: Int

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

Value: ViewHolder.FLAG_MOVED

FLAG_REMOVED

static val FLAG_REMOVED: Int

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

Value: ViewHolder.FLAG_REMOVED

<init>

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.

animateAppearance

abstract fun animateAppearance(
    @NonNull viewHolder: RecyclerView.ViewHolder, 
    @Nullable preLayoutInfo: RecyclerView.ItemAnimator.ItemHolderInfo?, 
    @NonNull postLayoutInfo: RecyclerView.ItemAnimator.ItemHolderInfo
): Boolean

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

animateChange

abstract fun animateChange(
    @NonNull oldHolder: RecyclerView.ViewHolder, 
    @NonNull newHolder: RecyclerView.ViewHolder, 
    @NonNull preLayoutInfo: RecyclerView.ItemAnimator.ItemHolderInfo, 
    @NonNull postLayoutInfo: RecyclerView.ItemAnimator.ItemHolderInfo
): Boolean

Called by the RecyclerView when an adapter item is present both before and after the layout and RecyclerView has received a Adapter#notifyItemChanged(int) call for it. This method may also be called when Adapter#notifyDataSetChanged() is called and adapter has stable ids so that RecyclerView could still rebind views to the same ViewHolders. If viewType changes when 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 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 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.

animateDisappearance

abstract fun animateDisappearance(
    @NonNull viewHolder: RecyclerView.ViewHolder, 
    @NonNull preLayoutInfo: RecyclerView.ItemAnimator.ItemHolderInfo, 
    @Nullable postLayoutInfo: RecyclerView.ItemAnimator.ItemHolderInfo?
): Boolean

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.

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

animatePersistence

abstract fun animatePersistence(
    @NonNull viewHolder: RecyclerView.ViewHolder, 
    @NonNull preLayoutInfo: RecyclerView.ItemAnimator.ItemHolderInfo, 
    @NonNull postLayoutInfo: RecyclerView.ItemAnimator.ItemHolderInfo
): Boolean

Called by the RecyclerView when a ViewHolder is present in both before and after the layout and RecyclerView has not received a Adapter#notifyItemChanged(int) call for it or a Adapter#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(ViewHolder) and return false.

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

canReuseUpdatedViewHolder

open fun canReuseUpdatedViewHolder(@NonNull viewHolder: RecyclerView.ViewHolder): 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).

Note that this method will only be called if the ViewHolder still has the same type (Adapter#getItemViewType(int)). Otherwise, ItemAnimator will always receive both ViewHolders 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.

canReuseUpdatedViewHolder

open fun canReuseUpdatedViewHolder(
    @NonNull viewHolder: RecyclerView.ViewHolder, 
    @NonNull payloads: MutableList<Any!>
): 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).

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

dispatchAnimationFinished

fun dispatchAnimationFinished(@NonNull viewHolder: RecyclerView.ViewHolder): Unit

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

For each call RecyclerView makes to animateAppearance(), animatePersistence(), or animateDisappearance(), there should be a matching dispatchAnimationFinished(ViewHolder) call by the subclass.

For animateChange(), subclass should call this method for both the oldHolder and newHolder (if they are not the same instance).

dispatchAnimationStarted

fun dispatchAnimationStarted(@NonNull viewHolder: RecyclerView.ViewHolder): Unit

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

For each call RecyclerView makes to animateAppearance(), animatePersistence(), or animateDisappearance(), there should be a matching dispatchAnimationStarted(ViewHolder) call by the subclass.

For animateChange(), subclass should call this method for both the oldHolder and newHolder (if they are not the same instance).

If your ItemAnimator decides not to animate a ViewHolder, it should call dispatchAnimationFinished(ViewHolder) without calling dispatchAnimationStarted(ViewHolder).

dispatchAnimationsFinished

fun dispatchAnimationsFinished(): Unit

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

endAnimation

abstract fun endAnimation(@NonNull item: RecyclerView.ViewHolder): Unit

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.

endAnimations

abstract fun endAnimations(): Unit

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.

getAddDuration

open fun getAddDuration(): Long

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

getChangeDuration

open fun getChangeDuration(): Long

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

getMoveDuration

open fun getMoveDuration(): Long

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

getRemoveDuration

open fun getRemoveDuration(): Long

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

isRunning

abstract fun isRunning(): Boolean

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.

isRunning

fun isRunning(@Nullable listener: RecyclerView.ItemAnimator.ItemAnimatorFinishedListener?): Boolean

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.

obtainHolderInfo

@NonNull open fun obtainHolderInfo(): RecyclerView.ItemAnimator.ItemHolderInfo

Returns a new ItemHolderInfo which will be used to store information about the ViewHolder. This information will later be passed into animate** methods.

You can override this method if you want to extend ItemHolderInfo and provide your own instances.

onAnimationFinished

open fun onAnimationFinished(@NonNull viewHolder: RecyclerView.ViewHolder): Unit

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

onAnimationStarted

open fun onAnimationStarted(@NonNull viewHolder: RecyclerView.ViewHolder): Unit

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

recordPostLayoutInformation

@NonNull open fun recordPostLayoutInformation(
    @NonNull state: RecyclerView.State, 
    @NonNull viewHolder: RecyclerView.ViewHolder
): RecyclerView.ItemAnimator.ItemHolderInfo

Called by the RecyclerView after the layout is complete. Item animator should record necessary information about the View's final state.

The data returned from this method will be passed to the related animate** methods.

The default implementation returns an ItemHolderInfo which holds the bounds of the View.

recordPreLayoutInformation

@NonNull open fun recordPreLayoutInformation(
    @NonNull state: RecyclerView.State, 
    @NonNull viewHolder: RecyclerView.ViewHolder, 
    changeFlags: Int, 
    @NonNull payloads: MutableList<Any!>
): RecyclerView.ItemAnimator.ItemHolderInfo

Called by the RecyclerView before the layout begins. Item animator should record necessary information about the View before it is potentially rebound, moved or removed.

The data returned from this method will be passed to the related animate** methods.

Note that this method may be called after pre-layout phase if LayoutManager adds new Views to the layout in pre-layout pass.

The default implementation returns an ItemHolderInfo which holds the bounds of the View and the adapter change flags.

runPendingAnimations

abstract fun runPendingAnimations(): Unit

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.

setAddDuration

open fun setAddDuration(addDuration: Long): Unit

Sets the duration for which all add animations will run.

setChangeDuration

open fun setChangeDuration(changeDuration: Long): Unit

Sets the duration for which all change animations will run.

setMoveDuration

open fun setMoveDuration(moveDuration: Long): Unit

Sets the duration for which all move animations will run.

setRemoveDuration

open fun setRemoveDuration(removeDuration: Long): Unit

Sets the duration for which all remove animations will run.