{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}
public abstract class PagedList<T extends Object>
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 null
s 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 list.
PagedList
can present data for an unbounded, infinite scrolling list, or a very large but countable list. Use PagedList.Config
to control how many items a PagedList
loads, and when.
If you use androidx.paging.LivePagedListBuilder
to get a androidx.lifecycle.LiveData, it will initialize PagedList
s on a background thread for you.
There are two ways that PagedList
can represent its not-yet-loaded data - with or without null
placeholders.
With placeholders, the PagedList
is always the full size of the data set. get(N)
returns the N
th item in the data set, or null
if its not yet loaded.
Without 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 get(N)
returns the N
th loaded item. This is not necessarily the N
th item in the data set.
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 null
items. 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
.
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.
See PagingSource
and androidx.paging.LivePagedListBuilder
for how new PagedList
s are created to represent changed data.
A PagedList
snapshot is simply an immutable shallow copy of the current state of the PagedList
as a List
. It will reference the same inner items, and contain the same null
placeholders, if present.
Parameters | |
---|---|
<T extends Object> |
The type of the entries in the list. |
Nested types |
|
---|---|
PagedList.BoundaryCallback |
Signals when a PagedList has reached the end of available data. |
PagedList.Builder |
Builder class for |
PagedList.Callback |
Callback signaling when content is loaded into the list. |
PagedList.Config |
Configures how a |
PagedList.Config.Builder |
Builder class for |
Public fields |
|
---|---|
final @NonNull PagedList.Config |
Return the Config used to construct this PagedList. |
final @NonNull DataSource<@NonNull ?, @NonNull T> |
This field is deprecated. DataSource is deprecated and has been replaced by PagingSource. |
abstract boolean |
True if the |
boolean |
Returns whether the list is immutable. |
abstract @Nullable Object |
Return the key for the position passed most recently to |
final int |
Returns the number of items loaded in the |
final int |
|
final int |
Position offset of the data in the list. |
int |
Size of the list, including any placeholders (not-yet-loaded null padding). |
Public methods |
|
---|---|
final void |
This method is deprecated. Dispatching a diff since snapshot created is behavior that can be instead tracked by attaching a Callback to the PagedList that is mutating, and tracking changes since calling PagedList.snapshot(). |
final void |
addWeakCallback(@NonNull PagedList.Callback callback) Adds a callback. |
final void |
Add a listener to observe the loading state of the |
abstract void |
detach() Detach the |
@Nullable T |
get(int index) Get the item in the list of loaded items at the provided index. |
final void |
loadAround(int index) Load adjacent items to passed index. |
final void |
removeWeakCallback(@NonNull PagedList.Callback callback) Removes a previously added callback. |
final void |
removeWeakLoadStateListener( Remove a previously registered load state listener. |
void |
retry() Retry any errors associated with this |
final @NonNull List<@NonNull T> |
snapshot() Returns an immutable snapshot of the |
Inherited methods |
||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
||||||||||||||||||||||||||||||
|
||||||||||||||||||||||||||||||
|
@NonNull
public final @NonNull PagedList.Config config
Return the Config used to construct this PagedList.
Returns | |
---|---|
@NonNull PagedList.Config |
the Config of this PagedList |
@NonNull
public final @NonNull DataSource<@NonNull ?, @NonNull T> dataSource
Throws | |
---|---|
kotlin.IllegalStateException |
if this |
@NonNull
public abstract boolean isDetached
True if the PagedList
has detached the PagingSource
it was loading from, and will no longer load new data.
A detached list is immutable
.
Returns | |
---|---|
boolean |
|
@NonNull
public boolean isImmutable
Returns whether the list is immutable.
Immutable lists may not become mutable again, and may safely be accessed from any thread.
In the future, this method may return true when a PagedList has completed loading from its PagingSource
. Currently, it is equivalent to isDetached
.
Returns | |
---|---|
boolean |
|
@Nullable
public abstract @Nullable Object lastKey
Return the key for the position passed most recently to loadAround
.
When a PagedList is invalidated, you can pass the key returned by this function to initialize the next PagedList. This ensures (depending on load times) that the next PagedList that arrives will have data that overlaps. If you use androidx.paging.LivePagedListBuilder, it will do this for you.
Returns | |
---|---|
@Nullable Object |
Key of position most recently passed to |
@NonNull
public final int loadedCount
Returns the number of items loaded in the PagedList
.
Unlike size
this counts only loaded items, not placeholders.
If placeholders are disabled
, this method is equivalent to size
.
Returns | |
---|---|
int |
Number of items currently loaded, not counting placeholders. |
See also | |
---|---|
size |
@NonNull
public final int positionOffset
Position offset of the data in the list.
If the PagingSource backing this PagedList is counted, the item returned from get(i)
has a position in the original data set of i + getPositionOffset()
.
If placeholders are enabled, this value is always 0
, since get(i)
will return either the data in its original index, or null if it is not loaded.
@NonNull
public int size
Size of the list, including any placeholders (not-yet-loaded null padding).
To get the number of loaded items, not counting placeholders, use loadedCount
.
See also | |
---|---|
loadedCount |
@NonNull
public final voidaddWeakCallback(
@Nullable List<@NonNull T> previousSnapshot,
@NonNull PagedList.Callback callback
)
Adds a callback, and issues updates since the previousSnapshot
was created.
If previousSnapshot
is passed, the callback
will also immediately be dispatched any differences between the previous snapshot, and the current state. For example, if the previousSnapshot was of 5 nulls, 10 items, 5 nulls, and the current state was 5 nulls, 12 items, 3 nulls, the callback would immediately receive a call ofonChanged(14, 2)
.
This allows an observer that's currently presenting a snapshot to catch up to the most recent version, including any changes that may have been made.
The callback is internally held as weak reference, so PagedList
doesn't hold a strong reference to its observer, such as a PagedListAdapter
. If an adapter were held with a strong reference, it would be necessary to clear its PagedList
observer before it could be GC'd.
Parameters | |
---|---|
@Nullable List<@NonNull T> previousSnapshot |
Snapshot previously captured from this List, or |
@NonNull PagedList.Callback callback |
|
See also | |
---|---|
removeWeakCallback |
@NonNull
public final void addWeakCallback(@NonNull PagedList.Callback callback)
Adds a callback.
The callback is internally held as weak reference, so PagedList
doesn't hold a strong reference to its observer, such as a androidx.paging.PagedListAdapter
. If an adapter were held with a strong reference, it would be necessary to clear its PagedList
observer before it could be GC'd.
Parameters | |
---|---|
@NonNull PagedList.Callback callback |
Callback to dispatch to. |
See also | |
---|---|
removeWeakCallback |
@NonNull
public final void addWeakLoadStateListener(
@NonNull Function2<@NonNull LoadType, @NonNull LoadState, Unit> listener
)
Add a listener to observe the loading state of the PagedList
.
Parameters | |
---|---|
@NonNull Function2<@NonNull LoadType, @NonNull LoadState, Unit> listener |
Listener to receive updates. |
See also | |
---|---|
removeWeakLoadStateListener |
@NonNull
public abstract void detach()
Detach the PagedList
from its PagingSource
, and attempt to load no more data.
This is called automatically when a PagingSource
is observed to be invalid, which is a signal to stop loading. The PagedList
will continue to present existing data, but will not initiate new loads.
@Nullable
public T get(int index)
Get the item in the list of loaded items at the provided index.
Parameters | |
---|---|
int index |
Index in the loaded item list. Must be >= 0, and < |
Returns | |
---|---|
T |
The item at the passed index, or |
See also | |
---|---|
size |
@NonNull
public final void loadAround(int index)
Load adjacent items to passed index.
Parameters | |
---|---|
int index |
Index at which to load. |
Throws | |
---|---|
kotlin.IndexOutOfBoundsException |
if index is not within bounds. |
@NonNull
public final void removeWeakCallback(@NonNull PagedList.Callback callback)
Removes a previously added callback.
Parameters | |
---|---|
@NonNull PagedList.Callback callback |
Callback, previously added. |
See also | |
---|---|
addWeakCallback |
@NonNull
public final void removeWeakLoadStateListener(
@NonNull Function2<@NonNull LoadType, @NonNull LoadState, Unit> listener
)
Remove a previously registered load state listener.
Parameters | |
---|---|
@NonNull Function2<@NonNull LoadType, @NonNull LoadState, Unit> listener |
Previously registered listener. |
See also | |
---|---|
addWeakLoadStateListener |
@NonNull
public void retry()
Retry any errors associated with this PagedList
.
If for example a network PagingSource
append timed out, calling this method will retry the failed append load.
You can observe loading state via addWeakLoadStateListener
, though generally this is done through the PagedListAdapter
or AsyncPagedListDiffer
.
@NonNull
public final List<@NonNull T> snapshot()
Returns an immutable snapshot of the PagedList
in its current state.
If this is immutableisImmutable
due to its PagingSource
being invalid, it will be returned.