androidx.xr.glimmer.list

Interfaces

LazyListItemInfo

Contains useful information about an individual item in a VerticalList.
ListItemScope

Receiver scope being used by the item content parameter of VerticalList.
ListLayoutInfo

Information about the layout of the VerticalList.
ListScope

Receiver scope which is used by VerticalList.

Classes

ListState

A state object that can be hoisted to control and observe scrolling.

Annotations

ListScopeMarker

DSL marker used to distinguish between list layout scope and the item scope.

Top-level functions summary

SnapLayoutInfoProvider

List snapping aligns the focus line with the center of the closest item.
Unit
@Composable
VerticalList(
    modifier: Modifier,
    state: ListState,
    contentPadding: PaddingValues,
    userScrollEnabled: Boolean,
    overscrollEffect: OverscrollEffect?,
    flingBehavior: FlingBehavior,
    reverseLayout: Boolean,
    horizontalAlignment: Alignment.Horizontal,
    verticalArrangement: Arrangement.Vertical,
    content: ListScope.() -> Unit
)

This is a scrolling list component that only composes and lays out the currently visible items.
ListState
@Composable
rememberListState(
    initialFirstVisibleItemIndex: Int,
    initialFirstVisibleItemScrollOffset: Int
)

Creates a ListState that is remembered across compositions.
FlingBehavior

Creates and remembers a focus-aware fling behavior that aligns the focus line with the center of the element expected to gain focus at the end of the fling.

Extension functions summary

inline Unit
<T : Any?> ListScope.items(
    items: List<T>,
    noinline key: ((item) -> Any)?,
    noinline contentType: (item) -> Any?,
    crossinline itemContent: @Composable ListItemScope.(item) -> Unit
)

Adds a list of items.
inline Unit
<T : Any?> ListScope.itemsIndexed(
    items: List<T>,
    noinline key: ((index: Int, item) -> Any)?,
    crossinline contentType: (index: Int, item) -> Any?,
    crossinline itemContent: @Composable ListItemScope.(index: Int, item) -> Unit
)

Adds a list of items where the content of an item is aware of its index.

Top-level functions

SnapLayoutInfoProvider

fun SnapLayoutInfoProvider(state: ListState): SnapLayoutInfoProvider

List snapping aligns the focus line with the center of the closest item. Combined with adaptive scrolling, this ensures that users have to move the same distance when swipes between items of the similar size, resulting in predictable movement.

Parameters
state: ListState

The ListState to observe for layout and focus information.
Returns
SnapLayoutInfoProvider

A focus-aware SnapLayoutInfoProvider instance.

VerticalList

@Composable
fun VerticalList(
    modifier: Modifier = Modifier,
    state: ListState = rememberListState(),
    contentPadding: PaddingValues = PaddingValues(0.dp),
    userScrollEnabled: Boolean = true,
    overscrollEffect: OverscrollEffect? = rememberOverscrollEffect(),
    flingBehavior: FlingBehavior = rememberSnapFlingBehavior(state),
    reverseLayout: Boolean = false,
    horizontalAlignment: Alignment.Horizontal = Alignment.Start,
    verticalArrangement: Arrangement.Vertical = Arrangement.Top,
    content: ListScope.() -> Unit
): Unit

This is a scrolling list component that only composes and lays out the currently visible items. It is based on androidx.compose.foundation.lazy.LazyColumn, but with extra functionality and customized behavior required for Glimmer. Glimmer applications should always use VerticalList instead of LazyColumn to ensure correct behavior.

The content block defines a DSL which allows you to emit items of different types. For example you can use ListScope.item to add a single item and ListScope.items to add a list of items.

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.PaddingValues
import androidx.compose.ui.unit.dp
import androidx.xr.glimmer.ListItem
import androidx.xr.glimmer.Text
import androidx.xr.glimmer.list.VerticalList

VerticalList(
    contentPadding = PaddingValues(16.dp),
    verticalArrangement = Arrangement.spacedBy(20.dp),
) {
    item { ListItem { Text("Header") } }
    items(count = 10) { index -> ListItem { Text("Item-$index") } }
    item { ListItem { Text("Footer") } }
}
Parameters
modifier: Modifier = Modifier

the modifier to apply to this layout.
state: ListState = rememberListState()

the state object to be used to control or observe the list's state.
contentPadding: PaddingValues = PaddingValues(0.dp)

