Package 

Class ItemTouchHelper

  • All Implemented Interfaces:
    tds.androidx.recyclerview.widget.RecyclerView.OnChildAttachStateChangeListener 
    
public class ItemTouchHelper
extends RecyclerView.ItemDecoration implements RecyclerView.OnChildAttachStateChangeListener

    This is a utility class to add swipe to dismiss and drag & drop support to RecyclerView.

    It works with a RecyclerView and a Callback class, which configures what type of interactions are enabled and also receives events when user performs these actions.

    Depending on which functionality you support, you should override onMove and / or onSwiped.

    This class is designed to work with any LayoutManager but for certain situations, it can be optimized for your custom LayoutManager by extending methods in the Callback class or implementing ViewDropHandler interface in your LayoutManager.

    By default, ItemTouchHelper moves the items' translateX/Y properties to reposition them. You can customize these behaviors by overriding onChildDraw or onChildDrawOver.

    Most of the time you only need to override onChildDraw.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      public interface ItemTouchHelper.ViewDropHandler

      An interface which can be implemented by LayoutManager for better integration with ItemTouchHelper.
      public abstract class ItemTouchHelper.Callback

      This class is the contract between ItemTouchHelper and your application. It lets you controlwhich touch behaviors are enabled per each ViewHolder and also receive callbacks when userperforms these actions.

      To control which actions user can take on each view, you should override getMovementFlags and return appropriate setof direction flags. (LEFT, RIGHT, START, END, UP, DOWN). You can use makeMovementFlags to easily construct it. Alternatively, you can use SimpleCallback.

      If user drags an item, ItemTouchHelper will call onMove(recyclerView, dragged, target).Upon receiving this callback, you should move the item from the old position({@code dragged.getAdapterPosition()}) to new position ({@code target.getAdapterPosition()})in your adapter and also call notifyItemMoved.To control where a View can be dropped, you can override canDropOver. When adragging View overlaps multiple other views, Callback chooses the closest View with whichdragged View might have changed positions. Although this approach works for many use cases,if you have a custom LayoutManager, you can override chooseDropTarget to select acustom drop target.

      When a View is swiped, ItemTouchHelper animates it until it goes out of bounds, then calls onSwiped. At this point, you should update youradapter (e.g. remove the item) and call related Adapter#notify event.
      public abstract class ItemTouchHelper.SimpleCallback

      A simple wrapper to the default Callback which you can construct with drag and swipedirections and this class will handle the flag callbacks. You should still override onMoveoronSwiped depending on your use case.

      ItemTouchHelper mIth = new ItemTouchHelper(
    new ItemTouchHelper.SimpleCallback(ItemTouchHelper.UP | ItemTouchHelper.DOWN,
        ItemTouchHelper.LEFT) {
        public boolean onMove(RecyclerView recyclerView,
            ViewHolder viewHolder, ViewHolder target) {
            final int fromPos = viewHolder.getAdapterPosition();
            final int toPos = target.getAdapterPosition();
            // move item in `fromPos` to `toPos` in adapter.
            return true;// true if moved, false otherwise
        }
        public void onSwiped(ViewHolder viewHolder, int direction) {
            // remove from adapter
        }
});

    • Constructor Detail

      • ItemTouchHelper

        ItemTouchHelper(ItemTouchHelper.Callback callback)
        Creates an ItemTouchHelper that will work with the given Callback.
        Parameters:
        callback - The Callback which controls the behavior of this touch helper.

    • Method Detail

      • attachToRecyclerView

         void attachToRecyclerView(@Nullable() RecyclerView recyclerView)

        Attaches the ItemTouchHelper to the provided RecyclerView. If TouchHelper is alreadyattached to a RecyclerView, it will first detach from the previous one. You can call thismethod with {@code null} to detach it from the current RecyclerView.

        Parameters:
        recyclerView - The RecyclerView instance to which you want to add this helper or{@code null} if you want to remove ItemTouchHelper from the currentRecyclerView.

      • onDrawOver

         void onDrawOver(Canvas c, RecyclerView parent, RecyclerView.State state)

        Draw any appropriate decorations into the Canvas supplied to the RecyclerView.Any content drawn by this method will be drawn after the item views are drawnand will thus appear over the views.

        Parameters:
        c - Canvas to draw into
        parent - RecyclerView this ItemDecoration is drawing into
        state - The current state of RecyclerView.

      • onDraw

         void onDraw(Canvas c, RecyclerView parent, RecyclerView.State state)

        Draw any appropriate decorations into the Canvas supplied to the RecyclerView.Any content drawn by this method will be drawn before the item views are drawn,and will thus appear underneath the views.

        Parameters:
        c - Canvas to draw into
        parent - RecyclerView this ItemDecoration is drawing into
        state - The current state of RecyclerView

      • onChildViewAttachedToWindow

         void onChildViewAttachedToWindow(@NonNull() View view)

        Called when a view is attached to the RecyclerView.

        Parameters:
        view - The View which is attached to the RecyclerView

      • onChildViewDetachedFromWindow

         void onChildViewDetachedFromWindow(@NonNull() View view)

        Called when a view is detached from RecyclerView.

        Parameters:
        view - The View which is being detached from the RecyclerView

      • getItemOffsets

         void getItemOffsets(Rect outRect, View view, RecyclerView parent, RecyclerView.State state)

        Retrieve any offsets for the given item. Each field of outRect specifiesthe number of pixels that the item view should be inset by, similar to padding or margin.The default implementation sets the bounds of outRect to 0 and returns.

        If this ItemDecoration does not affect the positioning of item views, it should setall four fields of outRect (left, top, right, bottom) to zerobefore returning.

        If you need to access Adapter for additional data, you can call getChildAdapterPosition to get the adapter position of theView.

        Parameters:
        outRect - Rect to receive the output.
        view - The child view to decorate
        parent - RecyclerView this ItemDecoration is decorating
        state - The current state of RecyclerView.

      • startDrag

         void startDrag(@NonNull() RecyclerView.ViewHolder viewHolder)

        Starts dragging the provided ViewHolder. By default, ItemTouchHelper starts a drag when aView is long pressed. You can disable that behavior by overriding isLongPressDragEnabled.

        For this method to work:

        • The provided ViewHolder must be a child of the RecyclerView to which thisItemTouchHelperis attached.
        • Callback must have dragging enabled.
        • There must be a previous touch event that was reported to the ItemTouchHelperthrough RecyclerView's ItemTouchListener mechanism. As long as no other ItemTouchListenergrabs previous events, this should work as expected.
        For example, if you would like to let your user to be able to drag an Item by touching oneof its descendants, you may implement it as follows:
            viewHolder.dragButton.setOnTouchListener(new View.OnTouchListener() {
        public boolean onTouch(View v, MotionEvent event) {
            if (MotionEvent.getActionMasked(event) == MotionEvent.ACTION_DOWN) {
                mItemTouchHelper.startDrag(viewHolder);
            }
            return false;
        }
    });
        Parameters:
        viewHolder - The ViewHolder to start dragging.

      • startSwipe

         void startSwipe(@NonNull() RecyclerView.ViewHolder viewHolder)

        Starts swiping the provided ViewHolder. By default, ItemTouchHelper starts swiping a Viewwhen user swipes their finger (or mouse pointer) over the View. You can disable thisbehaviorby overriding Callback

        For this method to work:

        • The provided ViewHolder must be a child of the RecyclerView to which thisItemTouchHelper is attached.
        • Callback must have swiping enabled.
        • There must be a previous touch event that was reported to the ItemTouchHelperthrough RecyclerView's ItemTouchListener mechanism. As long as no other ItemTouchListenergrabs previous events, this should work as expected.
        For example, if you would like to let your user to be able to swipe an Item by touching oneof its descendants, you may implement it as follows:
            viewHolder.dragButton.setOnTouchListener(new View.OnTouchListener() {
        public boolean onTouch(View v, MotionEvent event) {
            if (MotionEvent.getActionMasked(event) == MotionEvent.ACTION_DOWN) {
                mItemTouchHelper.startSwipe(viewHolder);
            }
            return false;
        }
    });
        Parameters:
        viewHolder - The ViewHolder to start swiping.