Cursors, RecyclerViews, and ItemAnimators

RecyclerView is an Android support library class that was introduced with the launch of Android “Lollipop” (compatible all the way back to Android 2.1).  It has a ton of new capabilities and built on a new architecture that promises flexibility and scalability for Android apps.

It’s ListView predecessor didn’t age too well and became cumbersome to use and extend.  ListView had a plethora of built in adapters (classes for binding data to the ListView), including an adapter for binding a ListView to a Cursor.  RecyclerView is great, but it’s missing a cursor adapter.  Because RecyclerView is so extensible, developers can easily write one, like the one written by Jason Yu:

Well, great, now I can use CursorLoaders, Cursors, and RecyclerViews in my Android app.  There’s one problem.  Backing up a bit, RecyclerViews introduced ItemAnimators.  They provide an easy way to run animations when items in the data backing a RecyclerView are inserted, removed, or changed.  If you’ve done any type of animations with ListView, you’d appreciate the ease of ItemAnimators.  RecyclerView determines which animation to run using RecyclerView.Adapter functions called in an implementing adapter:

  • notifyItemChanged
  • notifyItemRangedChanged
  • notifyItemInserted
  • notifyItemRangeInserted
  • notifyItemRemoved
  • notifyItemRangeRemoved
  • notifyItemMoved

Each of the mentioned functions requires an index, or range of indexes indicating which items were inserted, removed, or changed.

Going back to the problem, using a CursorLoader and Cursors in an Android app.  A dataset change (new record, deleted record, changed record) causes CursorLoader to initiate the allocation of a new Cursor that points to the new dataset.  This is great, we can pass that new Cursor to our CursorRecyclerViewAdapter seen above.  This is where our problem rears it’s head.  Our default implementation only knows that the dataset has changed, but doesn’t know the particulars (which records are new, removed, or changed)…so it calls notifyDataSetChanged, which causes the entire RecyclerView to be invalidated and redrawn.  It looks bad and is inefficient (see explanation at the end).

I needed a way to determine which records were inserted, which were removed, and which were changed.  I had a cursor to the old dataset and a cursor to the new dataset.  My only options were to diff them, building a list of records that were added, removed, and changed.  This allowed me to run the appropriate notifyItem* function and gain the corresponding animation that improved the user experience.  This is the RecyclerView adapter I use in my podcast app, PremoFM.

In this Gist, I’ve added several things to make this diff possible, built on the great work of Jason Yu.

First, my dataset contains a column I use to record a timestamp when that record is updated.  I pass the name of the column to the CursorRecyclerViewAdapter.  This becomes my comparison column (mComparisonColumn).  This saves me from having to compare each value, in each row in a record from one cursor, to each value in each row in a record in another cursor.

Second, I’ve added several functions that compare a new cursor and an old cursor:

  1. getChangeOrInsertRecords – iterates over the incoming cursor, then the outgoing cursor in an inner loop.  Matches each record on a row ID.  If a match is found, it then compares the comparison column.  If the values in that column don’t match, this record was edited.  If a record in the incoming cursor is not found in the outgoing cursor, then it’s a new record.  If the incoming cursor is empty, then all the records were deleted.  If the outgoing cursor is empty, then all the records in the incoming cursor can be assumed as inserted.
  2. getDeletedRecords – iterates over the outgoing cursor, then the incoming cursor in an inner loop.  It matches each record on a row ID.  If a record in the outgoing cursor is not found in the incoming cursor, then we can assume that the record has been deleted.

The result of running these two functions is a list that contains the index and that indexes difference (insert, remove, change).  I use this data in swapCursor to run the corresponding notifyItem* function and I gain animations when items change.

What does all of this get me?  Look at the user interface differences below.

notify_dataset  notify_item

Left: notifyDataSetChanged / Right: notifyItem*

Downsides?  The diff is a O(n^2) operation.  If you have a ton of records, this operation could take a while.  A possible optimization is to only diff the records that are visible in the RecyclerView and not the entire dataset behind each cursor.

Let me know if you have any questions by hitting me up on Twitter.  Also download my podcast app, PremoFM, in the Google Play Store now by going to

Why is using notifyDataSetChanged with RecyclerView bad and inefficient?  Calling notifyItemChanged causes RecyclerView to make a requestLayout for the RecyclerView.  So even if the text was updated in the first item in my RecyclerView, all the items will be redrawn.  The function notifyDataSetChanged triggers a call to RecyclerView.AdapterDataObservable.notifyChange.  In this function, each RecyclerViewDataObserver.onChanged function is called, which eventually triggers a requestLayout call.

Evidence is freely available for in the Android source code.