Promotion

Unmaintained

I'm unable to maintain this library due to lack of time. If anyone interested, feel free to folk it.

SwipeableRV

SwipeableRV is a library that provides a fast and convenient way to implement the 'swipe to dismiss' feature in Recycler View, as seen in apps such as Messenger.

SwipeableRV wraps around ItemTouchHelper from the Android Support Library. Therefore, developers do not need to do any extra work on ItemTouchHelper.Callback themselve. Instead they can just focus on creating a recycler view, adapter, and view holder as normal, plus some minimal work on specifying some details such as supported swipe directions, deletion message or icon.

Below is how SwipeableRV looks.

Usage

SwipeableRV is made with the goal of making things as simple as possible. To implement the RecyclerView shown above, the following steps are needed.

All the above attributes are optional. If you don't specify them, then the default values (defined within the library) are used.

The above example is for the case in which you need to specify different types of action and effects for different swipe direction (left-to-right and right-to-left). If that is not required (no difference between the swipe directions), then the settings would be simpler:

It can be seen that all ltr_xyz and rtl_xyz attributes are now replaced with a single xyz attribute since in SwipeableRV the value of a xyz attribute can override the values of ltr_xyz and rtl_xyz. That also means whenever a xyz attribute is defined, never define any ltr_xyz and/or rtl_xyz attribute in the same recycler view.

Notes:

These attributes can also be set programmatically through an instance of the SwipeableRV class.

By default, the has_border attribute has the value of true. Setting it false would remove the top and bottom borders (shown in the above screen).

Java Code

Adapter

Your adapter has to implements the SWAdapter interface. For your convenience, SwipeableRV provides 2 abstract classes that implement the interface so you can subclass one of them.

####Subclass StandardSWAdapterStandardSWAdapter provides an implementation in which it has a reference to your list of items and directly manipulate (add/remove) the items. With this option, all what you need to do is specifying the type of the items being displayed within the SWRecyclerView (i.e., String in this example) and define a constructor which takes a list of items as follows.

####Subclass DelegateSWAdapterDelegateSWAdapter provides you with more flexibility that you don't need to pass the item list into your adapter. This is designed for cases in which your architecture requires the item list to be manipulated by only a certain class. With this option, you need to provide your own implementation of the DWItemDelegate interface and pass it into the adapter's constructor. Example as follows:

Your DWItemDelegate should define how the item list is added or removed. ####Provide your own implementation of SWAdapter interface In case the pre-implemented adapters do not meet your need, you can consider implementing your own SWAdapter.

###Recycler View Setup Set up SWRecyclerView just the same way as you do for a normal RecyclerView, except that you have to include this line:

This is a key method that sets up the swipe-to-dismiss feature on the recycler view behind the scene. The swipe_directions parameter specifies which directions your items can be swiped (to delete). For example, ItemTouchHelper.LEFT|ItemTouchHelper.RIGHT indicates that they can be swiped in both directions (left-to-right as well as right-to-left).

That's it! Now you've got a recycler view with swipe-to-dismiss feature. How simple and quick that is?

List of SwipableRV's attributes

SwipableRV make it possible for your to quickly customise most of the text and color related to the swipe actions. Please refer to the following table for a complete list of attributes supported by SwipableRV and get the idea of what it can do.

Note: whenever there is 3 version of an attribute, for example swipe_icon, ltr_swipe_icon and rtl_swipe_icon, the value of the first one always override the other two. Therefore, if there is no difference between the settings for left-to-right and right-to-left swipes, you should only specify the general version of the attribute (i.e., swipe_icon).

Attributes

Purpose

Data type

Default

has_border

Set if the top and bottom line should be drawn around the item being swiped. If this value is set to false, the next 2 attributes (about border) would be ignored. This is normally set to false if you already has a separator between items in your recycler view.

boolean

true

border_color

Set separator line color

color

#cccccc

border_width

Set separator line width

dimension

1dp

swipe_iconltr_swipe_iconrtl_swipe_icon

Set the icon to be displayed when an item is being swiped

