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 buttons. All buttons will be released as a result. A trackpad cancel event can only be sent when 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.

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.

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 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 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 panEnd(delayMillis: Long = eventPeriodMillis): Unit

Ends a pan gesture. The androidx.compose.ui.input.pointer.PointerEventType.PanEnd will be sent at the current event time.

The helper function pan allows combining these calls into a single call, to pan by a given offset sending the appropriate event in sequence.

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

Updates the ongoing pan gesture, by applying the given delta as part of the pan. The androidx.compose.ui.input.pointer.PointerEventType.PanMove will be sent at the current event time.

The helper function pan allows combining these calls into a single call, to pan by a given offset sending the appropriate event in sequence.

fun panStart(): Unit

Starts a pan gesture. The androidx.compose.ui.input.pointer.PointerEventType.PanStart will be sent at the current event time. This should be followed by any number of calls to panMoveBy, followed by panEnd.

The helper function pan allows combining these calls into a single call, to pan by a given offset sending the appropriate event in sequence.

fun press(button: TrackpadButton = TrackpadButton.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 button events.

fun release(button: TrackpadButton = TrackpadButton.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 button events.

fun scaleChangeBy(
    scaleFactor: @FloatRange(from = 0.0, fromInclusive = false) Float,
    delayMillis: Long = eventPeriodMillis
): Unit

Updates the ongoing scale gesture, by applying the given multiplicative scaleFactor as part of the gesture. The androidx.compose.ui.input.pointer.PointerEventType.ScaleChange will be sent at the current event time.

The helper function scale allows combining these calls into a single call, to scale by a given factor sending the appropriate events in sequence.

fun scaleEnd(delayMillis: Long = eventPeriodMillis): Unit

Ends a scale gesture. The androidx.compose.ui.input.pointer.PointerEventType.ScaleEnd will be sent at the current event time.

The helper function scale allows combining these calls into a single call, to scale by a given factor sending the appropriate events in sequence.

fun scaleStart(): Unit

Starts a scale gesture. The androidx.compose.ui.input.pointer.PointerEventType.ScaleStart will be sent at the current event time. This should be followed by any number of calls to scaleChangeBy, followed by scaleEnd.

The helper function scale allows combining these calls into a single call, to scale by a given factor sending the appropriate events in sequence.

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: TrackpadButton = TrackpadButton.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: TrackpadButton = TrackpadButton.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: TrackpadButton = TrackpadButton.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: TrackpadButton = TrackpadButton.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.pan(offset: Offset): Unit

Sends a pan gesture with the given total offset. The event will be sent starting at the current event time.

To send a pan gesture with a curve, use pan(curve, durationMillis, keyTimes).

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

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

fun TrackpadInjectionScope.pan(
    curve: (timeMillis: Long) -> Offset,
    durationMillis: Long = 200,
    keyTimes: List<Long> = emptyList()
): Unit

Sends a pan gesture with the offsets in the panning coordinate space following the given curve. It is expected that the curve starts at Offset.Zero, as a pan gesture starts with no delta, and then move outward from the origin.

To send a pan with just a single amount, use pan(offset).

fun TrackpadInjectionScope.panWithVelocity(
    offset: Offset,
    endVelocity: @FloatRange(from = 0.0) Float,
    durationMillis: Long = VelocityPathFinder.calculateDefaultDuration(Offset.Zero, offset, endVelocity)
): Unit

Performs a pan gesture on the associated node such that it ends with the given endVelocity.

The pan will go from Offset.Zero at t=0 to offset at t=durationMillis. In between, the pan will go monotonically from Offset.Zero and offset, but not strictly. Due to imprecision, no guarantees can be made for the actual velocity at the end of the gesture, but generally it is within 0.1 of the desired velocity.

When a pan cannot be created that results in the desired velocity (because the input is too restrictive), an exception will be thrown with suggestions to fix the input.

The coordinates are in the pan coordinate system, which has the same scale as the display in pixel coordinates, where Offset.Zero indicates no panning.

Use pan(curve, duration, durationMillis) to directly control the curve of the pan.

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

Secondary-click on position, or on the current cursor position if position is unspecified. While the secondary button is not necessarily a physical right button (e.g. a multi-finger tap), 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.scale(
    scaleFactor: @FloatRange(from = 0.0, fromInclusive = false) Float
): Unit

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

The scaleFactor is a multiplicative zoom factor. A scaleFactor of 1 represents no change. A scaleFactor less than 1 represents a "zoom out" gesture, while a factor of more than one represents a "zoom in" gesture.

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

composeTestRule.onNodeWithTag("transformable").performTrackpadInput {
    // Performs a scale with a factor of 0.9f, which corresponds to a "zoom out" gesture.
    scale(0.9f)
}

fun TrackpadInjectionScope.tripleClick(
    position: Offset = center,
    button: TrackpadButton = TrackpadButton.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.