AsyncPagedListDiffer
open classAsyncPagedListDiffer<T : Any>
kotlin.Any | |
↳ | androidx.paging.AsyncPagedListDiffer |
Helper object for mapping a androidx.paging.PagedList into a RecyclerView.Adapter.
For simplicity, the PagedListAdapter wrapper class can often be used instead of the differ directly. This diff class is exposed for complex cases, and where overriding an adapter base class to support paging isn't convenient.
When consuming a LiveData of PagedList, you can observe updates and dispatch them directly to submitList. The AsyncPagedListDiffer then can present this updating data set simply for an adapter. It listens to PagedList loading callbacks, and uses DiffUtil on a background thread to compute updates as new PagedLists are received.
It provides a simple list-like API with getItem and itemCount for an adapter to acquire and present data objects.
A complete usage pattern with Room would look like this:
@Dao interface UserDao { @Query("SELECT * FROM user ORDER BY lastName ASC") public abstract DataSource.Factory<Integer, User> usersByLastName(); } class MyViewModel extends ViewModel { public final LiveData<PagedList<User>> usersList; public MyViewModel(UserDao userDao) { usersList = new LivePagedListBuilder<>( userDao.usersByLastName(), /* page size */20).build(); } } class MyActivity extends AppCompatActivity { @Override public void onCreate(Bundle savedState) { super.onCreate(savedState); MyViewModel viewModel = new ViewModelProvider(this).get(MyViewModel.class); RecyclerView recyclerView = findViewById(R.id.user_list); final UserAdapter adapter = new UserAdapter(); viewModel.usersList.observe(this, pagedList -> adapter.submitList(pagedList)); recyclerView.setAdapter(adapter); } } class UserAdapter extends RecyclerView.Adapter<UserViewHolder> { private final AsyncPagedListDiffer<User> differ = new AsyncPagedListDiffer(this, DIFF_CALLBACK); @Override public int getItemCount() { return differ.getItemCount(); } public void submitList(PagedList<User> pagedList) { differ.submitList(pagedList); } @Override public void onBindViewHolder(UserViewHolder holder, int position) { User user = differ.getItem(position); if (user != null) { holder.bindTo(user); } else { // Null defines a placeholder item - AsyncPagedListDiffer will automatically // invalidate this row when the actual object is loaded from the database holder.clear(); } } public static final DiffUtil.ItemCallback<User> DIFF_CALLBACK = new DiffUtil.ItemCallback<User>() { @Override public boolean areItemsTheSame( @NonNull User oldUser, @NonNull User newUser) { // User properties may have changed if reloaded from the DB, but ID is fixed return oldUser.getId() == newUser.getId(); } @Override public boolean areContentsTheSame(@NonNull User oldUser, @NonNull User newUser) { // NOTE: if you use equals, your object must properly override Object#equals() // Incorrectly returning false here will result in too many animations. return oldUser.equals(newUser); } } }
Summary
Nested classes | |
---|---|
abstract |
Listener for when the current PagedList is updated. |
Public constructors | |
---|---|
<init>(adapter: RecyclerView.Adapter<*>, diffCallback: DiffUtil.ItemCallback<T>) Convenience for |
|
<init>(listUpdateCallback: ListUpdateCallback, config: AsyncDifferConfig<T>) |
Public methods | |
---|---|
open Unit |
addLoadStateListener(listener: (LoadType, LoadState) -> Unit) Add a LoadState listener to observe the loading state of the current PagedList. |
open Unit |
addPagedListListener(listener: AsyncPagedListDiffer.PagedListListener<T>) Add a PagedListListener to receive updates when the current PagedList changes. |
Unit |
addPagedListListener(callback: (PagedList<T>?, PagedList<T>?) -> Unit) Add a callback to receive updates when the current PagedList changes. |
open T? |
Get the item from the current PagedList at the specified index. |
open Unit |
removeLoadStateListener(listener: (LoadType, LoadState) -> Unit) Remove a previously registered LoadState listener. |
open Unit |
Remove a previously registered PagedListListener. |
Unit |
removePagedListListener(callback: (PagedList<T>?, PagedList<T>?) -> Unit) Remove a previously registered callback via addPagedListListener. |
open Unit |
submitList(pagedList: PagedList<T>?) Pass a new PagedList to the differ. |
open Unit |
submitList(pagedList: PagedList<T>?, commitCallback: Runnable?) Pass a new PagedList to the differ. |
Properties | |
---|---|
open PagedList<T>? |
Returns the PagedList currently being displayed by the differ. |
open Int |
Get the number of items currently presented by this Differ. |
Public constructors
<init>
AsyncPagedListDiffer(
adapter: RecyclerView.Adapter<*>,
diffCallback: DiffUtil.ItemCallback<T>)
Convenience for
AsyncPagedListDiffer( AdapterListUpdateCallback(adapter), AsyncDifferConfig.Builder<T>(diffCallback).build() )
Parameters | |
---|---|
adapter: RecyclerView.Adapter<*> | Adapter that will receive update signals. |
diffCallback: DiffUtil.ItemCallback<T> | The DiffUtil.ItemCallback instance to compare items in the list. |
<init>
AsyncPagedListDiffer(
listUpdateCallback: ListUpdateCallback,
config: AsyncDifferConfig<T>)
Public methods
addLoadStateListener
open fun addLoadStateListener(listener: (LoadType, LoadState) -> Unit): Unit
Add a LoadState listener to observe the loading state of the current PagedList.
As new PagedLists are submitted and displayed, the listener will be notified to reflect current LoadType.REFRESH, LoadType.PREPEND, and LoadType.APPEND states.
Parameters | |
---|---|
listener: (LoadType, LoadState) -> Unit | LoadState listener to receive updates. |
See Also
addPagedListListener
open fun addPagedListListener(listener: AsyncPagedListDiffer.PagedListListener<T>): Unit
Add a PagedListListener to receive updates when the current PagedList changes.
Parameters | |
---|---|
listener: AsyncPagedListDiffer.PagedListListener<T> | Listener to receive updates. |
See Also
addPagedListListener
fun addPagedListListener(callback: (PagedList<T>?, PagedList<T>?) -> Unit): Unit
Add a callback to receive updates when the current PagedList changes.
Parameters | |
---|---|
callback: (PagedList<T>?, PagedList<T>?) -> Unit | to receive updates. |
See Also
getItem
open fun getItem(index: Int): T?
Get the item from the current PagedList at the specified index.
Note that this operates on both loaded items and null padding within the PagedList.
Parameters | |
---|---|
index: Int | Index of item to get, must be >= 0, and < getItemCount . |
Return | |
---|---|
The item, | or null, if a null placeholder is at the specified position. |
Exceptions | |
---|---|
IndexOutOfBoundsException |
if itemCount is 0. |
removeLoadStateListener
open fun removeLoadStateListener(listener: (LoadType, LoadState) -> Unit): Unit
Remove a previously registered LoadState listener.
Parameters | |
---|---|
listener: (LoadType, LoadState) -> Unit | Previously registered listener. |
See Also
removePagedListListener
open fun removePagedListListener(listener: AsyncPagedListDiffer.PagedListListener<T>): Unit
Remove a previously registered PagedListListener.
Parameters | |
---|---|
listener: AsyncPagedListDiffer.PagedListListener<T> | Previously registered listener. |