TrackpadInjectionScope

fun cancel(delayMillis: Long = eventPeriodMillis): Unit

Sends a cancel event delayMillis after the last sent event to cancel a stream of trackpad events with pressed mouse buttons. All buttons will be released as a result. A trackpad cancel event can only be sent when mouse buttons are pressed.

fun enter(
    position: Offset = currentPosition,
    delayMillis: Long = eventPeriodMillis
): Unit

Sends a hover enter event at the given position, delayMillis after the last sent event, without sending a hover move event.

An IllegalStateException will be thrown when mouse buttons are down, or if the trackpad is already hovering.

The position is in the node's local coordinate system, where (0, 0) is the top left corner of the node.

Note: enter and exit events are already sent as a side effect of movement when necessary. Whether or not this is part of the contract of trackpad events is platform dependent, so it is highly discouraged to manually send enter or exit events. Only use this method for tests that need to make assertions about a component's state in between the enter/exit and move event.

fun exit(position: Offset = currentPosition, delayMillis: Long = eventPeriodMillis): Unit

Sends a hover exit event at the given position, delayMillis after the last sent event, without sending a hover move event.

An IllegalStateException will be thrown if the trackpad was not hovering.

The position is in the node's local coordinate system, where (0, 0) is the top left corner of the node.

Note: enter and exit events are already sent as a side effect of movement when necessary. Whether or not this is part of the contract of trackpad events is platform dependent, so it is highly discouraged to manually send enter or exit events. Only use this method for tests that need to make assertions about a component's state in between the enter/exit and move event.

open fun moveBy(delta: Offset, delayMillis: Long = eventPeriodMillis): Unit

Sends a move event delayMillis after the last sent event on the associated node, with the position of the trackpad moved by the given delta.

If no mouse buttons are pressed, a hover event will be sent instead of a move event. If the trackpad wasn't hovering yet, a hover enter event is sent as well.

fun moveTo(position: Offset, delayMillis: Long = eventPeriodMillis): Unit

Sends a move event delayMillis after the last sent event on the associated node, with the position of the trackpad updated to position. The position is in the node's local coordinate system, where (0, 0) is the top left corner of the node.

If no mouse buttons are pressed, a hover event will be sent instead of a move event. If the trackpad wasn't hovering yet, a hover enter event is sent as well.

fun pinch(scaleFactor: Float): Unit

Sends a pinch event with the given scaleFactor. The event will be sent at the current event time.

The scaleFactor is a multiplicative zoom factor. A scaleFactor of 1 represents no pinch movement. A scaleFactor less than 1 represents a pinch where the 2 fingers become closer together (often interpreted as a "zoom out" gesture), and a scaleFactor of more than 1 represents a pinch where the 2 fingers become farther apart (often interpreted as a "zoom in" gesture).

import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.performTrackpadInput

composeTestRule.onNodeWithTag("transformable").performTrackpadInput {
    // Performs a pinch with a factor of 0.9f, which corresponds to a pinch
    // with the fingers becoming closer together, which is commonly interpreted
    // as a "zoom out" gesture
    pinch(0.9f)
}

fun press(button: MouseButton = MouseButton.Primary): Unit

Sends a down and button pressed event for the given button on the associated node. When no buttons were down yet, this will exit hovering mode before the button is pressed. All events will be sent at the current event time. Trackpads behave similarly to mice, with platform interpreted gestures that send mouse button events, so this API takes the MouseButton to press.

Throws an IllegalStateException if the button is already pressed.

fun release(button: MouseButton = MouseButton.Primary): Unit

Sends a button released and up event for the given button on the associated node. If this was the last button to be released, the trackpad will enter hovering mode and send an accompanying trackpad move event after the button has been released. All events will be sent at the current event time. Trackpads behave similarly to mice, with platform interpreted gestures that send mouse button events, so this API takes the MouseButton to release.

Throws an IllegalStateException if the button is not pressed.

fun scroll(offset: Offset): Unit

Sends a scroll event with the given offset. The event will be sent at the current event time.

import androidx.compose.ui.geometry.Offset
import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.performTrackpadInput

composeTestRule.onNodeWithTag("verticalScrollable").performTrackpadInput {
    scroll(Offset(0f, 100f))
}

open fun updatePointerBy(delta: Offset): Unit

Updates the position of the trackpad by the given delta, but does not send a move or hover event. This can be useful to adjust the trackpad position before sending for example a press event.

fun updatePointerTo(position: Offset): Unit

Updates the position of the trackpad to the given position, but does not send a move or hover event. This can be useful to adjust the trackpad position before sending for example a press event. The position is in the node's local coordinate system, where (0.px, 0.px) is the top left corner of the node.

