pointerInput

Compose Modifier

Common

Deprecated PointerInputModifierNoParamError

fun Modifier.pointerInput(block: suspend PointerInputScope.() -> Unit): Modifier

Create a modifier for processing pointer input within the region of the modified element.

It is an error to call pointerInput without at least one key parameter.

Common

Deprecated This function is deprecated. Use the PointerInputEventHandler block variation instead

fun Modifier.pointerInput(key1: Any?, block: suspend PointerInputScope.() -> Unit): Modifier

Common

fun Modifier.pointerInput(key1: Any?, block: PointerInputEventHandler): Modifier

Create a modifier for processing pointer input within the region of the modified element.

pointerInput blocks may call PointerInputScope.awaitPointerEventScope to install a pointer input handler that can AwaitPointerEventScope.awaitPointerEvent to receive and consume pointer input events. Extension functions on PointerInputScope or AwaitPointerEventScope may be defined to perform higher-level gesture detection. The pointer input handling block will be cancelled and re-started when pointerInput is recomposed with a different key1 or the block class is different.

When a pointerInput modifier is created by composition, if block captures any local variables to operate on, two patterns are common for working with changes to those variables depending on the desired behavior.

Specifying the captured value as a key parameter will cause block to cancel and restart from the beginning if the value changes:

If block should not restart when a captured value is changed but the value should still be updated for its next use, use rememberUpdatedState to update a value holder that is accessed by block:

Note Any removal operations on Android Views from pointerInput should wrap the block in a post { } block to guarantee the event dispatch completes before executing the removal. (You do not need to do this when removing a composable because Compose guarantees it completes via the snapshot state system.)

Common

Deprecated This function is deprecated. Use the PointerInputEventHandler block variation instead

fun Modifier.pointerInput(
    key1: Any?,
    key2: Any?,
    block: suspend PointerInputScope.() -> Unit,
): Modifier

Common

fun Modifier.pointerInput(key1: Any?, key2: Any?, block: PointerInputEventHandler): Modifier

Create a modifier for processing pointer input within the region of the modified element.

Specifying the captured value as a key parameter will cause block to cancel and restart from the beginning if the value changes:

Common

Deprecated This function is deprecated. Use the PointerInputEventHandler block variation instead

fun Modifier.pointerInput(
    vararg keys: Any?,
    block: suspend PointerInputScope.() -> Unit,
): Modifier

Common

fun Modifier.pointerInput(vararg keys: Any?, block: PointerInputEventHandler): Modifier

Create a modifier for processing pointer input within the region of the modified element.

pointerInput blocks may call PointerInputScope.awaitPointerEventScope to install a pointer input handler that can AwaitPointerEventScope.awaitPointerEvent to receive and consume pointer input events. Extension functions on PointerInputScope or AwaitPointerEventScope may be defined to perform higher-level gesture detection. The pointer input handling block will be cancelled and re-started when pointerInput is recomposed with any different keys or the block class is different.

Specifying the captured value as a key parameter will cause block to cancel and restart from the beginning if the value changes:

Code Examples

keyedPointerInputModifier

fun keyedPointerInputModifier() {
    @Composable
    fun MyComposable(parameter: String) {
        Box(
            Modifier.fillMaxSize().pointerInput(parameter) {
                // This entire pointerInput block will restart from the beginning
                // if and when `parameter` changes, since it's used as a key in
                // the creation of the `pointerInput` modifier
                detectTapGestures { performAction(parameter) }
            }
        )
    }
}

rememberedUpdatedParameterPointerInputModifier

fun rememberedUpdatedParameterPointerInputModifier() {
    @Composable
    fun MyComposable(parameter: String) {
        val currentParameter by rememberUpdatedState(parameter)
        Box(
            Modifier.fillMaxSize().pointerInput(Unit) {
                // This pointerInput block will never restart since
                // it specifies a key of `Unit`, which never changes
                detectTapGestures {
                    // ...however, currentParameter is updated out from under this running
                    // pointerInput suspend block by rememberUpdatedState, and will always
                    // contain the latest value updated by the composition when a tap
                    // is detected here.
                    performAction(currentParameter)
                }
            }
        )
    }
}