Package 

Class SimpleItemAnimator

  • 
public abstract class SimpleItemAnimator
extends RecyclerView.ItemAnimator

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

    • Method Detail

      • getSupportsChangeAnimations

         boolean getSupportsChangeAnimations()

        Returns whether this ItemAnimator supports animations of change events.

      • setSupportsChangeAnimations

         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 thecontents of items will not be animated. What those animations do is leftup to the discretion of the ItemAnimator subclass, in its animateChange implementation.The value of this property is true by default.

        Parameters:
        supportsChangeAnimations - true if change animations are supported bythis ItemAnimator, false otherwise.

      • canReuseUpdatedViewHolder

         boolean canReuseUpdatedViewHolder(@NonNull() RecyclerView.ViewHolder viewHolder)

        When an item is changed, ItemAnimator can decide whether it wants to re-usethe same ViewHolder for animations or RecyclerView should create a copy of theitem 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 sametype ( Adapter#getItemViewType(int)). Otherwise, ItemAnimator will always receiveboth 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.

      • animateDisappearance

         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 hasbeen removed by the LayoutManager. It might have been removed from the adapter or simplybecome invisible due to other factors. You can distinguish these two cases by checkingthe change flags that were passed to recordPreLayoutInformation.

        Note that when a ViewHolder both changes and disappears in the same layout pass, theanimation callback method which will be called by the RecyclerView depends on theItemAnimator's decision whether to re-use the same ViewHolder or not, and also theLayoutManager's decision whether to layout the changed version of a disappearingViewHolder or not. RecyclerView will call animateChange instead of {@code animateDisappearance} if and only if the ItemAnimatorreturns {@code false} from canReuseUpdatedViewHolder and theLayoutManager 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 disappearlocation for the View by laying it out in that location. When that happens,RecyclerView will call recordPostLayoutInformation and theresponse of that call will be passed to this method as the postLayoutInfo.

        ItemAnimator must call dispatchAnimationFinished when the animationis complete (or instantly call dispatchAnimationFinished if itdecides not to animate the view).

        Parameters:
        viewHolder - The ViewHolder which should be animated
        preLayoutInfo - The information that was returned fromrecordPreLayoutInformation.
        postLayoutInfo - The information that was returned fromrecordPostLayoutInformation.

      • animateChange

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

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

        If this method is called due to a notifyDataSetChanged call, there isa good possibility that item contents didn't really change but it is rebound from theadapter. DefaultItemAnimator will skip animating the View if its location on thescreen didn't change and your animator should handle this case as well and avoid creatingunnecessary animations.

        When an item is updated, ItemAnimator has a chance to ask RecyclerView to keep theprevious presentation of the item as-is and supply a new ViewHolder for the updatedpresentation (see: canReuseUpdatedViewHolder.This is useful if you don't know the contents of the Item and would liketo 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 performantand 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 forthis ViewHolder when canReuseUpdatedViewHolder was called, theoldHolder and newHolder will be different ViewHolder instanceswhich represent the same Item. In that case, only the new ViewHolder is visibleto the LayoutManager but RecyclerView keeps old ViewHolder attached for animations.

        ItemAnimator must call dispatchAnimationFinished for each distinctViewHolder when their animation is complete(or instantly call dispatchAnimationFinished if it decides not toanimate 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, theanimation callback method which will be called by the RecyclerView depends on theItemAnimator's decision whether to re-use the same ViewHolder or not, and also theLayoutManager's decision whether to layout the changed version of a disappearingViewHolder or not. RecyclerView will call {@code animateChange} instead of animateDisappearance if and only if the ItemAnimator returns {@code false} from canReuseUpdatedViewHolder and theLayoutManager 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 - The ViewHolder before the layout is started, might be the sameinstance with newHolder.
        newHolder - The ViewHolder after the layout is finished, might be the sameinstance with oldHolder.

      • animateRemove

         abstract boolean animateRemove(RecyclerView.ViewHolder holder)

        Called when an item is removed from the RecyclerView. Implementors can choosewhether and how to animate that change, but must always call dispatchRemoveFinished when done, eitherimmediately (if no animation will occur) or after the animation actually finishes.The return value indicates whether an animation has been set up and whether theItemAnimator's runPendingAnimations method should be called at thenext opportunity. This mechanism allows ItemAnimator to set up individual animationsas 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 theRecyclerView, but for which the system does not have enough information to animatethem out of view. In that case, the default animation for removing items is runon those items as well.

        Parameters:
        holder - The item that is being removed.

      • animateAdd

         abstract boolean animateAdd(RecyclerView.ViewHolder holder)

        Called when an item is added to the RecyclerView. Implementors can choosewhether and how to animate that change, but must always call dispatchAddFinished when done, eitherimmediately (if no animation will occur) or after the animation actually finishes.The return value indicates whether an animation has been set up and whether theItemAnimator's runPendingAnimations method should be called at thenext opportunity. This mechanism allows ItemAnimator to set up individual animationsas 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 theRecyclerView, but for which the system does not have enough information to animatethem into view. In that case, the default animation for adding items is runon those items as well.

        Parameters:
        holder - The item that is being added.

      • animateMove

         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 choosewhether and how to animate that change, but must always call dispatchMoveFinished when done, eitherimmediately (if no animation will occur) or after the animation actually finishes.The return value indicates whether an animation has been set up and whether theItemAnimator's runPendingAnimations method should be called at thenext opportunity. This mechanism allows ItemAnimator to set up individual animationsas 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:
        holder - The item that is being moved.

      • animateChange

         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 {@code oldHolder} is the same ViewHolder as the {@code newHolder}, you must call dispatchChangeFinished once and only once. In that case, thesecond parameter of {@code dispatchChangeFinished} is ignored.

        The return value indicates whether an animation has been set up and whether theItemAnimator's runPendingAnimations method should be called at thenext opportunity. This mechanism allows ItemAnimator to set up individual animationsas 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:
        oldHolder - The original item that changed.
        newHolder - The new item that was created with the changed content.
        fromLeft - Left of the old view holder
        fromTop - Top of the old view holder
        toLeft - Left of the new view holder
        toTop - Top of the new view holder

      • dispatchChangeFinished

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

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

        Parameters:
        item - The item which has been changed (this method must be called foreach non-null ViewHolder passed intoanimateChange).
        oldItem - true if this is the old item that was changed, false ifit is the new item that replaced the old item.

      • dispatchChangeStarting

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

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

        Parameters:
        item - The item which has been changed (this method must be called foreach non-null ViewHolder passed intoanimateChange).
        oldItem - true if this is the old item that was changed, false ifit is the new item that replaced the old item.

      • onRemoveStarting

         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 overridethis method to handle any ViewHolder-specific operations linked to animationlifecycles.

        Parameters:
        item - The ViewHolder being animated.

      • onRemoveFinished

         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 overridethis method to handle any ViewHolder-specific operations linked to animationlifecycles.

        Parameters:
        item - The ViewHolder being animated.

      • onAddStarting

         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 overridethis method to handle any ViewHolder-specific operations linked to animationlifecycles.

        Parameters:
        item - The ViewHolder being animated.

      • onAddFinished

         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 overridethis method to handle any ViewHolder-specific operations linked to animationlifecycles.

        Parameters:
        item - The ViewHolder being animated.

      • onMoveStarting

         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 overridethis method to handle any ViewHolder-specific operations linked to animationlifecycles.

        Parameters:
        item - The ViewHolder being animated.

      • onMoveFinished

         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 overridethis method to handle any ViewHolder-specific operations linked to animationlifecycles.

        Parameters:
        item - The ViewHolder being animated.

      • onChangeStarting

         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 overridethis method to handle any ViewHolder-specific operations linked to animationlifecycles.

        Parameters:
        item - The ViewHolder being animated.
        oldItem - true if this is the old item that was changed, false ifit is the new item that replaced the old item.

      • onChangeFinished

         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 overridethis method to handle any ViewHolder-specific operations linked to animationlifecycles.

        Parameters:
        item - The ViewHolder being animated.
        oldItem - true if this is the old item that was changed, false ifit is the new item that replaced the old item.