androidx.compose.ui.input.rotary

Interfaces

RotaryInputModifierNode

Implement this interface to create a Modifier.Node that can intercept rotary scroll events.
Cmn

Classes

RotaryScrollEvent

This event represents a rotary input event.
Cmn
android

Extension functions summary

Modifier
Modifier.onPreRotaryScrollEvent(
    onPreRotaryScrollEvent: (RotaryScrollEvent) -> Boolean
)

Adding this modifier to the modifier parameter of a component will allow it to intercept RotaryScrollEvents if it (or one of its children) is focused.
Cmn
Modifier
Modifier.onRotaryScrollEvent(
    onRotaryScrollEvent: (RotaryScrollEvent) -> Boolean
)

Adding this modifier to the modifier parameter of a component will allow it to intercept RotaryScrollEvents if it (or one of its children) is focused.
Cmn

Extension functions

onPreRotaryScrollEvent

Cmn 
fun Modifier.onPreRotaryScrollEvent(
    onPreRotaryScrollEvent: (RotaryScrollEvent) -> Boolean
): Modifier

Adding this modifier to the modifier parameter of a component will allow it to intercept RotaryScrollEvents if it (or one of its children) is focused.

import androidx.compose.foundation.focusable
import androidx.compose.foundation.gestures.scrollBy
import androidx.compose.foundation.horizontalScroll
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.verticalScroll
import androidx.compose.material.MaterialTheme
import androidx.compose.material.Switch
import androidx.compose.material.Text
import androidx.compose.material.darkColors
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.ui.Alignment.Companion.CenterHorizontally
import androidx.compose.ui.Alignment.Companion.CenterVertically
import androidx.compose.ui.Modifier
import androidx.compose.ui.focus.FocusRequester
import androidx.compose.ui.focus.focusRequester
import androidx.compose.ui.graphics.Color.Companion.White
import androidx.compose.ui.input.rotary.onPreRotaryScrollEvent
import androidx.compose.ui.input.rotary.onRotaryScrollEvent
import androidx.compose.ui.text.TextStyle
import androidx.compose.ui.unit.dp

MaterialTheme(colors = darkColors()) {
    val rowScrollState = rememberScrollState()
    val columnScrollState = rememberScrollState()
    val coroutineScope = rememberCoroutineScope()
    val focusRequester = remember { FocusRequester() }
    var interceptScroll by remember { mutableStateOf(false) }
    Column(
        Modifier.onPreRotaryScrollEvent {
                // You can intercept an event before it is sent to the child.
                if (interceptScroll) {
                    coroutineScope.launch { rowScrollState.scrollBy(it.horizontalScrollPixels) }
                    // return true to consume this event.
                    true
                } else {
                    // return false to ignore this event and continue propagation to the child.
                    false
                }
            }
            .onRotaryScrollEvent {
                // If the child does not use the scroll, we get notified here.
                coroutineScope.launch { rowScrollState.scrollBy(it.horizontalScrollPixels) }
                true
            }
    ) {
        Row(
            modifier = Modifier.align(CenterHorizontally),
            verticalAlignment = CenterVertically
        ) {
            Text(
                modifier = Modifier.width(70.dp),
                text = if (interceptScroll) "Row" else "Column",
                style = TextStyle(color = White)
            )
            Switch(
                checked = interceptScroll,
                onCheckedChange = { interceptScroll = it },
            )
        }
        Row(modifier = Modifier.fillMaxWidth().horizontalScroll(rowScrollState)) {
            repeat(100) {
                Text(
                    text = "row item $it ",
                    modifier = Modifier.align(CenterVertically),
                    color = White,
                )
            }
        }
        Column(
            modifier =
                Modifier.fillMaxWidth()
                    .verticalScroll(columnScrollState)
                    .onRotaryScrollEvent {
                        coroutineScope.launch {
                            columnScrollState.scrollBy(it.verticalScrollPixels)
                        }
                        true
                    }
                    .focusRequester(focusRequester)
                    .focusable(),
        ) {
            repeat(100) {
                Text(
                    text = "column item $it",
                    modifier = Modifier.align(CenterHorizontally),
                    color = White,
                )
            }
        }
    }

    LaunchedEffect(Unit) { focusRequester.requestFocus() }
}
Parameters
onPreRotaryScrollEvent: (RotaryScrollEvent) -> Boolean

This callback is invoked when the user interacts with the rotary button on a wear device. It gives ancestors of a focused component the chance to intercept a RotaryScrollEvent.

When the user rotates the side button on a wear device, a RotaryScrollEvent is sent to the focused item. Before reaching the focused item, this event starts at the root composable, and propagates down the hierarchy towards the focused item. It invokes any onPreRotaryScrollEvents it encounters on ancestors of the focused item. After reaching the focused item, the event propagates up the hierarchy back towards the parent. It invokes any onRotaryScrollEvents it encounters on its way back.

Return true to indicate that you consumed the event and want to stop propagation of this event.
Returns
Modifier

true if the event is consumed, false otherwise.

onRotaryScrollEvent

