ItemTouchHelper

Kotlin |Java

open class ItemTouchHelper : RecyclerView.ItemDecoration, RecyclerView.OnChildAttachStateChangeListener

kotlin.Any
↳	androidx.recyclerview.widget.RecyclerView.ItemDecoration
	↳	androidx.recyclerview.widget.ItemTouchHelper

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 Callback#onMove(RecyclerView, ViewHolder, ViewHolder) and / or Callback#onSwiped(ViewHolder, int).

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 ItemTouchHelper.Callback class or implementing ItemTouchHelper.ViewDropHandler interface in your LayoutManager.

By default, ItemTouchHelper moves the items' translateX/Y properties to reposition them. You can customize these behaviors by overriding Callback#onChildDraw(Canvas, RecyclerView, * ViewHolder, float, float, int, boolean) or Callback#onChildDrawOver(Canvas, RecyclerView, ViewHolder, float, float, int, * boolean).

Most of the time you only need to override onChildDraw.

Summary

Nested classes
abstract	Callback This class is the contract between ItemTouchHelper and your application.
abstract	SimpleCallback A simple wrapper to the default Callback which you can construct with drag and swipe directions and this class will handle the flag callbacks.
abstract	ViewDropHandler An interface which can be implemented by LayoutManager for better integration with ItemTouchHelper.

Constants
static Int	ACTION_STATE_DRAG A View is currently being dragged.
static Int	ACTION_STATE_IDLE ItemTouchHelper is in idle state.
static Int	ACTION_STATE_SWIPE A View is currently being swiped.
static Int	ANIMATION_TYPE_DRAG Animation type for views that were dragged and now will animate to their final position.
static Int	ANIMATION_TYPE_SWIPE_CANCEL Animation type for views which are not completely swiped thus will animate back to their original position.
static Int	ANIMATION_TYPE_SWIPE_SUCCESS Animation type for views which are swiped successfully.
static Int	DOWN Down direction, used for swipe & drag control.
static Int	END Horizontal end direction.
static Int	LEFT Left direction, used for swipe & drag control.
static Int	RIGHT Right direction, used for swipe & drag control.
static Int	START Horizontal start direction.
static Int	UP Up direction, used for swipe & drag control.

Public constructors
<init>(@NonNull callback: ItemTouchHelper.Callback) Creates an ItemTouchHelper that will work with the given Callback.

Public methods
open Unit	attachToRecyclerView(@Nullable recyclerView: RecyclerView?) Attaches the ItemTouchHelper to the provided RecyclerView.
open Unit	getItemOffsets(outRect: Rect, view: View, parent: RecyclerView, state: RecyclerView.State)
open Unit	onChildViewAttachedToWindow(@NonNull view: View)
open Unit	onChildViewDetachedFromWindow(@NonNull view: View)
open Unit	onDraw(c: Canvas, parent: RecyclerView, state: RecyclerView.State)
open Unit	onDrawOver(c: Canvas, parent: RecyclerView, state: RecyclerView.State)
open Unit	startDrag(@NonNull viewHolder: RecyclerView.ViewHolder) Starts dragging the provided ViewHolder.
open Unit	startSwipe(@NonNull viewHolder: RecyclerView.ViewHolder) Starts swiping the provided ViewHolder.

Inherited functions
From class ItemDecoration Unit getItemOffsets(@NonNull outRect: Rect, itemPosition: Int, @NonNull parent: RecyclerView) Unit onDraw(@NonNull c: Canvas, @NonNull parent: RecyclerView) Unit onDrawOver(@NonNull c: Canvas, @NonNull parent: RecyclerView)

Constants

ACTION_STATE_DRAG

static val ACTION_STATE_DRAG: Int

A View is currently being dragged.

Value: 2

ACTION_STATE_IDLE

static val ACTION_STATE_IDLE: Int

ItemTouchHelper is in idle state. At this state, either there is no related motion event by the user or latest motion events have not yet triggered a swipe or drag.

Value: 0

ACTION_STATE_SWIPE

static val ACTION_STATE_SWIPE: Int

