{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

SuspendingPointerInputFilterKt

public final class SuspendingPointerInputFilterKt


Summary

Public methods

static final @NonNull SuspendingPointerInputModifierNode

Supports suspending pointer event handling.

static final @NonNull Modifier
pointerInput(
    @NonNull Modifier receiver,
    @ExtensionFunctionType @NonNull SuspendFunction1<@NonNull PointerInputScopeUnit> block
)

This method is deprecated. Modifier.pointerInput must provide one or more 'key' parameters that define the identity of the modifier and determine when its previous input processing coroutine should be cancelled and a new effect launched for the new key.

static final @NonNull Modifier
pointerInput(
    @NonNull Modifier receiver,
    Object key1,
    @ExtensionFunctionType @NonNull SuspendFunction1<@NonNull PointerInputScopeUnit> block
)

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

static final @NonNull Modifier
pointerInput(
    @NonNull Modifier receiver,
    Object keys,
    @ExtensionFunctionType @NonNull SuspendFunction1<@NonNull PointerInputScopeUnit> block
)

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

static final @NonNull Modifier
pointerInput(
    @NonNull Modifier receiver,
    Object key1,
    Object key2,
    @ExtensionFunctionType @NonNull SuspendFunction1<@NonNull PointerInputScopeUnit> block
)

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

Public methods

SuspendingPointerInputModifierNode

public static final @NonNull SuspendingPointerInputModifierNode SuspendingPointerInputModifierNode(
    @ExtensionFunctionType @NonNull SuspendFunction1<@NonNull PointerInputScopeUnit> pointerInputHandler
)

Supports suspending pointer event handling. This is used by pointerInput, so in most cases you should just use pointerInput for suspending pointer input. Creating a SuspendingPointerInputModifierNode should only be needed when you want to delegate to suspending pointer input as part of the implementation of a complex Modifier.Node.

pointerInput

public static final @NonNull Modifier pointerInput(
    @NonNull Modifier receiver,
    @ExtensionFunctionType @NonNull SuspendFunction1<@NonNull PointerInputScopeUnit> block
)

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.

pointerInput

public static final @NonNull Modifier pointerInput(
    @NonNull Modifier receiver,
    Object key1,
    @ExtensionFunctionType @NonNull SuspendFunction1<@NonNull PointerInputScopeUnit> block
)

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

pointerInputs 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.

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:

import androidx.compose.foundation.gestures.detectTapGestures
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.input.pointer.pointerInput

@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)
                }
            }
    )
}

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:

import androidx.compose.foundation.gestures.detectTapGestures
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.runtime.Composable
import androidx.compose.runtime.rememberUpdatedState
import androidx.compose.ui.Modifier
import androidx.compose.ui.input.pointer.pointerInput

@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)
                }
            }
    )
}

pointerInput

public static final @NonNull Modifier pointerInput(
    @NonNull Modifier receiver,
    Object keys,
    @ExtensionFunctionType @NonNull SuspendFunction1<@NonNull PointerInputScopeUnit> block
)

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

pointerInputs 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.

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:

import androidx.compose.foundation.gestures.detectTapGestures
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.input.pointer.pointerInput

@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)
                }
            }
    )
}

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:

import androidx.compose.foundation.gestures.detectTapGestures
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.runtime.Composable
import androidx.compose.runtime.rememberUpdatedState
import androidx.compose.ui.Modifier
import androidx.compose.ui.input.pointer.pointerInput

@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)
                }
            }
    )
}

pointerInput

public static final @NonNull Modifier pointerInput(
    @NonNull Modifier receiver,
    Object key1,
    Object key2,
    @ExtensionFunctionType @NonNull SuspendFunction1<@NonNull PointerInputScopeUnit> block
)

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

pointerInputs 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 key2.

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:

import androidx.compose.foundation.gestures.detectTapGestures
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.input.pointer.pointerInput

@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)
                }
            }
    )
}

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:

import androidx.compose.foundation.gestures.detectTapGestures
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.runtime.Composable
import androidx.compose.runtime.rememberUpdatedState
import androidx.compose.ui.Modifier
import androidx.compose.ui.input.pointer.pointerInput

@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)
                }
            }
    )
}