PagedList<T : Any> : AbstractList<T>
Lazy loading list that pages in immutable content from a PagingSource.
A PagedList is a List which loads its data in chunks (pages) from a PagingSource. Items can be accessed with get, and further loading can be triggered with loadAround. To display a PagedList, see androidx.paging.PagedListAdapter, which enables the binding of a PagedList to a androidx.recyclerview.widget.RecyclerView.
All data in a PagedList is loaded from its PagingSource. Creating a PagedList loads the first chunk of data from the PagingSource immediately, and should for this reason be done on a background thread. The constructed PagedList may then be passed to and used on the UI thread. This is done to prevent passing a list with no loaded content to the UI thread, which should generally not be presented to the user.
A PagedList initially presents this first partial load as its content, and expands over time as
content is loaded in. When loadAround is called, items will be loaded in near the passed
list index. If placeholder
nulls are present in the list, they will be replaced as
content is loaded. If not, newly loaded items will be inserted at the beginning or end of the
There are two ways that PagedList can represent its not-yet-loaded data - with or without
With placeholders, the PagedList is always the full size of the data set.
Nth item in the data set, or
null if its not yet loaded.
null placeholders, the PagedList is the sublist of data that has already been
loaded. The size of the PagedList is the number of currently loaded items, and
Nth loaded item. This is not necessarily the
Nth item in the
Placeholders have several benefits:
- They express the full sized list to the presentation layer (often a androidx.paging.PagedListAdapter), and so can support scrollbars (without jumping as pages are loaded or dropped) and fast-scrolling to any position, loaded or not.
- They avoid the need for a loading spinner at the end of the loaded list, since the list is always full sized.
They also have drawbacks:
- Your Adapter needs to account for
nullitems. This often means providing default values in data you bind to a androidx.recyclerview.widget.RecyclerView.ViewHolder.
- They don't work well if your item views are of different sizes, as this will prevent loading items from cross-fading nicely.
- They require you to count your data set, which can be expensive or impossible, depending on your PagingSource.
Placeholders are enabled by default, but can be disabled in two ways. They are disabled if the
PagingSource does not count its data set in its initial load, or if
false is passed to
PagedList.Config.Builder.setEnablePlaceholders when building a PagedList.Config.
Mutability and Snapshots
A PagedList is mutable while loading, or ready to load from its PagingSource. As loads succeed, a mutable PagedList will be updated via Runnables on the main thread. You can listen to these updates with a PagedList.Callback. (Note that androidx.paging.PagedListAdapter will listen to these to signal RecyclerView about the updates/changes).
If a PagedList attempts to load from an invalid PagingSource, it will detach from the PagingSource, meaning that it will no longer attempt to load data. It will return true from isImmutable, and a new PagingSource / PagedList pair must be created to load further data.
Signals when a PagedList has reached the end of available data.
Builder class for PagedList.
Callback signaling when content is loaded into the list.
Adds a callback, and issues updates since the previousSnapshot was created.
Adds a callback.
Add a listener to observe the loading state of the PagedList.
Get the item in the list of loaded items at the provided index.
Load adjacent items to passed index.
Removes a previously added callback.
Remove a previously registered load state listener.
Retry any errors associated with this PagedList.
Returns an immutable snapshot of the PagedList in its current state.
|Inherited extension functions|