a padding around the whole content. This will add padding for the. content after it has been clipped, which is not possible via modifier param. You can use it to add a padding before the first item or after the last one.
userScrollEnabled: Boolean = true

If user gestures are enabled.
overscrollEffect: OverscrollEffect? = rememberOverscrollEffect()

the OverscrollEffect that will be used to render overscroll for this layout. Note that the OverscrollEffect.node will be applied internally as well - you do not need to use Modifier.overscroll separately.
flingBehavior: FlingBehavior = rememberSnapFlingBehavior(state)

logic describing fling and snapping behavior when drag has finished.
reverseLayout: Boolean = false

reverses the direction of scrolling and layout.
horizontalAlignment: Alignment.Horizontal = Alignment.Start

aligns items horizontally.
verticalArrangement: Arrangement.Vertical = Arrangement.Top

is arrangement for items. This only applies if the content is smaller than the viewport.
content: ListScope.() -> Unit

a block which describes the content. Inside this block you can use methods like ListScope.item to add a single item or ListScope.items to add a list of items.

rememberListState

@Composable
fun rememberListState(
    initialFirstVisibleItemIndex: Int = 0,
    initialFirstVisibleItemScrollOffset: Int = 0
): ListState

Creates a ListState that is remembered across compositions.

Changes to the provided initial values will not result in the state being recreated or changed in any way if it has already been created.

Parameters
initialFirstVisibleItemIndex: Int = 0

the initial value for ListState.firstVisibleItemIndex
initialFirstVisibleItemScrollOffset: Int = 0

the initial value for ListState.firstVisibleItemScrollOffset

rememberSnapFlingBehavior

@Composable
fun rememberSnapFlingBehavior(state: ListState): FlingBehavior

Creates and remembers a focus-aware fling behavior that aligns the focus line with the center of the element expected to gain focus at the end of the fling. This ensures predictable movement for users.

Parameters
state: ListState

The ListState to observe for layout and focus information.
Returns
FlingBehavior

A FlingBehavior instance that provides focus-aware snapping.

Extension functions

items

inline fun <T : Any?> ListScope.items(
    items: List<T>,
    noinline key: ((item) -> Any)? = null,
    noinline contentType: (item) -> Any? = { null },
    crossinline itemContent: @Composable ListItemScope.(item) -> Unit
): Unit

Adds a list of items.

Parameters
items: List<T>

the data list
noinline key: ((item) -> Any)? = null

a factory of stable and unique keys representing the item. Using the same key for multiple items in the list is not allowed. Type of the key should be saveable via Bundle on Android. If null is passed the position in the list will represent the key. When you specify the key the scroll position will be maintained based on the key, which means if you add/remove items before the current visible item the item with the given key will be kept as the first visible one. This can be overridden by calling 'requestScrollToItem' on the 'ListState'.
noinline contentType: (item) -> Any? = { null }

a factory of the content types for the item. The item compositions of the same type could be reused more efficiently. Note that null is a valid type and items of such type will be considered compatible.
crossinline itemContent: @Composable ListItemScope.(item) -> Unit

the content displayed by a single item

itemsIndexed

inline fun <T : Any?> ListScope.itemsIndexed(
    items: List<T>,
    noinline key: ((index: Int, item) -> Any)? = null,
    crossinline contentType: (index: Int, item) -> Any? = { _, _ -> null },
    crossinline itemContent: @Composable ListItemScope.(index: Int, item) -> Unit
): Unit

Adds a list of items where the content of an item is aware of its index.

Parameters
items: List<T>

the data list
noinline key: ((index: Int, item) -> Any)? = null

a factory of stable and unique keys representing the item. Using the same key for multiple items in the list is not allowed. Type of the key should be saveable via Bundle on Android. If null is passed the position in the list will represent the key. When you specify the key the scroll position will be maintained based on the key, which means if you add/remove items before the current visible item the item with the given key will be kept as the first visible one. This can be overridden by calling 'requestScrollToItem' on the 'ListState'.
crossinline contentType: (index: Int, item) -> Any? = { _, _ -> null }

a factory of the content types for the item. The item compositions of the same type could be reused more efficiently. Note that null is a valid type and items of such type will be considered compatible.
crossinline itemContent: @Composable ListItemScope.(index: Int, item) -> Unit

the content displayed by a single item