TouchInjectionScope

fun cancel(delayMillis: Long = eventPeriodMillis): Unit

Sends a cancel event delayMillis after the last sent event to cancel the current gesture. The cancel event contains the current position of all active pointers.

fun currentPosition(pointerId: Int = 0): Offset?

Returns the current position of the given pointerId. The default pointerId is 0. 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.

open fun down(position: Offset): Unit

Sends a down event for the default pointer at position on the associated node. The position is in the node's local coordinate system, where (0, 0) is the top left corner of the node. The default pointer has pointerId = 0.

If no pointers are down yet, this will start a new touch gesture. If a gesture is already in progress, this event is sent at the same timestamp as the last event. If the default pointer is already down, an IllegalArgumentException will be thrown.

fun down(pointerId: Int, position: Offset): Unit

Sends a down event for the pointer with the given pointerId at position on the associated node. The position is in the node's local coordinate system, where (0, 0) is the top left corner of the node.

If no pointers are down yet, this will start a new touch gesture. If a gesture is already in progress, this event is sent at the same timestamp as the last event. If the given pointer is already down, an IllegalArgumentException will be thrown.

fun move(delayMillis: Long = eventPeriodMillis): Unit

Sends a move event delayMillis after the last sent event without updating any of the pointer positions. This can be useful when batching movement of multiple pointers together, which can be done with updatePointerTo and updatePointerBy.

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 default pointer moved by the given delta. The default pointer has pointerId = 0.

If the pointer is not yet down, an IllegalArgumentException will be thrown.