A View is currently being swiped.

Value: 1

ANIMATION_TYPE_DRAG

static val ANIMATION_TYPE_DRAG: Int

Animation type for views that were dragged and now will animate to their final position.

Value: 1 << 3

ANIMATION_TYPE_SWIPE_CANCEL

static val ANIMATION_TYPE_SWIPE_CANCEL: Int

Animation type for views which are not completely swiped thus will animate back to their original position.

Value: 1 << 2

ANIMATION_TYPE_SWIPE_SUCCESS

static val ANIMATION_TYPE_SWIPE_SUCCESS: Int

Animation type for views which are swiped successfully.

Value: 1 << 1

DOWN

static val DOWN: Int

Down direction, used for swipe & drag control.

Value: 1 << 1

END

static val END: Int

Horizontal end direction. Resolved to LEFT or RIGHT depending on RecyclerView's layout direction. Used for swipe & drag control.

Value: RIGHT << 2

LEFT

static val LEFT: Int

Left direction, used for swipe & drag control.

Value: 1 << 2

RIGHT

static val RIGHT: Int

Right direction, used for swipe & drag control.

Value: 1 << 3

START

static val START: Int

Horizontal start direction. Resolved to LEFT or RIGHT depending on RecyclerView's layout direction. Used for swipe & drag control.

Value: LEFT << 2

UP

static val UP: Int

Up direction, used for swipe & drag control.

Value: 1

Public constructors

<init>

ItemTouchHelper(@NonNull callback: ItemTouchHelper.Callback)

Creates an ItemTouchHelper that will work with the given Callback.

You can attach ItemTouchHelper to a RecyclerView via attachToRecyclerView(RecyclerView). Upon attaching, it will add an item decoration, an onItemTouchListener and a Child attach / detach listener to the RecyclerView.

Parameters
callback	ItemTouchHelper.Callback: The Callback which controls the behavior of this touch helper.

Public methods

attachToRecyclerView

open fun attachToRecyclerView(@Nullable recyclerView: RecyclerView?): Unit

Attaches the ItemTouchHelper to the provided RecyclerView. If TouchHelper is already attached to a RecyclerView, it will first detach from the previous one. You can call this method with null to detach it from the current RecyclerView.

Parameters
recyclerView	RecyclerView?: The RecyclerView instance to which you want to add this helper or null if you want to remove ItemTouchHelper from the current RecyclerView.

getItemOffsets

open fun getItemOffsets(outRect: Rect, view: View, parent: RecyclerView, state: RecyclerView.State): Unit

onChildViewAttachedToWindow

open fun onChildViewAttachedToWindow(@NonNull view: View): Unit

onChildViewDetachedFromWindow

open fun onChildViewDetachedFromWindow(@NonNull view: View): Unit

onDraw

open fun onDraw(c: Canvas, parent: RecyclerView, state: RecyclerView.State): Unit

onDrawOver

open fun onDrawOver(c: Canvas, parent: RecyclerView, state: RecyclerView.State): Unit

startDrag

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

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

For this method to work:

• The provided ViewHolder must be a child of the RecyclerView to which this ItemTouchHelper is attached.
• ItemTouchHelper.Callback must have dragging enabled.
• There must be a previous touch event that was reported to the ItemTouchHelper through RecyclerView's ItemTouchListener mechanism. As long as no other ItemTouchListener grabs 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 one of 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	RecyclerView.ViewHolder: The ViewHolder to start dragging. It must be a direct child of RecyclerView.

See Also

• ItemTouchHelper.Callback#isItemViewSwipeEnabled()

startSwipe

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

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

For this method to work:

• The provided ViewHolder must be a child of the RecyclerView to which this ItemTouchHelper is attached.
• ItemTouchHelper.Callback must have swiping enabled.
• There must be a previous touch event that was reported to the ItemTouchHelper through RecyclerView's ItemTouchListener mechanism. As long as no other ItemTouchListener grabs 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 one of 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	RecyclerView.ViewHolder: The ViewHolder to start swiping. It must be a direct child of RecyclerView.