PagedList.Config.Builder

public final class PagedList.Config.Builder


Builder class for PagedList.Config.

You must at minimum specify page size with setPageSize.

Summary

Public constructors

Public methods

final @NonNull PagedList.Config

Creates a PagedList.Config with the given parameters.

final @NonNull PagedList.Config.Builder
setEnablePlaceholders(boolean enablePlaceholders)

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

final @NonNull PagedList.Config.Builder
setInitialLoadSizeHint(@IntRange(from = 1) int initialLoadSizeHint)

Defines how many items to load when first load occurs.

final @NonNull PagedList.Config.Builder
setMaxSize(@IntRange(from = 2) int maxSize)

Defines how many items to keep loaded at once.

final @NonNull PagedList.Config.Builder
setPageSize(@IntRange(from = 1) int pageSize)

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

final @NonNull PagedList.Config.Builder
setPrefetchDistance(@IntRange(from = 0) int prefetchDistance)

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

Public constructors

Builder

public final Builder()

Public methods

build

@NonNull
public final PagedList.Config build()

Creates a PagedList.Config with the given parameters.

Throws
kotlin.IllegalArgumentException

if placeholders are disabled and prefetchDistance is set to 0

kotlin.IllegalArgumentException

if maximum size is less than pageSize + 2*prefetchDistance

setEnablePlaceholders

@NonNull
public final PagedList.Config.Builder setEnablePlaceholders(boolean enablePlaceholders)

Pass false to disable null placeholders in PagedLists using this PagedList.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 PagingSource can count all unloaded items (so that the number of nulls to present is known).

  2. placeholders are not disabled on the PagedList.Config.

Call setEnablePlaceholders(false) to ensure the receiver of the PagedList (often a androidx.paging.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 will not be issued as part of loading, though a androidx.paging.PagedListAdapter may still receive change events as a result of PagedList diffing.

Parameters
boolean enablePlaceholders

false if null placeholders should be disabled.

setInitialLoadSizeHint

@NonNull
public final PagedList.Config.Builder setInitialLoadSizeHint(@IntRange(from = 1) int initialLoadSizeHint)

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.

If not set, defaults to three times page size.

Parameters
@IntRange(from = 1) int initialLoadSizeHint

Number of items to load while initializing the PagedList

setMaxSize

@NonNull
public final PagedList.Config.Builder setMaxSize(@IntRange(from = 2) int maxSize)

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 prefetchDistance plus the pageSize). 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 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.

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

Parameters
@IntRange(from = 2) int maxSize

Maximum number of items to keep in memory, or PagedList.Config.Companion.MAX_SIZE_UNBOUNDED to disable page dropping.

setPageSize

@NonNull
public final PagedList.Config.Builder setPageSize(@IntRange(from = 1) int pageSize)

Defines the number of items loaded at once from the