ScreenScaffold

Component in Wear Material 3 Compose

[ScreenScaffold] is one of the Wear Material3 scaffold components.

The scaffold components [AppScaffold] and [ScreenScaffold] lay out the structure of a screen and coordinate transitions of the [ScrollIndicator] and [TimeText] components.

[ScreenScaffold] displays the [ScrollIndicator] at the center-end of the screen by default and coordinates showing/hiding [TimeText] and [ScrollIndicator] according to [scrollState].

This version of [ScreenScaffold] has a special slot for a button at the bottom, that grows and shrinks to take the available space after the scrollable content.

Last updated: 2024-09-07 14:23

Installation

dependencies {
   implementation("androidx.wear.compose:compose-material3:1.0.0-alpha24")
}

Overloads

@Composable
fun ScreenScaffold(
    scrollState: ScalingLazyListState,
    modifier: Modifier = Modifier,
    timeText: (@Composable () -> Unit)? = null,
    scrollIndicator: (@Composable BoxScope.() -> Unit)? = {
        ScrollIndicator(scrollState, modifier = Modifier.align(Alignment.CenterEnd))
    },
    bottomButton: (@Composable BoxScope.() -> Unit)? = null,
    content: @Composable BoxScope.() -> Unit,
)

Parameters

name	description
scrollState	The scroll state for [ScalingLazyColumn], used to drive screen transitions such as [TimeText] scroll away and showing/hiding [ScrollIndicator].
modifier	The modifier for the screen scaffold.
timeText	Time text (both time and potentially status message) for this screen, if different to the time text at the [AppScaffold] level. When null, the time text from the [AppScaffold] is displayed for this screen.
scrollIndicator	The [ScrollIndicator] to display on this screen, which is expected to be aligned to Center-End. It is recommended to use the Material3 [ScrollIndicator] which is provided by default. No scroll indicator is displayed if null is passed.
bottomButton	Optional slot for a Button (usually an [EdgeButton]) that takes the available space below a scrolling list. It will scale up and fade in when the user scrolls to the end of the list, and scale down and fade out as the user scrolls up.
content	The body content for this screen.

@Composable
fun ScreenScaffold(
    scrollState: LazyListState,
    modifier: Modifier = Modifier,
    scrollIndicator: @Composable BoxScope.() -> Unit = {
        ScrollIndicator(scrollState, modifier = Modifier.align(Alignment.CenterEnd))
    },
    timeText: (@Composable () -> Unit)? = null,
    bottomButton: (@Composable BoxScope.() -> Unit)? = null,
    content: @Composable BoxScope.() -> Unit,
)

Parameters

name	description
scrollState	The scroll state for LazyColumn, used to drive screen transitions such as [TimeText] scroll away and showing/hiding [ScrollIndicator].
modifier	The modifier for the screen scaffold.
timeText	Time text (both time and potentially status message) for this screen, if different to the time text at the [AppScaffold] level. When null, the time text from the [AppScaffold] is displayed for this screen.
scrollIndicator	The [ScrollIndicator] to display on this screen, which is expected to be aligned to Center-End. It is recommended to use the Material3 [ScrollIndicator] which is provided by default. No scroll indicator is displayed if null is passed.
bottomButton	Optional slot for a Button (usually an [EdgeButton]) that takes the available space below a scrolling list. It will scale up and fade in when the user scrolls to the end of the list, and scale down and fade out as the user scrolls up.
content	The body content for this screen.

@Composable
fun ScreenScaffold(
    scrollState: ScrollState,
    bottomButton: @Composable BoxScope.() -> Unit,
    bottomButtonHeight: Dp,
    modifier: Modifier = Modifier,
    timeText: (@Composable () -> Unit)? = null,
    scrollIndicator: (@Composable BoxScope.() -> Unit)? = {
        ScrollIndicator(scrollState, modifier = Modifier.align(Alignment.CenterEnd))
    },
    content: @Composable BoxScope.() -> Unit,
)

Parameters

name	description
scrollState	The scroll state for a Column, used to drive screen transitions such as [TimeText] scroll away and showing/hiding [ScrollIndicator].
bottomButton	Optional slot for a Button (usually an [EdgeButton]) that takes the available space below a scrolling list. It will scale up and fade in when the user scrolls to the end of the list, and scale down and fade out as the user scrolls up.
bottomButtonHeight	the maximum height of the space taken by the bottom button.
modifier	The modifier for the screen scaffold.
timeText	Time text (both time and potentially status message) for this screen, if different to the time text at the [AppScaffold] level. When null, the time text from the [AppScaffold] is displayed for this screen.
scrollIndicator	The [ScrollIndicator] to display on this screen, which is expected to be aligned to Center-End. It is recommended to use the Material3 [ScrollIndicator] which is provided by default. No scroll indicator is displayed if null is passed.
content	The body content for this screen.