Cmn 
fun Modifier.onRotaryScrollEvent(
    onRotaryScrollEvent: (RotaryScrollEvent) -> Boolean
): Modifier

Adding this modifier to the modifier parameter of a component will allow it to intercept RotaryScrollEvents if it (or one of its children) is focused.

import androidx.compose.foundation.focusable
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.verticalScroll
import androidx.compose.material.Text
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.ui.Alignment.Companion.CenterHorizontally
import androidx.compose.ui.Modifier
import androidx.compose.ui.focus.FocusRequester
import androidx.compose.ui.focus.focusRequester
import androidx.compose.ui.graphics.Color.Companion.White
import androidx.compose.ui.input.rotary.onRotaryScrollEvent

val scrollState = rememberScrollState()
val coroutineScope = rememberCoroutineScope()
val focusRequester = remember { FocusRequester() }
Column(
    modifier =
        Modifier.fillMaxWidth()
            .verticalScroll(scrollState)
            .onRotaryScrollEvent {
                coroutineScope.launch {
                    scrollState.scrollTo(
                        (scrollState.value + it.verticalScrollPixels).roundToInt()
                    )
                }
                true
            }
            .focusRequester(focusRequester)
            .focusable(),
) {
    repeat(100) {
        Text(
            text = "item $it",
            modifier = Modifier.align(CenterHorizontally),
            color = White,
        )
    }
}

LaunchedEffect(Unit) { focusRequester.requestFocus() }

This sample demonstrates how a parent can add an onRotaryScrollEvent modifier to gain access to a RotaryScrollEvent when a child does not consume it:

import androidx.compose.foundation.focusable
import androidx.compose.foundation.gestures.scrollBy
import androidx.compose.foundation.horizontalScroll
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Row
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.width
import androidx.compose.foundation.rememberScrollState
import androidx.compose.foundation.verticalScroll
import androidx.compose.material.MaterialTheme
import androidx.compose.material.Switch
import androidx.compose.material.Text
import androidx.compose.material.darkColors
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.ui.Alignment.Companion.CenterHorizontally
import androidx.compose.ui.Alignment.Companion.CenterVertically
import androidx.compose.ui.Modifier
import androidx.compose.ui.focus.FocusRequester
import androidx.compose.ui.focus.focusRequester
import androidx.compose.ui.graphics.Color.Companion.White
import androidx.compose.ui.input.rotary.onPreRotaryScrollEvent
import androidx.compose.ui.input.rotary.onRotaryScrollEvent
import androidx.compose.ui.text.TextStyle
import androidx.compose.ui.unit.dp

MaterialTheme(colors = darkColors()) {
    val rowScrollState = rememberScrollState()
    val columnScrollState = rememberScrollState()
    val coroutineScope = rememberCoroutineScope()
    val focusRequester = remember { FocusRequester() }
    var interceptScroll by remember { mutableStateOf(false) }
    Column(
        Modifier.onPreRotaryScrollEvent {
                // You can intercept an event before it is sent to the child.
                if (interceptScroll) {
                    coroutineScope.launch { rowScrollState.scrollBy(it.horizontalScrollPixels) }
                    // return true to consume this event.
                    true
                } else {
                    // return false to ignore this event and continue propagation to the child.
                    false
                }
            }
            .onRotaryScrollEvent {
                // If the child does not use the scroll, we get notified here.
                coroutineScope.launch { rowScrollState.scrollBy(it.horizontalScrollPixels) }
                true
            }
    ) {
        Row(
            modifier = Modifier.align(CenterHorizontally),
            verticalAlignment = CenterVertically
        ) {
            Text(
                modifier = Modifier.width(70.dp),
                text = if (interceptScroll) "Row" else "Column",
                style = TextStyle(color = White)
            )
            Switch(
                checked = interceptScroll,
                onCheckedChange = { interceptScroll = it },
            )
        }
        Row(modifier = Modifier.fillMaxWidth().horizontalScroll(rowScrollState)) {
            repeat(100) {
                Text(
                    text = "row item $it ",
                    modifier = Modifier.align(CenterVertically),
                    color = White,
                )
            }
        }
        Column(
            modifier =
                Modifier.fillMaxWidth()
                    .verticalScroll(columnScrollState)
                    .onRotaryScrollEvent {
                        coroutineScope.launch {
                            columnScrollState.scrollBy(it.verticalScrollPixels)
                        }
                        true
                    }
                    .focusRequester(focusRequester)
                    .focusable(),
        ) {
            repeat(100) {
                Text(
                    text = "column item $it",
                    modifier = Modifier.align(CenterHorizontally),
                    color = White,
                )
            }
        }
    }

    LaunchedEffect(Unit) { focusRequester.requestFocus() }
}
Parameters
onRotaryScrollEvent: (RotaryScrollEvent) -> Boolean

This callback is invoked when the user interacts with the rotary side button or the bezel on a wear device. While implementing this callback, return true to stop propagation of this event. If you return false, the event will be sent to this onRotaryScrollEvent's parent.
Returns
Modifier

true if the event is consumed, false otherwise.

Here is an example of a scrollable container that scrolls in response to RotaryScrollEvents.