carbon.recycler

Class ItemTouchHelper

java.lang.Object

android.support.v7.widget.RecyclerView.ItemDecoration

carbon.recycler.ItemTouchHelper

All Implemented Interfaces:

android.support.v7.widget.RecyclerView.OnChildAttachStateChangeListener

public class ItemTouchHelper
extends android.support.v7.widget.RecyclerView.ItemDecoration
implements android.support.v7.widget.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 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).

Most of the time, you only need to override onChildDraw but due to limitations of platform prior to Honeycomb, you may need to implement onChildDrawOver as well.

Nested Class Summary

Nested Classes

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.

Field Summary

Fields

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 Summary

Constructors

Constructor and Description
ItemTouchHelper(ItemTouchHelper.Callback callback) Creates an ItemTouchHelper that will work with the given Callback.

Method Summary

Modifier and Type	Method and Description
void	attachToRecyclerView(android.support.v7.widget.RecyclerView recyclerView) Attaches the ItemTouchHelper to the provided RecyclerView.
void	getItemOffsets(android.graphics.Rect outRect, android.view.View view, android.support.v7.widget.RecyclerView parent, android.support.v7.widget.RecyclerView.State state)
void	onChildViewAttachedToWindow(android.view.View view)
void	onChildViewDetachedFromWindow(android.view.View view)
void	onDraw(android.graphics.Canvas c, android.support.v7.widget.RecyclerView parent, android.support.v7.widget.RecyclerView.State state)
void	onDrawOver(android.graphics.Canvas c, android.support.v7.widget.RecyclerView parent, android.support.v7.widget.RecyclerView.State state)
void	startDrag(android.support.v7.widget.RecyclerView.ViewHolder viewHolder) Starts dragging the provided RowViewHolder.
void	startSwipe(android.support.v7.widget.RecyclerView.ViewHolder viewHolder) Starts swiping the provided RowViewHolder.

Methods inherited from class android.support.v7.widget.RecyclerView.ItemDecoration

getItemOffsets, onDraw, onDrawOver

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

UP

public static final int UP

Up direction, used for swipe & drag control.

See Also:

Constant Field Values

DOWN

public static final int DOWN

Down direction, used for swipe & drag control.

See Also:

Constant Field Values

LEFT

public static final int LEFT

Left direction, used for swipe & drag control.

See Also:

Constant Field Values

RIGHT

public static final int RIGHT

Right direction, used for swipe & drag control.

See Also:

Constant Field Values

START

public static final int START

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

See Also:

Constant Field Values

END

public static final int END

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

See Also:

Constant Field Values

ACTION_STATE_IDLE

public static final int ACTION_STATE_IDLE

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.

See Also:

Constant Field Values

ACTION_STATE_SWIPE

public static final int ACTION_STATE_SWIPE

A View is currently being swiped.

See Also:

Constant Field Values

ACTION_STATE_DRAG

public static final int ACTION_STATE_DRAG

A View is currently being dragged.

See Also:

Constant Field Values

ANIMATION_TYPE_SWIPE_SUCCESS

public static final int ANIMATION_TYPE_SWIPE_SUCCESS

Animation type for views which are swiped successfully.

See Also:

Constant Field Values

ANIMATION_TYPE_SWIPE_CANCEL

public static final int ANIMATION_TYPE_SWIPE_CANCEL

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

See Also:

Constant Field Values

ANIMATION_TYPE_DRAG

public static final int ANIMATION_TYPE_DRAG

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

See Also:

Constant Field Values

Constructor Detail

ItemTouchHelper

public ItemTouchHelper(ItemTouchHelper.Callback 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 - The Callback which controls the behavior of this touch helper.

Method Detail

attachToRecyclerView

public void attachToRecyclerView(@Nullable
                                 android.support.v7.widget.RecyclerView recyclerView)

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 - The RecyclerView instance to which you want to add this helper or null if you want to remove ItemTouchHelper from the current RecyclerView.

onDrawOver

public void onDrawOver(android.graphics.Canvas c,
                       android.support.v7.widget.RecyclerView parent,
                       android.support.v7.widget.RecyclerView.State state)

Overrides:

onDrawOver in class android.support.v7.widget.RecyclerView.ItemDecoration

onDraw

public void onDraw(android.graphics.Canvas c,
                   android.support.v7.widget.RecyclerView parent,
                   android.support.v7.widget.RecyclerView.State state)

Overrides:

onDraw in class android.support.v7.widget.RecyclerView.ItemDecoration

onChildViewAttachedToWindow

public void onChildViewAttachedToWindow(android.view.View view)

Specified by:

onChildViewAttachedToWindow in interface android.support.v7.widget.RecyclerView.OnChildAttachStateChangeListener

onChildViewDetachedFromWindow

public void onChildViewDetachedFromWindow(android.view.View view)

Specified by:

onChildViewDetachedFromWindow in interface android.support.v7.widget.RecyclerView.OnChildAttachStateChangeListener

getItemOffsets

public void getItemOffsets(android.graphics.Rect outRect,
                           android.view.View view,
                           android.support.v7.widget.RecyclerView parent,
                           android.support.v7.widget.RecyclerView.State state)

Overrides:

getItemOffsets in class android.support.v7.widget.RecyclerView.ItemDecoration

startDrag

public void startDrag(android.support.v7.widget.RecyclerView.ViewHolder viewHolder)

Starts dragging the provided RowViewHolder. 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 RowViewHolder 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 (MotionEventCompat.getActionMasked(event) == MotionEvent.ACTION_DOWN) {
                 mItemTouchHelper.startDrag(viewHolder);
             }
             return false;
         }
     });
 

Parameters:

viewHolder - The RowViewHolder to start dragging. It must be a direct child of RecyclerView.

See Also:

ItemTouchHelper.Callback.isItemViewSwipeEnabled()

startSwipe

public void startSwipe(android.support.v7.widget.RecyclerView.ViewHolder viewHolder)

Starts swiping the provided RowViewHolder. 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 RowViewHolder 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 (MotionEventCompat.getActionMasked(event) == MotionEvent.ACTION_DOWN) {
                 mItemTouchHelper.startSwipe(viewHolder);
             }
             return false;
         }
     });
 

Parameters:

viewHolder - The RowViewHolder to start swiping. It must be a direct child of RecyclerView.