@Composable
fun ScreenScaffold(
    scrollState: ScrollState,
    modifier: Modifier = Modifier,
    timeText: (@Composable () -> Unit)? = null,
    scrollIndicator: (@Composable BoxScope.() -> Unit)? = {
        ScrollIndicator(scrollState, modifier = Modifier.align(Alignment.CenterEnd))
    },
    content: @Composable BoxScope.() -> Unit,
)

Parameters

name	description
scrollState	The scroll state for a Column, used to drive screen transitions such as [TimeText] scroll away and showing/hiding [ScrollIndicator].
modifier	The modifier for the screen scaffold.
timeText	Time text (both time and potentially status message) for this screen, if different to the time text at the [AppScaffold] level. When null, the time text from the [AppScaffold] is displayed for this screen.
scrollIndicator	The [ScrollIndicator] to display on this screen, which is expected to be aligned to Center-End. It is recommended to use the Material3 [ScrollIndicator] which is provided by default. No scroll indicator is displayed if null is passed.
content	The body content for this screen.

@Composable
fun ScreenScaffold(
    bottomButton: @Composable BoxScope.() -> Unit,
    scrollInfoProvider: ScrollInfoProvider,
    modifier: Modifier = Modifier,
    timeText: (@Composable () -> Unit)? = null,
    scrollIndicator: (@Composable BoxScope.() -> Unit)? = null,
    content: @Composable BoxScope.() -> Unit,
)

Parameters

name	description
bottomButton	slot for a Button (usually an [EdgeButton]) that takes the available space below a scrolling list. It will scale up and fade in when the user scrolls to the end of the list, and scale down and fade out as the user scrolls up.
scrollInfoProvider	Provider for scroll information used to scroll away screen elements such as [TimeText] and coordinate showing/hiding the [ScrollIndicator], this needs to be a [ScrollInfoProvider].
modifier	The modifier for the screen scaffold.
timeText	Time text (both time and potentially status message) for this screen, if different to the time text at the [AppScaffold] level. When null, the time text from the [AppScaffold] is displayed for this screen.
scrollIndicator	The [ScrollIndicator] to display on this screen, which is expected to be aligned to Center-End. It is recommended to use the Material3 [ScrollIndicator] which is provided by default. No scroll indicator is displayed if null is passed.
content	The body content for this screen.

@Composable
fun ScreenScaffold(
    modifier: Modifier = Modifier,
    timeText: (@Composable () -> Unit)? = null,
    scrollInfoProvider: ScrollInfoProvider? = null,
    scrollIndicator: (@Composable BoxScope.() -> Unit)? = null,
    content: @Composable BoxScope.() -> Unit,
)

Parameters

name	description
modifier	The modifier for the screen scaffold.
timeText	Time text (both time and potentially status message) for this screen, if different to the time text at the [AppScaffold] level. When null, the time text from the [AppScaffold] is displayed for this screen.
scrollInfoProvider	Provider for scroll information used to scroll away screen elements such as [TimeText] and coordinate showing/hiding the [ScrollIndicator].
scrollIndicator	The [ScrollIndicator] to display on this screen, which is expected to be aligned to Center-End. It is recommended to use the Material3 [ScrollIndicator] which is provided by default. No scroll indicator is displayed if null is passed.
content	The body content for this screen.

Code Example

ScaffoldSample

@Composable
fun ScaffoldSample() {
    // Declare just one [AppScaffold] per app such as in the activity.
    // [AppScaffold] allows static screen elements (i.e. [TimeText]) to remain visible
    // during in-app transitions such as swipe-to-dismiss.
    AppScaffold {
        // Define the navigation hierarchy within the AppScaffold,
        // such as using SwipeDismissableNavHost.
        // For this sample, we will define a single screen inline.
        val listState = rememberScalingLazyListState()

        // By default, ScreenScaffold will handle transitions showing/hiding ScrollIndicator
        // and showing/hiding/scrolling away TimeText.
        ScreenScaffold(scrollState = listState) {
            ScalingLazyColumn(state = listState, modifier = Modifier.fillMaxSize()) {
                items(10) {
                    Button(
                        onClick = {},
                        label = { Text("Item ${it + 1}") },
                    )
                }
            }
        }
    }
}