AutoCenteringParams

class AutoCenteringParams

Parameters to determine which list item and offset to calculate auto-centering spacing for. The default values are itemIndex = 1 and itemOffset = 0. This will provide sufficient padding for the second item (index = 1) in the list being centerable. This is to match the Wear UX guidelines that a typical list will have a ListHeader item as the first item in the list (index = 0) and that this should not be scrollable into the middle of the viewport, instead the first list item that a user can interact with (index = 1) would be the first that would be in the center.

If your use case is different and you want all list items to be able to be scrolled to the viewport middle, including the first item in the list then set itemIndex = 0.

The higher the value for itemIndex you provide the less auto centering padding will be provided as the amount of padding needed to allow that item to be centered will reduce. Even for a list of short items setting itemIndex above 3 or 4 is likely to result in no auto-centering padding being provided as items with index 3 or 4 will probably already be naturally scrollable to the center of the viewport.

itemOffset allows adjustment of the items position relative the ScalingLazyColumns ScalingLazyListAnchorType. This can be useful if you need fine grained control over item positioning and spacing, e.g. If you are lining up the gaps between two items on the viewport center line where you would want to set the offset to half the distance between listItems in pixels.

See also rememberScalingLazyListState where similar fields are provided to allow control over the initially selected centered item index and offset. By default these match the auto centering defaults meaning that the second item (index = 1) will be the item scrolled to the viewport center.

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalDensity
import androidx.compose.ui.unit.dp
import androidx.wear.compose.foundation.lazy.AutoCenteringParams
import androidx.wear.compose.foundation.lazy.ScalingLazyColumn
import androidx.wear.compose.foundation.lazy.ScalingLazyListAnchorType
import androidx.wear.compose.foundation.lazy.rememberScalingLazyListState
import androidx.wear.compose.material.Chip
import androidx.wear.compose.material.ChipDefaults
import androidx.wear.compose.material.ListHeader
import androidx.wear.compose.material.Text

val coroutineScope = rememberCoroutineScope()
val itemSpacing = 6.dp
// Line up the gap between the items on the center-line
val scrollOffset = with(LocalDensity.current) { -(itemSpacing / 2).roundToPx() }
val state =
    rememberScalingLazyListState(
        initialCenterItemIndex = 1,
        initialCenterItemScrollOffset = scrollOffset
    )

ScalingLazyColumn(
    modifier = Modifier.fillMaxWidth(),
    anchorType = ScalingLazyListAnchorType.ItemStart,
    verticalArrangement = Arrangement.spacedBy(itemSpacing),
    state = state,
    autoCentering = AutoCenteringParams(itemOffset = scrollOffset)
) {
    item { ListHeader { Text(text = "List Header") } }
    items(20) {
        Chip(
            onClick = {
                coroutineScope.launch {
                    // Add +1 to allow for the ListHeader
                    state.animateScrollToItem(it + 1, scrollOffset)
                }
            },
            label = { Text("List item $it") },
            colors = ChipDefaults.secondaryChipColors()
        )
    }
}

Summary

Public constructors
AutoCenteringParams(itemIndex: Int, itemOffset: Int)

Public functions
open operator Boolean
equals(other: Any?)
open Int

Public constructors

AutoCenteringParams

Added in 1.2.0
AutoCenteringParams(itemIndex: Int = 1, itemOffset: Int = 0)
Parameters
itemIndex: Int = 1

Which list item index to enable auto-centering from. Space (padding) will be added such that items with index itemIndex or greater will be able to be scrolled to the center of the viewport. If the developer wants to add additional space to allow other list items to also be scrollable to the center they can use contentPadding on the ScalingLazyColumn. If the developer wants custom control over position and spacing they can switch off autoCentering and provide contentPadding.
itemOffset: Int = 0

What offset, if any, to apply when calculating space for auto-centering the itemIndex item. E.g. itemOffset can be used if the developer wants to align the viewport center in the gap between two list items.

For an example of a ScalingLazyColumn with an explicit itemOffset see:

Public functions

equals

open operator fun equals(other: Any?): Boolean

hashCode

open fun hashCode(): Int