androidx.compose.ui.input.pointer

fun PointerIcon(pointerIcon: PointerIcon): PointerIcon

Creates PointerIcon from android.view.PointerIcon

fun PointerIcon(pointerIconType: Int): PointerIcon

Creates PointerIcon from pointer icon type (see android.view.PointerIcon.getSystemIcon

fun SuspendingPointerInputModifierNode(
    pointerInputEventHandler: PointerInputEventHandler
): SuspendingPointerInputModifierNode

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.

fun PointerInputChange.anyChangeConsumed(): Boolean

True if any aspect of this PointerInputChange has been consumed.

fun PointerInputChange.changedToDown(): Boolean

True if this PointerInputChange represents a pointer coming in contact with the screen and that change has not been consumed.

fun PointerInputChange.changedToDownIgnoreConsumed(): Boolean

True if this PointerInputChange represents a pointer coming in contact with the screen, whether or not that change has been consumed.

fun PointerInputChange.changedToUp(): Boolean

True if this PointerInputChange represents a pointer breaking contact with the screen and that change has not been consumed.

fun PointerInputChange.changedToUpIgnoreConsumed(): Boolean

True if this PointerInputChange represents a pointer breaking contact with the screen, whether or not that change has been consumed.

fun PointerInputChange.consumeAllChanges(): Unit

Consumes all changes associated with the PointerInputChange

fun PointerInputChange.consumeDownChange(): Unit

Consume the up or down change of this PointerInputChange if there is an up or down change to consume.

fun PointerInputChange.consumePositionChange(): Unit

Consume position change if there is any

fun PointerButtons.indexOfFirstPressed(): Int

Returns the index of first button pressed as used in isPressed or -1 if no button is pressed.

fun PointerButtons.indexOfLastPressed(): Int

Returns the index of last button pressed as used in isPressed or -1 if no button is pressed.

fun PointerInputChange.isOutOfBounds(size: IntSize): Boolean

Returns true if the pointer has moved outside of the region of (0, 0, size.width, size.height) or false if the current pointer is up or it is inside the given bounds.

fun PointerInputChange.isOutOfBounds(
    size: IntSize,
    extendedTouchPadding: Size
): Boolean

Returns true if the pointer has moved outside of the pointer region. For Touch events, this is (-extendedTouchPadding.width, -extendedTouchPadding.height, size.width + extendedTouchPadding.width, size.height + extendedTouchPadding.height) and for other events, this is (0, 0, size.width, size.height). Returnsfalse if the current pointer is up or it is inside the pointer region.

fun PointerButtons.isPressed(buttonIndex: Int): Boolean

Returns true when the button at buttonIndex is pressed and false when it isn't pressed. This method can handle buttons that haven't been assigned a designated purpose like isPrimaryPressed and isSecondaryPressed.

fun Modifier.motionEventSpy(watcher: (motionEvent: MotionEvent) -> Unit): Modifier

Calls watcher with each MotionEvent that the layout area or any child pointerInput receives. The MotionEvent may or may not have been transformed to the local coordinate system. The Compose View will be considered as handling the MotionEvent in the area that the motionEventSpy is active.

This method can only be used to observe MotionEvents and can not be used to capture an event stream.

watcher is called during the PointerEventPass.Initial pass.

Developers should use pointerInput to handle pointer input processing within Compose. motionEventSpy is only useful as part of Android View interoperability.

If you need to handle and consume MotionEvents, use pointerInteropFilter.

fun Modifier.pointerHoverIcon(
    icon: PointerIcon,
    overrideDescendants: Boolean = false
): Modifier

Modifier that lets a developer define a pointer icon to display when the cursor is hovered over the element. When overrideDescendants is set to true, descendants cannot override the pointer icon using this modifier.

import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.text.selection.SelectionContainer
import androidx.compose.material.Text
import androidx.compose.ui.Modifier
import androidx.compose.ui.input.pointer.PointerIcon
import androidx.compose.ui.input.pointer.pointerHoverIcon

Column(Modifier.pointerHoverIcon(PointerIcon.Crosshair)) {
    SelectionContainer {
        Column {
            Text("Selectable text")
            Text(
                modifier = Modifier.pointerHoverIcon(PointerIcon.Hand, true),
                text = "Selectable text with hand"
            )
        }
    }
    Text("Just text with global pointerIcon")
}

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.

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

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 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:

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

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

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

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 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:

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

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

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

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, 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:

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

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

fun Modifier.pointerInteropFilter(
    requestDisallowInterceptTouchEvent: RequestDisallowInterceptTouchEvent? = null,
    onTouchEvent: (MotionEvent) -> Boolean
): Modifier

A special PointerInputModifier that provides access to the underlying MotionEvents originally dispatched to Compose. Prefer pointerInput and use this only for interoperation with existing code that consumes MotionEvents.

While the main intent of this Modifier is to allow arbitrary code to access the original MotionEvent dispatched to Compose, for completeness, analogs are provided to allow arbitrary code to interact with the system as if it were an Android View.

This includes 2 APIs,

1. onTouchEvent has a Boolean return type which is akin to the return type of View.onTouchEvent. If the provided onTouchEvent returns true, it will continue to receive the event stream (unless the event stream has been intercepted) and if it returns false, it will not.

2. requestDisallowInterceptTouchEvent is a lambda that you can optionally provide so that you can later call it (yes, in this case, you call the lambda that you provided) which is akin to calling ViewParent.requestDisallowInterceptTouchEvent. When this is called, any associated ancestors in the tree that abide by the contract will act accordingly and will not intercept the even stream.

fun PointerInputChange.positionChange(): Offset

The distance that the pointer has moved on the screen minus any distance that has been consumed.

fun PointerInputChange.positionChangeConsumed(): Boolean

True if this PointerInputChange's movement has been consumed.

fun PointerInputChange.positionChangeIgnoreConsumed(): Offset

The distance that the pointer has moved on the screen, ignoring the fact that it might have been consumed.

fun PointerInputChange.positionChanged(): Boolean

True if this PointerInputChange represents a pointer moving on the screen and some of that movement has not been consumed.

fun PointerInputChange.positionChangedIgnoreConsumed(): Boolean

True if this PointerInputChange represents a pointer moving on the screen ignoring how much of that movement may have been consumed.

fun Modifier.stylusHoverIcon(
    icon: PointerIcon,
    overrideDescendants: Boolean = false,
    touchBoundsExpansion: DpTouchBoundsExpansion? = null
): Modifier

Modifier that lets a developer define a pointer icon to display when a stylus is hovered over the element. When overrideDescendants is set to true, descendants cannot override the pointer icon using this modifier.

import androidx.compose.foundation.BorderStroke
import androidx.compose.foundation.border
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.padding
import androidx.compose.foundation.layout.requiredSize
import androidx.compose.material.Text
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.graphics.SolidColor
import androidx.compose.ui.input.pointer.PointerIcon
import androidx.compose.ui.input.pointer.stylusHoverIcon
import androidx.compose.ui.unit.dp

Box(
    Modifier.requiredSize(200.dp)
        .border(BorderStroke(2.dp, SolidColor(Color.Red)))
        .stylusHoverIcon(PointerIcon.Crosshair)
) {
    Text(text = "crosshair icon")
    Box(
        Modifier.padding(20.dp)
            .requiredSize(150.dp)
            .border(BorderStroke(2.dp, SolidColor(Color.Black)))
            .stylusHoverIcon(PointerIcon.Text)
    ) {
        Text(text = "text icon")
        Box(
            Modifier.padding(40.dp)
                .requiredSize(100.dp)
                .border(BorderStroke(2.dp, SolidColor(Color.Blue)))
                .stylusHoverIcon(PointerIcon.Hand)
        ) {
            Text(text = "hand icon")
        }
    }
}

val PointerButtons.areAnyPressed: Boolean

Returns true if any button is pressed or false if all buttons are released.

val PointerKeyboardModifiers.isAltGraphPressed: Boolean

true when the AltGraph key is pressed.

val PointerKeyboardModifiers.isAltPressed: Boolean

true when the Alt key is pressed. This is commonly associated with the Option key on some keyboards.

val PointerButtons.isBackPressed: Boolean

true when the back button (mouse back button) is pressed or false when it isn't pressed or there is no mouse button assigned to "back."

val PointerKeyboardModifiers.isCapsLockOn: Boolean

true when the keyboard's Caps Lock is on.

val PointerKeyboardModifiers.isCtrlPressed: Boolean

true when the Control key is pressed.

val PointerButtons.isForwardPressed: Boolean

true when the forward button (mouse forward button) is pressed or false when it isn't pressed or there is no button assigned to "forward."

val PointerKeyboardModifiers.isFunctionPressed: Boolean

true when the Function key is pressed.

val PointerKeyboardModifiers.isMetaPressed: Boolean

true when the Meta key is pressed. This is commonly associated with the Windows or Command key on some keyboards.

val PointerKeyboardModifiers.isNumLockOn: Boolean

true when the keyboard's Num Lock is on.

val PointerButtons.isPrimaryPressed: Boolean

true when the primary button (left mouse button) is pressed or false when it isn't pressed.

val PointerKeyboardModifiers.isScrollLockOn: Boolean

true when the keyboard's Scroll Lock is on.

val PointerButtons.isSecondaryPressed: Boolean

true when the secondary button (right mouse button) is pressed or false when it isn't pressed.

val PointerKeyboardModifiers.isShiftPressed: Boolean

true when the Shift key is pressed.

val PointerKeyboardModifiers.isSymPressed: Boolean

true when the Sym key is pressed.

val PointerButtons.isTertiaryPressed: Boolean

true when the tertiary button (middle mouse button) is pressed or false when it isn't pressed.