realm-recyclerview-lite

realm-recyclerview-lite is an implementation of a RecyclerView which supports Realm data.
It is intended to be a slim library which fulfills the functionality requirements I have some of my open source Android apps, such as Minerva; no more, no less. I decided to release it as a library in case others had similar use cases to mine. Take a look at the table of contents for a better idea of what features are offered.

If you just want to know what's new, the changelog is here.

Please be sure to take a moment to look at the Origin section. You'll find a link to Thorben Primke's realm-recyclerview library, which this library is a heavily reworked derivative of.

And yes...at this point is isn't really "lite" anymore 😉.

Table of Contents

• Installation
• Basic Usage
• Swiping
• Drag and Drop
  • Long Click as the Drag Trigger
• Advanced Swiping and Drag and Drop
• Multi-Select
• Fast Scrolling
  • Handle State Notifications
  • Fast Scroller Customization
• Padding

allprojects {
    repositories {
        jcenter()
    }
}

And then add this to your app's build.gradle file:

dependencies {
    compile ('com.bkromhout:realm-recyclerview-lite:{latest version}@aar') {
        transitive = true
    }
}

Please note that at this time, realm-recyclerview-lite has been tested and is verified to work with Realm 2.0.2. Don't be afraid to try a newer version of Realm, just be sure to open an issue if you run into problems.

realm-recyclerview-lite is compatible with Android API Levels >= 11.

<com.bkromhout.rrvl.RealmRecyclerView
        android:id="@+id/recycler"
        android:layout_width="match_parent"
        android:layout_height="match_parent"/>

Next, create an adapter class which extends RealmRecyclerViewAdapter.
Here's a slimmed down version of the sample app's ItemAdapter class:

public class ItemAdapter extends RealmRecyclerViewAdapter<Item, ItemAdapter.ItemVH> {

    public ItemAdapter(Context context, RealmResults<Item> realmResults) {
        super(context, realmResults);
        setHasStableIds(true);
    }

    @Override
    public long getItemId(int position) {
        return realmResults.get(position).uniqueId;
    }

    @Override
    public ItemVH onCreateViewHolder(ViewGroup parent, int viewType) {
        return new ItemVH(inflater.inflate(R.layout.item_card, parent, false));
    }

    @Override
    public void onBindViewHolder(final ItemVH holder, int position) {
        Item item = realmResults.get(position);
        holder.name.setText(item.name);
    }

    class ItemVH extends RecyclerView.ViewHolder {
        @Bind(R.id.content)
        RelativeLayout content;
        @Bind(R.id.drag_handle)
        ImageView dragHandle;
        @Bind(R.id.name)
        TextView name;
        @Bind(R.id.delete_button)
        ImageButton delete;

        public ItemVH(View itemView) {
            super(itemView);
            ButterKnife.bind(this, itemView);
        }
    }
}

Any model class you wish to use display using a RealmRecyclerViewAdapter must implement the UIDModel interface.
Here's a slimmed down version of the sample app's Item class:

public class Item extends RealmObject implements UIDModel {
    public String name;
    @Index
    public long position;
    @PrimaryKey
    public long uniqueId;

    public Item() {
    }

    public Item(String name) {
        this.name = name;
        this.position = nextPos;
        nextPos += GAP;
        this.uniqueId = nextUniqueId.getAndIncrement();
    }

    @Override
    public Object getUID() {
        // Use our uniqueId field as the UID.
        return uniqueId;
    }
}

The UIDModel.getUID method allows a RealmRecyclerViewAdapter to obtain some value unique to each instance of a model class in order to support predictive animations.
If you're planning to return anything more than the value of a primary key field, as is shown here, I recommend that you read the JavaDoc in the UIDModel interface class.

Finally, you only need to call RealmRecyclerView.setAdapter to set your adapter.

A couple more points of note:

• RealmRecyclerView supports LinearLayoutManager only
• RealmRecyclerView is not actually a RecyclerView subclass, it's a FrameLayout. If you need access to the real RecyclerView or LinearLayoutManager instances for some reason, you can use the getRecyclerView and getLayoutManager methods
• When you're done using an adapter (such as when an Activity or Fragment is being destroyed), be sure to call its close method to prevent any possible Realm instance leaks

• In our layout, with the swipe attribute:

<com.bkromhout.rrvl.RealmRecyclerView
        android:id="@+id/recycler"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        app:swipe="true"/>

• Or programmatically, with the RealmRecyclerView.setSwipe method:

recyclerView.setSwipe(true);

Next, we need to override the onSwiped method in our adapter, as well as add a single line to our onBindViewHolder method. These are the relevant parts from the sample app's ItemAdapter class:

@Override
public void onBindViewHolder(final ItemVH holder, int position) {
    Item item = realmResults.get(position);
    holder.name.setText(item.name);
    // We set the unique ID as the tag on a view so that we will be able to get it
    // in the onSwiped() method.
    holder.content.setTag(item.uniqueId);
}

@Override
public void onSwiped(RecyclerView.ViewHolder swiped, int direction) {
    // Get the unique ID of the item.
    long swipedId = (long) ((ItemVH) swiped).content.getTag()

    // Remove the item from Realm.
    try (Realm realm = Realm.getDefaultInstance()) {
        Item item = realm.where(Item.class).equalTo("uniqueId", swipedId).findFirst();
        realm.beginTransaction();
        item.deleteFromRealm();
        realm.commitTransaction();
    }
}