open fun moveBy(pointerId: Int, 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 pointer with the given pointerId moved by the given delta.

If the pointer is not yet down, an IllegalArgumentException will be thrown.

open 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 default pointer updated to position. The position is in the node's local coordinate system, where (0, 0) is the top left corner of the node. The default pointer has pointerId = 0.

If the default pointer is not yet down, an IllegalArgumentException will be thrown.

open fun moveTo(
    pointerId: Int,
    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 pointer with the given pointerId 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 the pointer is not yet down, an IllegalArgumentException will be thrown.

@ExperimentalTestApi
open fun moveWithHistory(
    relativeHistoricalTimes: List<Long>,
    historicalCoordinates: List<Offset>,
    delayMillis: Long = eventPeriodMillis
): Unit

Sends a move event delayMillis after the last sent event without updating any of the pointer positions, while adding the historicalCoordinates at the relativeHistoricalTimes to the move event. This corresponds to the scenario where a touch screen generates touch events quicker than can be dispatched and batches them together.

This overload is a convenience method for the common case where the gesture only has one pointer.

@ExperimentalTestApi
fun moveWithHistoryMultiPointer(
    relativeHistoricalTimes: List<Long>,
    historicalCoordinates: List<List<Offset>>,
    delayMillis: Long = eventPeriodMillis
): Unit

Sends a move event delayMillis after the last sent event without updating any of the pointer positions, while adding the historicalCoordinates at the relativeHistoricalTimes to the move event. This corresponds to the scenario where a touch screen generates touch events quicker than can be dispatched and batches them together.

import androidx.compose.ui.geometry.Offset
import androidx.compose.ui.test.ExperimentalTestApi
import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.performTouchInput

// Move two fingers in a horizontal line, one on y=100 and one on y=500
composeTestRule.onNodeWithTag("myComponent").performTouchInput {
    // First, make contact with the screen with both pointers:
    down(0, Offset(300f, 100f))
    down(1, Offset(300f, 500f))
    // Update the pointer locations for the next event
    updatePointerTo(0, Offset(400f, 100f))
    updatePointerTo(1, Offset(400f, 500f))
    // And send the move event with historical data
    @OptIn(ExperimentalTestApi::class)
    moveWithHistoryMultiPointer(
        // Let's add 3 historical events
        relativeHistoricalTimes = listOf(-12, -8, -4),
        // Now, for each pointer we supply the historical coordinates
        historicalCoordinates =
            listOf(
                // Pointer 0 moves along y=100
                listOf(Offset(325f, 100f), Offset(350f, 100f), Offset(375f, 100f)),
                // Pointer 1 moves along y=500
                listOf(Offset(325f, 500f), Offset(350f, 500f), Offset(375f, 500f)),
            ),
        // The actual move event will be sent 16ms after the previous event
        delayMillis = 16
    )
    // And finish the gesture by lifting both fingers. Can be done in any order
    up(1)
    up(0)
}

fun up(pointerId: Int = 0): Unit

Sends an up event for the pointer with the given pointerId, or the default pointer if pointerId is omitted, on the associated node.

open fun updatePointerBy(pointerId: Int, delta: Offset): Unit

Updates the position of the pointer with the given pointerId by the given delta, but does not send a move event. The move event can be sent with move.

If the pointer is not yet down, an IllegalArgumentException will be thrown.

fun updatePointerTo(pointerId: Int, position: Offset): Unit

Updates the position of the pointer with the given pointerId to the given position, but does not send a move event. The move event can be sent with move. The position is in the node's local coordinate system, where (0.px, 0.px) is the top left corner of the node.

If the pointer is not yet down, an IllegalArgumentException will be thrown.

fun TouchInjectionScope.click(position: Offset = center): Unit

Performs a click gesture (aka a tap) on the associated node.

The click is done at the given position, or in the center if the position is omitted. The position is in the node's local coordinate system, where (0, 0) is the top left corner of the node.

fun TouchInjectionScope.doubleClick(
    position: Offset = center,
    delayMillis: Long = viewConfiguration.defaultDoubleTapDelayMillis
): Unit

Performs a double click gesture (aka a double tap) on the associated node.

The double click is done at the given position or in the center if the position is omitted. By default, the delayMillis between the first and the second click is half way in between the minimum and maximum required delay for a double click. The position is in the node's local coordinate system, where (0, 0) is the top left corner of the node.

fun TouchInjectionScope.longClick(
    position: Offset = center,
    durationMillis: Long = viewConfiguration.longPressTimeoutMillis + 100
): Unit

Performs a long click gesture (aka a long press) on the associated node.

The long click is done at the given position, or in the center if the position is omitted. By default, the durationMillis of the press is 100ms longer than the minimum required duration for a long press. The position is in the node's local coordinate system, where (0, 0) is the top left corner of the node.

fun TouchInjectionScope.multiTouchSwipe(
    curves: List<(timeMillis: Long) -> Offset>,
    durationMillis: Long = 200,
    keyTimes: List<Long> = emptyList()
): Unit

Performs a multi touch swipe gesture on the associated node.

Each pointer follows curves[i] from 0 till durationMillis. Sampling of an event is forced at all times defined in keyTimes. The time between events is kept as close to eventPeriodMillis as possible, given the constraints. The coordinates are in the node's local coordinate system, where (0, 0) is the top left corner of the node. The default duration is 200 milliseconds.

fun TouchInjectionScope.pinch(
    start0: Offset,
    end0: Offset,
    start1: Offset,
    end1: Offset,
    durationMillis: Long = 400
): Unit

Performs a pinch gesture on the associated node.

For each pair of start and end Offsets, the motion events are linearly interpolated. The coordinates are in the node's local coordinate system where (0, 0) is the top left corner of the node. The default duration is 400 milliseconds.

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

Performs a swipe gesture on the associated node.

The swipe follows the curve from 0 till durationMillis. Will force sampling of an event at all times defined in keyTimes. The time between events is kept as close to eventPeriodMillis as possible, given the constraints. The coordinates are in the node's local coordinate system, where (0, 0) is the top left corner of the node. The default duration is 200 milliseconds.

fun TouchInjectionScope.swipe(
    start: Offset,
    end: Offset,
    durationMillis: Long = 200
): Unit

Performs a swipe gesture on the associated node.

The motion events are linearly interpolated between start and end. The coordinates are in the node's local coordinate system, where (0, 0) is the top left corner of the node. The default duration is 200 milliseconds.

fun TouchInjectionScope.swipeDown(
    startY: Float = top,
    endY: Float = bottom,
    durationMillis: Long = 200
): Unit

Performs a swipe down gesture along x = [centerX] of the associated node, from startY till endY, taking durationMillis milliseconds.

fun TouchInjectionScope.swipeLeft(
    startX: Float = right,
    endX: Float = left,
    durationMillis: Long = 200
): Unit

Performs a swipe left gesture along y = [centerY] of the associated node, from startX till endX, taking durationMillis milliseconds.

fun TouchInjectionScope.swipeRight(
    startX: Float = left,
    endX: Float = right,
    durationMillis: Long = 200
): Unit

Performs a swipe right gesture along y = [centerY] of the associated node, from startX till endX, taking durationMillis milliseconds.

fun TouchInjectionScope.swipeUp(
    startY: Float = bottom,
    endY: Float = top,
    durationMillis: Long = 200
): Unit

Performs a swipe up gesture along x = [centerX] of the associated node, from startY till endY, taking durationMillis milliseconds.

fun TouchInjectionScope.swipeWithVelocity(
    start: Offset,
    end: Offset,
    endVelocity: Float,
    durationMillis: Long = VelocityPathFinder.calculateDefaultDuration(start, end, endVelocity)
): Unit

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

The swipe will go through start at t=0 and through end at t=durationMillis. In between, the swipe will go monotonically from start and end, 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 swipe 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 node's local coordinate system, where (0, 0) is the top left corner of the node. The default duration is calculated such that a feasible swipe can be created that ends in the given velocity.