PagingConfig

An object used to configure loading behavior within a Pager, as it loads content from a PagingSource.

Summary

Constants
const Int

When maxSize is set to MAX_SIZE_UNBOUNDED, the maximum number of items loaded is unbounded, and pages will never be dropped.
Cmn

Public constructors
PagingConfig(
    pageSize: Int,
    prefetchDistance: @IntRange(from = 0) Int,
    enablePlaceholders: Boolean,
    initialLoadSize: @IntRange(from = 1) Int,
    maxSize: @IntRange(from = 2) Int,
    jumpThreshold: Int
)
Cmn

Public properties
Boolean

Defines whether PagingData may display null placeholders, if the PagingSource provides them.
Cmn
Int

Defines requested load size for initial load from PagingSource, typically larger than pageSize, so on first load data there's a large enough range of content loaded to cover small scrolls.
Cmn
Int

Defines a threshold for the number of items scrolled outside the bounds of loaded items before Paging should give up on loading pages incrementally, and instead jump to the user's position by triggering REFRESH via invalidate.
Cmn
Int

Defines the maximum number of items that may be loaded into PagingData before pages should be dropped.
Cmn
Int

Defines the number of items loaded at once from the PagingSource.
Cmn
Int

Prefetch distance which defines how far from the edge of loaded content an access must be to trigger further loading.
Cmn

Constants

MAX_SIZE_UNBOUNDED

Cmn 
const val MAX_SIZE_UNBOUNDED: Int

When maxSize is set to MAX_SIZE_UNBOUNDED, the maximum number of items loaded is unbounded, and pages will never be dropped.

Public constructors

PagingConfig

Cmn
Added in 3.0.0
PagingConfig(
    pageSize: Int,
    prefetchDistance: @IntRange(from = 0) Int = pageSize,
    enablePlaceholders: Boolean = true,
    initialLoadSize: @IntRange(from = 1) Int = pageSize * DEFAULT_INITIAL_PAGE_MULTIPLIER,
    maxSize: @IntRange(from = 2) Int = MAX_SIZE_UNBOUNDED,
    jumpThreshold: Int = COUNT_UNDEFINED
)

Public properties

enablePlaceholders

Cmn
Added in 3.0.0
val enablePlaceholders: Boolean

Defines whether PagingData may display null placeholders, if the PagingSource provides them.

PagingData will present null placeholders for not-yet-loaded content if two conditions are met:

  1. Its PagingSource can count all unloaded items (so that the number of nulls to present is known).

  2. enablePlaceholders is set to true

initialLoadSize

Cmn
Added in 3.0.0
val initialLoadSize: Int

Defines requested load size for initial load from PagingSource, typically larger than pageSize, so on first load data there's a large enough range of content loaded to cover small scrolls.

Note: initialLoadSize is used to inform PagingSource.LoadParams.loadSize, but is not enforced. A PagingSource may completely ignore this value and still return a valid initial Page.

jumpThreshold

Cmn
Added in 3.0.0
val jumpThreshold: Int

Defines a threshold for the number of items scrolled outside the bounds of loaded items before Paging should give up on loading pages incrementally, and instead jump to the user's position by triggering REFRESH via invalidate.

Defaults to COUNT_UNDEFINED, which disables invalidation due to scrolling large distances.

Note: In order to allow PagingSource to resume from the user's current scroll position after invalidation, PagingSource.getRefreshKey must be implemented.

See also
getRefreshKey
jumpingSupported

maxSize

Cmn
Added in 3.0.0
val maxSize: Int

Defines the maximum number of items that may be loaded into PagingData before pages should be dropped.

If set to MAX_SIZE_UNBOUNDED, pages will never be dropped.

This can be used to cap the number of items kept in memory by dropping pages. This value is typically many pages so old pages are cached in case the user scrolls back.

This value must be at least two times the prefetchDistance plus the pageSize). This constraint prevent loads from being continuously fetched and discarded due to prefetching.

maxSize is best effort, not a guarantee. In practice, if maxSize is many times pageSize, the number of items held by PagingData will not grow above this number. Exceptions are made as necessary to guarantee:

  • Pages are never dropped until there are more than two pages loaded. Note that a PagingSource may not be held strictly to requested pageSize, so two pages may be larger than expected.

  • Pages are never dropped if they are within a prefetch window (defined to be pageSize + (2 * prefetchDistance)) of the most recent load.

See also
MAX_SIZE_UNBOUNDED

pageSize

Cmn
Added in 3.0.0
val pageSize: Int

Defines the number of items loaded at once from the PagingSource.

Should be several times the number of visible items onscreen.

Configuring your page size depends on how your data is being loaded and used. Smaller page sizes improve memory usage, latency, and avoid GC churn. Larger pages generally improve loading throughput, to a point (avoid loading more than 2MB from SQLite at once, since it incurs extra cost).

If you're loading data for very large, social-media style cards that take up most of a screen, and your database isn't a bottleneck, 10-20 may make sense. If you're displaying dozens of items in a tiled grid, which can present items during a scroll much more quickly, consider closer to 100.

Note: pageSize is used to inform PagingSource.LoadParams.loadSize, but is not enforced. A PagingSource may completely ignore this value and still return a valid Page.

prefetchDistance

Cmn
Added in 3.0.0
val prefetchDistance: Int

Prefetch distance which defines how far from the edge of loaded content an access must be to trigger further loading. Typically should be set several times the number of visible items onscreen.

E.g., If this value is set to 50, a PagingData will attempt to load 50 items in advance of data that's already been accessed.

A value of 0 indicates that no list items will be loaded until they are specifically requested. This is generally not recommended, so that users don't observe a placeholder item (with placeholders) or end of list (without) while scrolling.