SwipeableRV

Additional

Language
Java
Version
N/A
Created
Oct 12, 2016
Updated
Aug 16, 2017
Owner
Huan Nguyen (huan-nguyen)
Contributors
Huan Nguyen (huan-nguyen)
worg
marchy
3
Activity
Badge
Generate
Download
Source code
APK file

Advertising

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.

XML Layout

...
xmlns:stdrv="http://schemas.android.com/apk/res-auto"
...
// instead of normal RecyclerView, 
<io.huannguyen.swipeablerv.view.SWRecyclerView
        android:id="@+id/recycler_view"
        android:scrollbars="vertical"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        swrv:border_color="@android:color/darker_gray"
        swrv:ltr_swipe_background="#B71C1C"
        swrv:rtl_swipe_background="#009688"
        swrv:ltr_swipe_message="@string/dismiss"
        swrv:rtl_swipe_message="@string/snooze"
        swrv:swipe_message_text_size="16sp"
        swrv:swipe_message_color="#fff"
        swrv:swipe_message_bold="true"
        swrv:ltr_swipe_icon="@drawable/ic_dismiss"
        swrv:rtl_swipe_icon="@drawable/ic_snooze"
        swrv:swipe_icon_color="#FFFFFF"
        swrv:swipe_icon_height="24dp"
        swrv:swipe_icon_width="24dp"
        swrv:swipe_icon_margin="24dp"
        swrv:ltr_snackbar_message="@string/dismissed"
        swrv:rtl_snackbar_message="@string/snoozed"
        swrv:snackbar_message_color="#fff"
        swrv:ltr_snackbar_background="#B71C1C"
        swrv:rtl_snackbar_background="#009688"
        swrv:undo_action_text_color="#fff"
        swrv:has_border="true"/>

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:

<io.huannguyen.swipeablerv.view.SWRecyclerView
        android:id="@+id/recycler_view"
        android:scrollbars="vertical"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        swrv:border_color="@android:color/darker_gray"
        swrv:swipe_background="#B71C1C"
        swrv:swipe_message="@string/dismiss"
        swrv:swipe_message_text_size="16sp"
        swrv:swipe_message_color="#fff"
        swrv:swipe_message_bold="true"
        swrv:swipe_icon="@drawable/ic_dismiss"
        swrv:swipe_icon_color="#FFFFFF"
        swrv:swipe_icon_height="24dp"
        swrv:swipe_icon_width="24dp"
        swrv:swipe_icon_margin="24dp"
        swrv:snackbar_message="@string/dismissed"
        swrv:snackbar_message_color="#fff"
        swrv:snackbar_background="#B71C1C"
        swrv:undo_action_text_color="#fff"
        swrv:has_border="true"/>

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 StandardSWAdapter StandardSWAdapter 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.

public class SampleAdapter extends StandardSWAdapter<String> {
    public SampleAdapter(List<String> reminderList) {
        this.mItems = reminderList;
    }
}

####Subclass DelegateSWAdapter DelegateSWAdapter 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:

public class SampleAdapter extends DelegateSWAdapter<String> {
    public SampleAdapter(SWItemDelegate<String> delegate) {
        this.mItems = reminderList;
    }
}

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:

mRecyclerView.setupSwipeToDismiss(your_adapter_instance, swipe_directions);

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).

A working example looks something like this:

// Get your recycler view from the XML layout
mRecyclerView = (STDRecyclerView) findViewById(R.id.recycler_view);
LayoutManager layoutManager = new LinearLayoutManager(getApplicationContext());
mRecyclerView.setLayoutManager(layoutManager);
mAdapter = new SampleAdapter(versions);
mRecyclerView.setAdapter(mAdapter);

// allow swiping in both directions (left-to-right and right-to-left)
mRecyclerView.setupSwipeToDelete(mAdapter, ItemTouchHelper.LEFT|ItemTouchHelper.RIGHT);

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 boolean false
swipe_message_text_sizeltr_swipe_message_text_size rtl_swipe_message_text_size
Set the size of the swipe message dimension 14sp
swipe_icon_and_message_gap ltr_swipe_icon_and_message_gap rtl_swipe_icon_and_message_gap Set the gap between the swipe icon and message dimension 10dp
allow_undo Set if undo action (on snack bar) is enabled. If this value is set to false, the snack bar's related attributes below would be ignored boolean true
snackbar_message ltr_snackbar_message rtl_snackbar_message Set the message shown on snack bar after an item is swiped away string Null
snackbar_message_color ltr_snackbar_message_color trl_snackbar_message_color Set the snack bar message's color color No color (System's color would be taken)
snackbar_background ltr_snackbar_background rtl_snackbar_background Set the snack bar's background color color No color (System's color would be taken)
undo_action_text ltr_undo_action_text rtl_undo_action_text Set the action named displayed on the snack bar string "UNDO"
undo_action_text_color ltr_undo_action_text_color rtl_undo_action_text_color Set the color of the undo action text color No color (System's color would be taken)

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.