ItemTouchHelper
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 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 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 onChildDraw or onChildDrawOver.
onChildDraw.
Summary
Nested types |
|---|
abstract class ItemTouchHelper.CallbackThis class is the contract between ItemTouchHelper and your application. |
abstract class ItemTouchHelper.SimpleCallback : ItemTouchHelper.CallbackA simple wrapper to the default Callback which you can construct with drag and swipe directions and this class will handle the flag callbacks. |
interface ItemTouchHelper.ViewDropHandlerAn interface which can be implemented by LayoutManager for better integration with |
Constants |
|
|---|---|
const Int |
A View is currently being dragged. |
const Int |
ItemTouchHelper is in idle state. |
const Int |
A View is currently being swiped. |
const Int |
Animation type for views that were dragged and now will animate to their final position. |
const Int |
Animation type for views which are not completely swiped thus will animate back to their original position. |
const Int |
Animation type for views which are swiped successfully. |
const Int |
DOWN = 2Down direction, used for swipe &drag control. |
const Int |
END = 32Horizontal end direction. |
const Int |
LEFT = 4Left direction, used for swipe &drag control. |
const Int |
RIGHT = 8Right direction, used for swipe &drag control. |
const Int |
START = 16Horizontal start direction. |
const Int |
UP = 1Up direction, used for swipe &drag control. |
Public constructors |
|---|
ItemTouchHelper(callback: ItemTouchHelper.Callback)Creates an ItemTouchHelper that will work with the given Callback. |
Public functions |
|
|---|---|
Unit |
attachToRecyclerView(recyclerView: RecyclerView?)Attaches the ItemTouchHelper to the provided RecyclerView. |
Unit |
getItemOffsets(Retrieve any offsets for the given item. |
Unit |
onChildViewAttachedToWindow(view: View)Called when a view is attached to the RecyclerView. |
Unit |
Called when a view is detached from RecyclerView. |
Unit |
onDraw(c: Canvas!, parent: RecyclerView!, state: RecyclerView.State!)Draw any appropriate decorations into the Canvas supplied to the RecyclerView. |
Unit |
onDrawOver(c: Canvas, parent: RecyclerView, state: RecyclerView.State)Draw any appropriate decorations into the Canvas supplied to the RecyclerView. |
Unit |
startDrag(viewHolder: RecyclerView.ViewHolder)Starts dragging the provided ViewHolder. |
Unit |
startSwipe(viewHolder: RecyclerView.ViewHolder)Starts swiping the provided ViewHolder. |
Inherited functions |
||||||
|---|---|---|---|---|---|---|
|
Constants
ACTION_STATE_DRAG
const val ACTION_STATE_DRAG = 2: Int
A View is currently being dragged.
ACTION_STATE_IDLE
const val ACTION_STATE_IDLE = 0: 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.
ACTION_STATE_SWIPE
const val ACTION_STATE_SWIPE = 1: Int
A View is currently being swiped.
ANIMATION_TYPE_DRAG
const val ANIMATION_TYPE_DRAG = 8: Int
Animation type for views that were dragged and now will animate to their final position.
ANIMATION_TYPE_SWIPE_CANCEL
const val ANIMATION_TYPE_SWIPE_CANCEL = 4: Int
Animation type for views which are not completely swiped thus will animate back to their original position.
ANIMATION_TYPE_SWIPE_SUCCESS
const val ANIMATION_TYPE_SWIPE_SUCCESS = 2: Int
Animation type for views which are swiped successfully.
END
const val END = 32: Int
Horizontal end direction. Resolved to LEFT or RIGHT depending on RecyclerView's layout direction. Used for swipe &drag control.
Public constructors
ItemTouchHelper
ItemTouchHelper(callback: ItemTouchHelper.Callback)
Creates an ItemTouchHelper that will work with the given Callback.
You can attach ItemTouchHelper to a RecyclerView via attachToRecyclerView. 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 functions
attachToRecyclerView
fun attachToRecyclerView(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 |
getItemOffsets
fun getItemOffsets(
outRect: Rect!,
view: View!,
parent: RecyclerView!,
state: RecyclerView.State!
): Unit
Retrieve any offsets for the given item. Each field of outRect specifies the 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 set all four fields of outRect (left, top, right, bottom) to zero before returning.
If you need to access Adapter for additional data, you can call getChildAdapterPosition to get the adapter position of the View.
| Parameters | |
|---|---|
outRect: Rect! |
Rect to receive the output. |
view: View! |
The child view to decorate |
parent: RecyclerView! |
RecyclerView this ItemDecoration is decorating |
state: RecyclerView.State! |
The current state of RecyclerView. |
onChildViewAttachedToWindow
fun onChildViewAttachedToWindow(view: View): Unit
Called when a view is attached to the RecyclerView.
| Parameters | |
|---|---|
view: View |
The View which is attached to the RecyclerView |
onChildViewDetachedFromWindow
fun onChildViewDetachedFromWindow(view: View): Unit
Called when a view is detached from RecyclerView.
| Parameters | |
|---|---|
view: View |
The View which is being detached from the RecyclerView |
onDraw
fun onDraw(c: Canvas!, parent: RecyclerView!, state: RecyclerView.State!): Unit
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! |
Canvas to draw into |
parent: RecyclerView! |
RecyclerView this ItemDecoration is drawing into |
state: RecyclerView.State! |
The current state of RecyclerView |
onDrawOver
fun onDrawOver(c: Canvas, parent: RecyclerView, state: RecyclerView.State): Unit
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 drawn and will thus appear over the views.
| Parameters | |
|---|---|
c: Canvas |
Canvas to draw into |
parent: RecyclerView |
RecyclerView this ItemDecoration is drawing into |
state: RecyclerView.State |
The current state of RecyclerView. |
startDrag
fun startDrag(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 isLongPressDragEnabled.
For this method to work:
- The provided ViewHolder must be a child of the RecyclerView to which this ItemTouchHelper is attached.
ItemTouchHelper.Callbackmust 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.
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 | |
|---|---|
isItemViewSwipeEnabled |
startSwipe
fun startSwipe(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.Callbackmust 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.
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. |