Android Dev Summit, October 23-24: two days of technical content, directly from the Android team. Sign-up for livestream updates.

Builder

class Builder
kotlin.Any
   ↳ androidx.paging.PagedList.Config.Builder

Builder class for Config.

You must at minimum specify page size with setPageSize(int).

Summary

Public constructors

Builder class for Config.

Public methods

PagedList.Config

Creates a Config with the given parameters.

PagedList.Config.Builder
setEnablePlaceholders(enablePlaceholders: Boolean)

Pass false to disable null placeholders in PagedLists using this Config.

PagedList.Config.Builder
setInitialLoadSizeHint(initialLoadSizeHint: Int)

Defines how many items to load when first load occurs.

PagedList.Config.Builder
setMaxSize(maxSize: Int)

Defines how many items to keep loaded at once.

PagedList.Config.Builder
setPageSize(pageSize: Int)

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

PagedList.Config.Builder
setPrefetchDistance(prefetchDistance: Int)

Defines how far from the edge of loaded content an access must be to trigger further loading.

Public constructors

<init>

Builder()

Builder class for Config.

You must at minimum specify page size with setPageSize(int).

Public methods

build

@NonNull fun build(): PagedList.Config

Creates a Config with the given parameters.

Return
PagedList.Config: A new Config.

setEnablePlaceholders

@NonNull fun setEnablePlaceholders(enablePlaceholders: Boolean): PagedList.Config.Builder

Pass false to disable null placeholders in PagedLists using this Config.

If not set, defaults to true.

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

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

2) placeholders are not disabled on the Config.

Call setEnablePlaceholders(false) to ensure the receiver of the PagedList (often a PagedListAdapter) doesn't need to account for null items.

If placeholders are disabled, not-yet-loaded content will not be present in the list. Paging will still occur, but as items are loaded or removed, they will be signaled as inserts to the PagedList.Callback. PagedList.Callback#onChanged(int, int) will not be issued as part of loading, though a PagedListAdapter may still receive change events as a result of PagedList diffing.

Parameters
enablePlaceholders Boolean: False if null placeholders should be disabled.
Return
PagedList.Config.Builder: this

setInitialLoadSizeHint

@NonNull fun setInitialLoadSizeHint(initialLoadSizeHint: Int): PagedList.Config.Builder

Defines how many items to load when first load occurs.

This value is typically larger than page size, so on first load data there's a large enough range of content loaded to cover small scrolls.

When using a PositionalDataSource, the initial load size will be coerced to an integer multiple of pageSize, to enable efficient tiling.

If not set, defaults to three times page size.

Parameters
initialLoadSizeHint Int: Number of items to load while initializing the PagedList.
Return
PagedList.Config.Builder: this

setMaxSize

@NonNull fun setMaxSize(maxSize: Int): PagedList.Config.Builder

Defines how many items to keep loaded at once.

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 setPrefetchDistance(int) prefetch distance} plus the page size). This constraint prevent loads from being continuously fetched and discarded due to prefetching.

The max size specified here best effort, not a guarantee. In practice, if maxSize is many times the page size, the number of items held by the PagedList 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 DataSource 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.

PageKeyedDataSource does not currently support dropping pages - when loading from a PageKeyedDataSource, this value is ignored.

If not set, defaults to MAX_SIZE_UNBOUNDED, which disables page dropping.

Parameters
maxSize Int: Maximum number of items to keep in memory, or MAX_SIZE_UNBOUNDED to disable page dropping.
Return
PagedList.Config.Builder: this

setPageSize

@NonNull fun setPageSize(pageSize: Int): PagedList.Config.Builder

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

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.

Parameters
pageSize Int: Number of items loaded at once from the DataSource.
Return
PagedList.Config.Builder: this

setPrefetchDistance

@NonNull fun setPrefetchDistance(prefetchDistance: Int): PagedList.Config.Builder

Defines how far from the edge of loaded content an access must be to trigger further loading.

Should be several times the number of visible items onscreen.

If not set, defaults to page size.

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.

Parameters
prefetchDistance Int: Distance the PagedList should prefetch.
Return
PagedList.Config.Builder: this