GestureScope

GestureScope(node: SemanticsNode, testContext: TestContext)

val visibleSize: IntSize

Returns the size of the visible part of the node we're interacting with. This is contrary to SemanticsNode.size, which returns the unclipped size of the node.

@ExperimentalTestApi
fun GestureScope.advanceEventTime(durationMillis: Long): Unit

Adds the given durationMillis to the current event time, delaying the next event by that time. Only valid when a gesture has already been started, or when a finished gesture is resumed.

fun GestureScope.cancel(): Unit

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

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

Performs a click gesture at the given position on the associated node, 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. The default position is the center of the node.

fun GestureScope.doubleClick(
    position: Offset = center,
    delayMillis: Long = doubleClickDelayMillis
): Unit

Performs a double click gesture at the given position on the associated node, or in the center if the position is omitted. By default, the delayMillis between the first and the second click is 145 milliseconds (empirically established). The position is in the node's local coordinate system, where (0, 0) is the top left corner of the node.

fun GestureScope.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 gesture. If a gesture is already in progress, this event is sent with at the same timestamp as the last event. If the default pointer is already down, an IllegalArgumentException will be thrown.

fun GestureScope.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 gesture. If a gesture is already in progress, this event is sent with at the same timestamp as the last event. If the given pointer is already down, an IllegalArgumentException will be thrown.

Subsequent events for this or other gestures can be spread out over both this and future invocations of performGesture. An entire gesture starts with a down event, followed by several down, move or up events, and ends with an up or a cancel event. Movement can be expressed with moveTo and moveBy to move a single pointer at a time, or movePointerTo and movePointerBy to move multiple pointers at a time. The movePointer[To|By] methods do not send the move event directly, use move to send the move event. Some other methods can send a move event as well. All events, regardless the method used, will always contain the current position of all pointers.

Down and up events are sent at the same time as the previous event, but will send an extra move event just before the down or up event if movePointerTo or movePointerBy has been called and no move event has been sent yet. This does not happen for cancel events, but the cancel event will contain the up to date position of all pointers. Move and cancel events will advance the event time by 16 milliseconds.

Because gestures don't have to be defined all in the same performGesture block, keep in mind that while the gesture is not complete, all code you execute in between blocks that progress the gesture, will be executed while imaginary fingers are actively touching the screen.

In the context of testing, it is not necessary to complete a gesture with an up or cancel event, if the test ends before it expects the finger to be lifted from the screen.

fun GestureScope.longClick(
    position: Offset = center,
    durationMillis: Long = LongPressTimeoutMillis + 100
): Unit

Performs a long click gesture at the given position on the associated node, or in the center if the position is omitted. By default, the durationMillis of the press is LongPressTimeoutMillis + 100 milliseconds. The position is in the node's local coordinate system, where (0, 0) is the top left corner of the node.

fun GestureScope.move(): Unit

Sends a move event without updating any of the pointer positions. This can be useful when batching movement of multiple pointers together, which can be done with movePointerTo and movePointerBy.

fun GestureScope.moveBy(delta: Offset): Unit

Sends a move 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.

fun GestureScope.moveBy(pointerId: Int, delta: Offset): Unit

Sends a move 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.

fun GestureScope.movePointerBy(pointerId: Int, delta: Offset): Unit