Keep in mind as you read through these steps that my preferred implementation choices may not line up exactly with yours; I've tried to keep this in mind to allow you maximum flexibility.

First, we need to enable drag and drop functionality. This can be done in two ways:

• In our layout, with the dragAndDrop attribute:

<com.bkromhout.rrvl.RealmRecyclerView
        android:id="@+id/recycler"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        app:dragAndDrop="true"/>

• Or programmatically, with the RealmRecyclerView.setDragAndDrop method:

recyclerView.setDragAndDrop(true);

Next, some work needs to be done in our adapter. For drag and drop to work, we need to override the onMove method. We also need to add a bit more to our overridden onBindViewHolder method so that our items' drag handle views actually initiate drags when touched.
These are the relevant parts from the sample app's ItemAdapter class:

@Override
public void onBindViewHolder(final ItemVH holder, int position) {
    Item item = realmResults.get(position);
    holder.name.setText(item.name);
    // We set the unique ID as the tag on a view so that we will be able to get it
    // in the onMove() method.
    holder.content.setTag(item.uniqueId);
    // Grabbing the drag handle should trigger a drag.
    holder.dragHandle.setOnTouchListener(new View.OnTouchListener() {
        @Override
        public boolean onTouch(View v, MotionEvent event) {
            if (MotionEventCompat.getActionMasked(event) == MotionEvent.ACTION_DOWN)
                startDragging(holder);
            return false;
        }
    });
}

@Override
    public boolean onMove(RecyclerView.ViewHolder dragging, RecyclerView.ViewHolder target) {
    // Get positions of items in adapter.
    int draggingPos = dragging.getAdapterPosition();
    int targetPos = target.getAdapterPosition();

    // Get the unique IDs of the items from the tag that we set in onBindViewHolder().
    long draggingId = (long) ((ItemVH) dragging).content.getTag();
    long targetId = (long) ((ItemVH) target).content.getTag();

    // Move the item up or down. The methods in ItemDragHelper will calculate and
    // assign a new position value for the item whose uniqueId == draggingId.
    if (draggingPos > targetPos) ItemDragHelper.moveItemToBefore(draggingId, targetId);
    else ItemDragHelper.moveItemToAfter(draggingId, targetId);

    return true;
}

Note how we've ensured that the onMove method will have access to the value in each Item's uniqueId field by storing that value as the tag of the content view in the view holder.

Please take a moment to look at some of the sample application's classes if you haven't done so yet. Especially relevant here are the Item model class and the ItemDragHelper class.

It's vitally important that you understand at least the concept of how the methods in ItemDragHelper work because you will need to implement something similar. If you're lucky then you may be able to adapt mine for your use. I won't detail it here, but if you want to read a bit more about my ordering scheme, you can read this.

You'll notice that we must handle two cases in the onMove method:

1. An item has been moved up
2. An item has been moved down

You should also notice that nowhere in this code, be it the onMove method above or the methods in ItemDragHelper, do we call any of the notify*Changed methods. This is intended, because RealmRecyclerViewAdapter handles making the correct calls for you when it detects the changes you've made to your data (it relies on a RealmChangeListener to get these notifications, and if you wish to see how it decides which of the notify*Changed methods to call, take a look at the RealmRecyclerViewAdapter class).

While that's great, we also have the option automatically initiating a drag when an item is long clicked; and for some use cases that's really all we need.
To enable this functionality, we can either:

• Add the longClickTriggersDrag attribute to our layout:

<com.bkromhout.rrvl.RealmRecyclerView
        android:id="@+id/recycler"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        app:dragAndDrop="true"
        app:longClickTriggersDrag="true"/>

• Or call the setLongClickTriggersDrag method on our RealmRecyclerView:

recyclerView.setLongClickTriggersDrag(true);

Once enabled, long clicking an item will automatically initiate a drag without you needing to call startDragging. You can still call it yourself in response to some other interaction if you'd like though.

Note that you do still have to implement the onMove method.

Similar to onSwiped and onMove, these correspond directly to the methods available in the ItemTouchHelper.Callback Class provided by the Android support libraries.

<com.bkromhout.rrvl.RealmRecyclerView
        android:id="@+id/recycler"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        app:fastScroll="true"
        app:autoHideFastScrollHandle="true"
        app:handleAutoHideDelay="1000"
        app:useFastScrollBubble="true"/>

@Override
public String getFastScrollBubbleText(int position) {
    return String.valueOf(realmResults.get(position).name.charAt(0));
}

recyclerView.setAdapter(adapter);
recyclerView.setBubbleTextProvider((ItemAdapter) adapter);

@Override
public void onHandleStateChanged(FastScrollerHandleState newState) {
    switch (newState) {
        case VISIBLE:
        case HIDDEN:
        case RELEASED:
            break;
        case PRESSED:
            // Hide the FloatingActionButton.
            fab.hide();
            break;
    }
}

<color name="rrvl_handle_inactive_color">#757575</color>
<color name="rrvl_handle_active_color">#FF4081</color>
<color name="rrvl_bubble_color">#FF4081</color>
<color name="rrvl_bubble_text_color">@android:color/white</color>

<dimen name="rrvl_bubble_text_size">48sp</dimen>
<dimen name="rrvl_handle_margin_end">8dp</dimen>
<dimen name="rrvl_handle_padding_start">8dp</dimen>