val currentPosition: Offset

Returns the current position of the cursor. The position is returned in the local coordinate system of the node with which we're interacting. (0, 0) is the top left corner of the node. If none of the move or updatePointer methods have been used yet, the trackpad's position will be (0, 0) in the Compose host's coordinate system, which will be -[topLeft] in the node's local coordinate system.

fun TrackpadInjectionScope.animateMoveAlong(
    curve: (timeMillis: Long) -> Offset,
    durationMillis: Long = DefaultTrackpadGestureDurationMillis
): Unit

Move the trackpad along the given curve, sending a stream of move events to get an animated path of durationMillis milliseconds. The trackpad will initially be moved to the start of the path, curve(0), if it is not already there. The positions defined by the curve are in the node's local coordinate system, where (0, 0) is the top left corner of the node.

Example of moving the trackpad along a curve:

import androidx.compose.ui.geometry.Offset
import androidx.compose.ui.test.animateMoveAlong
import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.performTrackpadInput

composeTestRule.onNodeWithTag("myComponent").performTrackpadInput {
    // Hover over the node, making a full circle with a radius of 100px
    val r = 100f
    animateMoveAlong(
        curve = {
            val angle = 2 * PI * it / 1000
            center + Offset(r * cos(angle).toFloat(), r * sin(angle).toFloat())
        },
        durationMillis = 1000L,
    )
}

fun TrackpadInjectionScope.animateMoveBy(
    delta: Offset,
    durationMillis: Long = DefaultTrackpadGestureDurationMillis
): Unit

Move the trackpad from the current position by the given delta, sending a stream of move events to get an animated path of durationMillis milliseconds.

fun TrackpadInjectionScope.animateMoveTo(
    position: Offset,
    durationMillis: Long = DefaultTrackpadGestureDurationMillis
): Unit

Move the trackpad from the current position to the given position, sending a stream of move events to get an animated path of durationMillis milliseconds. Move the trackpad to the desired start position if you want to start from a different position. The position is in the node's local coordinate system, where (0, 0) is the top left corner of the node.

Example of moving the trackpad along a line:

import androidx.compose.ui.test.animateMoveTo
import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.performTrackpadInput

composeTestRule.onNodeWithTag("myComponent").performTrackpadInput {
    // Hover over the node, making an X shape
    moveTo(topLeft)
    animateMoveTo(bottomRight)
    // Note that an actual user wouldn't be able to instantly
    // move from the bottom right to the top right
    advanceEventTime()
    moveTo(topRight)
    animateMoveTo(bottomLeft)
}

fun TrackpadInjectionScope.click(
    position: Offset = center,
    button: MouseButton = MouseButton.Primary
): Unit

Use button to click on position, or on the current cursor position if position is unspecified. The position is in the node's local coordinate system, where (0, 0) is the top left corner of the node. The default button is the primary button.

fun TrackpadInjectionScope.doubleClick(
    position: Offset = center,
    button: MouseButton = MouseButton.Primary
): Unit

Use button to double-click on position, or on the current trackpad position if position is unspecified. The position is in the node's local coordinate system, where (0, 0) is the top left corner of the node. The default button is the primary button.

fun TrackpadInjectionScope.dragAndDrop(
    start: Offset,
    end: Offset,
    button: MouseButton = MouseButton.Primary,
    durationMillis: Long = DefaultTrackpadGestureDurationMillis
): Unit

Use button to drag and drop something from start to end in durationMillis milliseconds. The trackpad position is updated to the start position before starting the gesture. The positions defined by the start and end are in the node's local coordinate system, where (0, 0) is the top left corner of the node.

fun TrackpadInjectionScope.longClick(
    position: Offset = center,
    button: MouseButton = MouseButton.Primary
): Unit

Use button to long-click on position, or on the current trackpad position if position is unspecified. The position is in the node's local coordinate system, where (0, 0) is the top left corner of the node. The default button is the primary button.

fun TrackpadInjectionScope.rightClick(position: Offset = center): Unit

Secondary-click on position, or on the current cursor position if position is unspecified. While the secondary mouse button is not necessarily the right mouse button (e.g. on left-handed mice), this method is still called rightClick for it's widespread use. The position is in the node's local coordinate system, where (0, 0) is the top left corner of the node.

fun TrackpadInjectionScope.tripleClick(
    position: Offset = center,
    button: MouseButton = MouseButton.Primary
): Unit

Use button to triple-click on position, or on the current trackpad position if position is unspecified. The position is in the node's local coordinate system, where (0, 0) is the top left corner of the node. The default button is the primary button.