Moves 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 GestureScope.movePointerTo(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 GestureScope.moveTo(position: Offset): Unit

Sends a move 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.

fun GestureScope.moveTo(pointerId: Int, position: Offset): Unit

Sends a move 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.

fun GestureScope.percentOffset(x: Float = 0.0f, y: Float = 0.0f): Offset

Creates an Offset relative to the size of the node we're interacting with. x and y are fractions of the width and height, between -1 and 1. Note that percentOffset(1f, 1f) != bottomRight, see right and bottom.

For example: percentOffset(.5f, .5f) is the same as the center; centerLeft + percentOffset(.1f, 0f) is a point 10% inward from the middle of the left edge; and bottomRight - percentOffset(.2f, .1f) is a point 20% to the left and 10% to the top of the bottom right corner.

fun GestureScope.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 GestureScope.swipe(start: Offset, end: Offset, durationMillis: Long = 200): Unit

Performs the 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 GestureScope.swipeDown(): Unit

Performs a swipe down gesture along the centerX of the associated node. The gesture starts slightly below the top of the node and ends at the bottom.

@ExperimentalTestApi
fun GestureScope.swipeDown(
    startY: Float = topFuzzed,
    endY: Float = bottom,
    durationMillis: Long = 200
): Unit

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

fun GestureScope.swipeLeft(): Unit

Performs a swipe left gesture along the centerY of the associated node. The gesture starts slightly left of the right side of the node and ends at the left side.

@ExperimentalTestApi
fun GestureScope.swipeLeft(
    startX: Float = rightFuzzed,
    endX: Float = left,
    durationMillis: Long = 200
): Unit

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

fun GestureScope.swipeRight(): Unit

Performs a swipe right gesture along the centerY of the associated node. The gesture starts slightly right of the left side of the node and ends at the right side.

@ExperimentalTestApi
fun GestureScope.swipeRight(
    startX: Float = leftFuzzed,
    endX: Float = right,
    durationMillis: Long = 200
): Unit

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

fun GestureScope.swipeUp(): Unit

Performs a swipe up gesture along the centerX of the associated node. The gesture starts slightly above the bottom of the node and ends at the top.

@ExperimentalTestApi
fun GestureScope.swipeUp(
    startY: Float = bottomFuzzed,
    endY: Float = top,
    durationMillis: Long = 200
): Unit

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

fun GestureScope.swipeWithVelocity(
    start: Offset,
    end: Offset,
    endVelocity: Float,
    durationMillis: Long = 200
): Unit

Performs the swipe gesture on the associated node, such that the velocity when the gesture is finished is roughly equal to endVelocity. The MotionEvents 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.

Note that due to imprecisions, no guarantees can be made on the precision of the actual velocity at the end of the gesture, but generally it is within 0.1% of the desired velocity.

fun GestureScope.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. If any pointers have been moved with movePointerTo or movePointerBy and no move event has been sent yet, a move event will be sent right before the up event.

val GestureScope.bottom: Float

Returns the y-coordinate for the bottom of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node. Note that, unless height == 0, bottom != height. In particular, bottom == height - 1f, because pixels are 0-based. If height == 0, bottom == 0 too.

val GestureScope.bottomCenter: Offset

Returns the center of the bottom edge of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node. Note that bottomCenter.y != height, see bottom.

val GestureScope.bottomLeft: Offset

Returns the bottom left corner of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node. Note that bottomLeft.y != height, see bottom.

val GestureScope.bottomRight: Offset

Returns the bottom right corner of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node. Note that bottomRight.x != width and bottomRight.y != height, see right and bottom.

val GestureScope.center: Offset

Returns the center of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node.

val GestureScope.centerLeft: Offset

Returns the center of the left edge of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node.

val GestureScope.centerRight: Offset

Returns the center of the right edge of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node. Note that centerRight.x != width, see right.

val GestureScope.centerX: Float

Returns the x-coordinate for the center of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node.

val GestureScope.centerY: Float

Returns the y-coordinate for the center of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node.

val GestureScope.height: Int

Shorthand for size.height

val GestureScope.left: Float

Returns the x-coordinate for the left edge of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node.

val GestureScope.right: Float

Returns the x-coordinate for the right edge of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node. Note that, unless width == 0, right != width. In particular, right == width - 1f, because pixels are 0-based. If width == 0, right == 0 too.

val GestureScope.top: Float

Returns the y-coordinate for the bottom of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node.

val GestureScope.topCenter: Offset

Returns the center of the top edge of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node.

val GestureScope.topLeft: Offset

Returns the top left corner of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node.

val GestureScope.topRight: Offset

Returns the top right corner of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node. Note that topRight.x != width, see right.

val GestureScope.width: Int

Shorthand for size.width