public class ItemTouchHelper extends RecyclerView.ItemDecoration implements RecyclerView.OnChildAttachStateChangeListener
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. On
platforms older than Honeycomb, ItemTouchHelper uses canvas translations and View's visibility
property to move items in response to touch events. 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)
.
onChildDraw
but due to limitations of
platform prior to Honeycomb, you may need to implement onChildDrawOver
as well.Modifier and Type | Class and Description |
---|---|
static class |
ItemTouchHelper.Callback
This class is the contract between ItemTouchHelper and your application.
|
static class |
ItemTouchHelper.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.
|
static interface |
ItemTouchHelper.ViewDropHandler
An interface which can be implemented by LayoutManager for better integration with
ItemTouchHelper . |
Modifier and Type | Field and Description |
---|---|
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.
|
Constructor and Description |
---|
ItemTouchHelper(ItemTouchHelper.Callback callback)
Creates an ItemTouchHelper that will work with the given Callback.
|
Modifier and Type | Method and Description |
---|---|
void |
attachToRecyclerView(RecyclerView recyclerView)
Attaches the ItemTouchHelper to the provided RecyclerView.
|
void |
getItemOffsets(Rect outRect,
View view,
RecyclerView parent,
RecyclerView.State state)
Retrieve any offsets for the given item.
|
void |
onChildViewAttachedToWindow(View view)
Called when a view is attached to the RecyclerView.
|
void |
onChildViewDetachedFromWindow(View view)
Called when a view is detached from RecyclerView.
|
void |
onDraw(Canvas c,
RecyclerView parent,
RecyclerView.State state)
Draw any appropriate decorations into the Canvas supplied to the RecyclerView.
|
void |
onDrawOver(Canvas c,
RecyclerView parent,
RecyclerView.State state)
Draw any appropriate decorations into the Canvas supplied to the RecyclerView.
|
void |
startDrag(RecyclerView.ViewHolder viewHolder)
Starts dragging the provided ViewHolder.
|
void |
startSwipe(RecyclerView.ViewHolder viewHolder)
Starts swiping the provided ViewHolder.
|
getItemOffsets, onDraw, onDrawOver
public static final int UP
public static final int DOWN
public static final int LEFT
public static final int RIGHT
public static final int START
public static final int END
public static final int ACTION_STATE_IDLE
public static final int ACTION_STATE_SWIPE
public static final int ACTION_STATE_DRAG
public static final int ANIMATION_TYPE_SWIPE_SUCCESS
public static final int ANIMATION_TYPE_SWIPE_CANCEL
public static final int ANIMATION_TYPE_DRAG
public ItemTouchHelper(ItemTouchHelper.Callback 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.
callback
- The Callback which controls the behavior of this touch helper.public void attachToRecyclerView(@Nullable RecyclerView recyclerView)
null
to detach it from the current 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.public void onDrawOver(Canvas c, RecyclerView parent, RecyclerView.State state)
RecyclerView.ItemDecoration
onDrawOver
in class RecyclerView.ItemDecoration
c
- Canvas to draw intoparent
- RecyclerView this ItemDecoration is drawing intostate
- The current state of RecyclerView.public void onDraw(Canvas c, RecyclerView parent, RecyclerView.State state)
RecyclerView.ItemDecoration
onDraw
in class RecyclerView.ItemDecoration
c
- Canvas to draw intoparent
- RecyclerView this ItemDecoration is drawing intostate
- The current state of RecyclerViewpublic void onChildViewAttachedToWindow(View view)
RecyclerView.OnChildAttachStateChangeListener
onChildViewAttachedToWindow
in interface RecyclerView.OnChildAttachStateChangeListener
view
- The View which is attached to the RecyclerViewpublic void onChildViewDetachedFromWindow(View view)
RecyclerView.OnChildAttachStateChangeListener
onChildViewDetachedFromWindow
in interface RecyclerView.OnChildAttachStateChangeListener
view
- The View which is being detached from the RecyclerViewpublic void getItemOffsets(Rect outRect, View view, RecyclerView parent, RecyclerView.State state)
RecyclerView.ItemDecoration
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
RecyclerView.getChildAdapterPosition(View)
to get the adapter position of the
View.
getItemOffsets
in class RecyclerView.ItemDecoration
outRect
- Rect to receive the output.view
- The child view to decorateparent
- RecyclerView this ItemDecoration is decoratingstate
- The current state of RecyclerView.public void startDrag(RecyclerView.ViewHolder viewHolder)
ItemTouchHelper.Callback.isLongPressDragEnabled()
.
For this method to work:
ItemTouchHelper.Callback
must have dragging enabled.viewHolder.dragButton.setOnTouchListener(new View.OnTouchListener() { public boolean onTouch(View v, MotionEvent event) { if (MotionEventCompat.getActionMasked(event) == MotionEvent.ACTION_DOWN) { mItemTouchHelper.startDrag(viewHolder); } return false; } });
viewHolder
- The ViewHolder to start dragging. It must be a direct child of
RecyclerView.ItemTouchHelper.Callback.isItemViewSwipeEnabled()
public void startSwipe(RecyclerView.ViewHolder viewHolder)
ItemTouchHelper.Callback
For this method to work:
ItemTouchHelper.Callback
must have swiping enabled.viewHolder.dragButton.setOnTouchListener(new View.OnTouchListener() { public boolean onTouch(View v, MotionEvent event) { if (MotionEventCompat.getActionMasked(event) == MotionEvent.ACTION_DOWN) { mItemTouchHelper.startSwipe(viewHolder); } return false; } });
viewHolder
- The ViewHolder to start swiping. It must be a direct child of
RecyclerView.