drawable

a Bin icon

swipe_backgroundltr_swipe_backgroundrtl_swipe_background

Set the color of the background to be displayed when an item is being swiped

color

#bbbbbb

swipe_icon_height

Set the height of the swipe icon

dimension

24dp

swipe_icon_width

Set the width of the swipe icon

dimension

24dp

swipe_icon_colorltr_swipe_icon_colorrtl_swipe_icon_color

Set the color of the swipe icon. This attribute is used whenever you must use an icon that is shared with other part of the app and you want it to have a different color.

color

no color

swipe_icon_marginltr_swipe_icon_marginrtl_swipe_icon_margin

Set the margin of the swipe icon (the gap between the swipe icon and the corresponding edge of the item view in which it is displayed in)

dimension

24dp

swipe_messageltr_swipe_messagertl_swipe_message

Set the message being displayed next to the swipe icon when an item is being swiped. This is usually for describing what action is to be carried out after an item is swiped in a certain direction

string

Null

swipe_message_colorltr_swipe_message_colorrtl_swipe_message_color

Set the swipe message's color

color

#000

swipe_message_font_path

Set the path to the font being used to display the swipe message. If this is not set, the message is displayed with the system's default font.

string

Null

swipe_message_bold

used only when the default font is used. Setting this attribute to true means that the message would be displayed in bold style

More Settings

Above I've shown how to use SwipeableRV in the simple case in which the same snack bar message is displayed for all item swiped in the same direction, and no additional processing is made whenever an item is removed or added back (by clicking on the undo action button). In this section, I'll show you some additional features of SwipeableRV .

Specify different snack bar messages for different items

You can override the getSnackBarMessage(ViewHolder viewHolder, int direction) function in the your implementation of the SWAdapter interface. In the default implementation, the snackbar_message (see the list of attributes above) specified in SWRecyclerView is returned.

Specify different swipe directions for different items

You can override the getUndoActionText(ViewHolder viewHolder, int direction) function in your SWAdapter class. By default, this function returns -1, which means the swipe directions for this item is identical to the swipe directions that was set via SWRecyclerView's setupSwipeToDismiss(SWAdapter, SnackbarDataProvider, int) method.

Specify additional actions when an item is removed from or added back to a Recycler View

You can create a class that implements the SWItemRemovalListener interface and assign this listener to an instance of SWAdapter. Within this interface, the following 3 methods should be implemented:

onItemTemporarilyRemoved(T item, int position): this method is called when an item is swiped to dismiss from a SWRecyclerView and a Snackbar is shown (if the allow_undo attribute is not set to false).

onItemPermanentlyRemoved(T item): this method is called when the "undoable" period has ellapsed and item can't be added back to the list anymore. This is a suitable place for permanently removing the item from database for instance

onItemAddedBack(T item, int position): this method is called when an item is added back to a SWRecyclerView after the undo button on a Snackbar is tapped.

##Programmatically build swipe message From the above example and attribute list, we know that the swipe message(s) can be set via XML layout. In case you need to programmatically build the swipe messages, take the following as an example. You can have a look in SwipeMessageBuilder for more attributes and functions.

mRecyclerView.getSwipeMessageBuilder()
.withMessage(getString(R.string.new_message))
.withFontPath(getString(R.string.droidSerif))
// build both messages with the same settings
// use SwipeMessageBuilder.LTR or SwipeMessageBuilder.RTL
// if you want to build a message for only one
// swipe direction
.withSwipeDirection(SwipeMessageBuilder.BOTH)
.build();

Download

SwipeableRV has been uploaded to JCenter. You can download it by adding the following dependency into your project.

compile 'io.huannguyen.swipeablerv:swipeable-rv:1.0.2'

Sample Project

You can access a sample project using SwipeableRV from the demo module in this repo.

Contributions & Questions

Any contribution is welcome. If you find a bug, please feel free to create an issue. If you have any suggestion/recommendation of new features or anything, shoot me an email at huan.nguyentuong@gmail.com or send me a pull request.