SnapshotLoader



Contains the public APIs for load operations in tests.

Tracks generational information and provides the listener to LoaderCallback on PagingDataPresenter operations.

Summary

Public functions

suspend Unit
appendScrollWhile(predicate: (item) -> Boolean)

Imitates scrolling down paged items, appending data until the given predicate returns false.

Cmn
suspend Unit
flingTo(index: Int)

Imitates flinging from current index to the target index.

Cmn
suspend Unit
prependScrollWhile(predicate: (item) -> Boolean)

Imitates scrolling up paged items, prepending data until the given predicate returns false.

Cmn
suspend Unit

Refresh the data that is presented on the UI.

Cmn
suspend Unit
scrollTo(index: Int)

Imitates scrolling from current index to the target index.

Cmn

Public functions

appendScrollWhile

suspend fun appendScrollWhile(predicate: (item) -> Boolean): Unit

Imitates scrolling down paged items, appending data until the given predicate returns false.

Note: This API loads an item before passing it into the predicate. This means the loaded pages may include the page which contains the item that does not match the predicate. For example, if pageSize = 2, the predicate {item: Int -> item < 3 } will return items [1, 2,3, 4] where 3, 4 is the page containing the boundary item3 not matching the predicate.

The loaded pages are also dependent on PagingConfig settings such as PagingConfig.prefetchDistance:

  • if prefetchDistance 0, the resulting appends will include prefetched items. For example, if pageSize = 2 and prefetchDistance = 2, the predicate {item: Int -> item < 3 } will load items [1, 2, 3, 4, 5, 6] where 5, 6 is the prefetched page.

Parameters
predicate: (item) -> Boolean

the predicate to match (return true) to continue append scrolls

flingTo

suspend fun flingTo(index: Int): Unit

Imitates flinging from current index to the target index. It will continue scrolling even as data is being loaded in. Returns all available data that has been scrolled through.

The scroll direction (prepend or append) is dependent on current index and target index. In general, scrolling to a smaller index triggers PREPEND while scrolling to a larger index triggers APPEND.

This function will scroll into placeholders. This means jumping is supported when PagingConfig.enablePlaceholders is true and the amount of placeholders traversed has reached PagingConfig.jumpThreshold. Jumping is disabled when PagingConfig.enablePlaceholders is false.

When PagingConfig.enablePlaceholders is false, the index is scoped within currently loaded items. For example, in a list of items(0-20) with currently loaded items(10-15), index0 = item(10), index4 = item(15).

Supports index beyond currently loaded items when PagingConfig.enablePlaceholders is false:

  1. For prepends, it supports negative indices for as long as there are still available data to load from. For example, take a list of items(0-20), pageSize = 1, with currently loaded items(10-15). With index0 = item(10), a scrollTo(-4) will scroll to item(6) and update index0 = item(6).

  2. For appends, it supports indices >= loadedDataSize. For example, take a list of items(0-20), pageSize = 1, with currently loaded items(10-15). With index4 = item(15), a scrollTo(7) will scroll to item(18) and update index7 = item(18). Note that both examples does not account for prefetches.

The index accounts for separators/headers/footers where each one of those consumes one scrolled index.

For both append/prepend, this function stops loading prior to fulfilling requested scroll distance if there are no more data to load from.

Parameters
index: Int

The target index to scroll to

See also
scrollTo

for faking scrolls that awaits for placeholders to load before continuing to scroll.

prependScrollWhile

suspend fun prependScrollWhile(predicate: (item) -> Boolean): Unit

Imitates scrolling up paged items, prepending data until the given predicate returns false.

Note: This API loads an item before passing it into the predicate. This means the loaded pages may include the page which contains the item that does not match the predicate. For example, if pageSize = 2, initialKey = 3, the predicate {item: Int -> item >= 3 } will return items [1, 2,3, 4] where 1, 2 is the page containing the boundary item2 not matching the predicate.

The loaded pages are also dependent on PagingConfig settings such as PagingConfig.prefetchDistance:

  • if prefetchDistance 0, the resulting prepends will include prefetched items. For example, if pageSize = 2, initialKey = 3, and prefetchDistance = 2, the predicate {item: Int -> item 4 } will load items [1, 2, 3, 4, 5, 6] where both 1,2 and 5, 6 are the prefetched pages.

Parameters
predicate: (item) -> Boolean

the predicate to match (return true) to continue prepend scrolls

refresh

suspend fun refresh(): Unit

Refresh the data that is presented on the UI.

refresh triggers a new generation of PagingData / PagingSource to represent an updated snapshot of the backing dataset.

This fake paging operation mimics UI-driven refresh signals such as swipe-to-refresh.

scrollTo

suspend fun scrollTo(index: Int): Unit

Imitates scrolling from current index to the target index. It waits for an item to be loaded in before triggering load on next item. Returns all available data that has been scrolled through.

The scroll direction (prepend or append) is dependent on current index and target index. In general, scrolling to a smaller index triggers PREPEND while scrolling to a larger index triggers APPEND.

When PagingConfig.enablePlaceholders is false, the index is scoped within currently loaded items. For example, in a list of items(0-20) with currently loaded items(10-15), index0 = item(10), index4 = item(15).

Supports index beyond currently loaded items when PagingConfig.enablePlaceholders is false:

  1. For prepends, it supports negative indices for as long as there are still available data to load from. For example, take a list of items(0-20), pageSize = 1, with currently loaded items(10-15). With index0 = item(10), a scrollTo(-4) will scroll to item(6) and update index0 = item(6).

  2. For appends, it supports indices >= loadedDataSize. For example, take a list of items(0-20), pageSize = 1, with currently loaded items(10-15). With index4 = item(15), a scrollTo(7) will scroll to item(18) and update index7 = item(18). Note that both examples does not account for prefetches.

The index accounts for separators/headers/footers where each one of those consumes one scrolled index.

For both append/prepend, this function stops loading prior to fulfilling requested scroll distance if there are no more data to load from.

Parameters
index: Int

The target index to scroll to

See also
flingTo

for faking a scroll that continues scrolling without waiting for items to be loaded in. Supports jumping.