LazyLayoutPrefetchState

Class

Common

class LazyLayoutPrefetchState()

State for lazy items prefetching, used by lazy layouts to instruct the prefetcher.

Secondary Constructors

@ExperimentalFoundationApi
constructor(
    prefetchScheduler: PrefetchScheduler? = null,
    onNestedPrefetch: (NestedPrefetchScope.() -> Unit)? = null,
) : this() {
    this.prefetchScheduler = prefetchScheduler
    this.onNestedPrefetch = onNestedPrefetch
}

State for lazy items prefetching, used by lazy layouts to instruct the prefetcher.

Parameters


prefetchScheduler	the `PrefetchScheduler` implementation to use to execute prefetch requests. If null is provided, the default `PrefetchScheduler` for the platform will be used.
onNestedPrefetch	a callback which will be invoked when this LazyLayout is prefetched in context of a parent LazyLayout, giving a chance to recursively prefetch its own children. See `NestedPrefetchScope`.

@ExperimentalFoundationApi
constructor(onNestedPrefetch: (NestedPrefetchScope.() -> Unit)? = null) : this() {
    this.onNestedPrefetch = onNestedPrefetch
}

State for lazy items prefetching, used by lazy layouts to instruct the prefetcher.

Parameters


onNestedPrefetch	a callback which will be invoked when this LazyLayout is prefetched in context of a parent LazyLayout, giving a chance to recursively prefetch its own children. See `NestedPrefetchScope`.

Functions

fun schedulePrecomposition(@IntRange(from = 0) index: Int): PrefetchHandle

Schedules precomposition for the new item. If you also want to premeasure the item please use schedulePrecompositionAndPremeasure instead. This function should only be called once per item. If the item has already been composed at the time this request executes, either from a previous call to this function or because the item is already visible, this request should have no meaningful effect.

Parameters


index	item index to prefetch.

Returns


	A `PrefetchHandle` which can be used to control the lifecycle of the prefetch request. Use `PrefetchHandle.cancel` to cancel the request or `PrefetchHandle.markAsUrgent` to mark the request as urgent.

fun schedulePrecompositionAndPremeasure(
        @IntRange(from = 0) index: Int,
        constraints: Constraints,
        onItemPremeasured: (PrefetchResultScope.() -> Unit)? = null,
    ): PrefetchHandle

Schedules precomposition and premeasure for the new item. This should be used instead of schedulePrecomposition if you also want to premeasure the item. This function should only be called once per item. If the item has already been composed / measured at the time this request executes, either from a previous call to this function or because the item is already visible, this request should have no meaningful effect.

Parameters


index	item index to prefetch.
constraints	`Constraints` to use for premeasuring.
onItemPremeasured	This callback is called when the item premeasuring is finished. If the request is canceled or no measuring is performed this callback won't be called. Use `PrefetchResultScope.getSize` to get the item's size.

Returns


	A `PrefetchHandle` which can be used to control the lifecycle of the prefetch request. Use `PrefetchHandle.cancel` to cancel the request or `PrefetchHandle.markAsUrgent` to mark the request as urgent.

Code Examples

LazyLayoutPrefetchStateSample

@Preview
@Composable
fun LazyLayoutPrefetchStateSample() {
    val items = remember { (0..100).toList().map { it.toString() } }
    var currentHandle = remember<LazyLayoutPrefetchState.PrefetchHandle?> { null }
    val prefetchState = remember { LazyLayoutPrefetchState() }
    // Create an item provider
    val itemProvider = remember {
        {
            object : LazyLayoutItemProvider {
                override val itemCount: Int
                    get() = 100
                @Composable
                override fun Item(index: Int, key: Any) {
                    Box(
                        modifier =
                            Modifier.width(100.dp)
                                .height(100.dp)
                                .background(color = if (index % 2 == 0) Color.Red else Color.Green)
                    ) {
                        Text(text = items[index])
                    }
                }
            }
        }
    }
    Column {
        Button(onClick = { currentHandle = prefetchState.schedulePrecomposition(10) }) {
            Text(text = "Prefetch Item 10")
        }
        Button(onClick = { currentHandle?.cancel() }) { Text(text = "Cancel Prefetch") }
        LazyLayout(modifier = Modifier.size(500.dp), itemProvider = itemProvider) { constraints ->
            // plug the measure policy, this is how we create and layout items.
            val placeablesCache = mutableListOf<Pair<Placeable, Int>>()
            fun Placeable.mainAxisSize() = width
            fun Placeable.crossAxisSize() = height
            val childConstraints =
                Constraints(maxWidth = Constraints.Infinity, maxHeight = constraints.maxHeight)
            var currentItemIndex = 0
            var crossAxisSize = 0
            var mainAxisSize = 0
            // measure items until we either fill in the space or run out of items.
            while (mainAxisSize < constraints.maxWidth && currentItemIndex < items.size) {
                val itemPlaceables = compose(currentItemIndex).map { it.measure(childConstraints) }
                for (item in itemPlaceables) {
                    // save placeable to be placed later.
                    placeablesCache.add(item to mainAxisSize)
                    mainAxisSize += item.mainAxisSize() // item size contributes to main axis size
                    // cross axis size will the size of tallest/widest item
                    crossAxisSize = maxOf(crossAxisSize, item.crossAxisSize())
                }
                currentItemIndex++
            }
            val layoutWidth = minOf(mainAxisSize, constraints.maxHeight)
            val layoutHeight = crossAxisSize
            layout(layoutWidth, layoutHeight) {
                // since this is a linear list all items are placed on the same cross-axis position
                for ((placeable, position) in placeablesCache) {
                    placeable.place(position, 0)
                }
            }
        }
    }
}