{% setvar book_path %}/reference/androidx/_book.yaml{% endsetvar %} {% include "_shared/_reference-head-tags.html" %}

GestureScopeKt

public final class GestureScopeKt


Summary

Public methods

static final void
@ExperimentalTestApi
advanceEventTime(@NonNull GestureScope receiver, long durationMillis)

This method is deprecated. Replaced by TouchInjectionScope.

static final void

This method is deprecated. Replaced by TouchInjectionScope.

static final void
click(@NonNull GestureScope receiver, @NonNull Offset position)

This method is deprecated. Replaced by TouchInjectionScope.

static final void
doubleClick(
    @NonNull GestureScope receiver,
    @NonNull Offset position,
    long delayMillis
)

This method is deprecated. Replaced by TouchInjectionScope.

static final void
down(@NonNull GestureScope receiver, @NonNull Offset position)

This method is deprecated. Replaced by TouchInjectionScope.

static final void
down(
    @NonNull GestureScope receiver,
    int pointerId,
    @NonNull Offset position
)

This method is deprecated. Replaced by TouchInjectionScope.

static final 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.

static final @NonNull 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.

static final @NonNull 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.

static final @NonNull 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.

static final @NonNull 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.

static final @NonNull 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.

static final @NonNull 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.

static final 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.

static final 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.

static final int

Shorthand for size.height

static final 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.

static final 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.

static final 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.

static final @NonNull 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.

static final @NonNull 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.

static final @NonNull 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.

static final int

Shorthand for size.width

static final void
longClick(
    @NonNull GestureScope receiver,
    @NonNull Offset position,
    long durationMillis
)

This method is deprecated. Replaced by TouchInjectionScope.

static final void

This method is deprecated. Replaced by TouchInjectionScope.

static final void
moveBy(@NonNull GestureScope receiver, @NonNull Offset delta)

This method is deprecated. Replaced by TouchInjectionScope.

static final void
moveBy(@NonNull GestureScope receiver, int pointerId, @NonNull Offset delta)

This method is deprecated. Replaced by TouchInjectionScope.

static final void
movePointerBy(
    @NonNull GestureScope receiver,
    int pointerId,
    @NonNull Offset delta
)

This method is deprecated. Replaced by TouchInjectionScope.

static final void
movePointerTo(
    @NonNull GestureScope receiver,
    int pointerId,
    @NonNull Offset position
)

This method is deprecated. Replaced by TouchInjectionScope.

static final void
moveTo(@NonNull GestureScope receiver, @NonNull Offset position)

This method is deprecated. Replaced by TouchInjectionScope.

static final void
moveTo(
    @NonNull GestureScope receiver,
    int pointerId,
    @NonNull Offset position
)

This method is deprecated. Replaced by TouchInjectionScope.

static final @NonNull Offset
percentOffset(@NonNull GestureScope receiver, float x, float y)

This method is deprecated. Replaced by TouchInjectionScope.

static final void
pinch(
    @NonNull GestureScope receiver,
    @NonNull Offset start0,
    @NonNull Offset end0,
    @NonNull Offset start1,
    @NonNull Offset end1,
    long durationMillis
)

This method is deprecated. Replaced by TouchInjectionScope.

static final void
swipe(
    @NonNull GestureScope receiver,
    @NonNull Offset start,
    @NonNull Offset end,
    long durationMillis
)

This method is deprecated. Replaced by TouchInjectionScope.

static final void

This method is deprecated. Replaced by TouchInjectionScope.

static final void
@ExperimentalTestApi
swipeDown(
    @NonNull GestureScope receiver,
    float startY,
    float endY,
    long durationMillis
)

This method is deprecated. Replaced by TouchInjectionScope.

static final void

This method is deprecated. Replaced by TouchInjectionScope.

static final void
@ExperimentalTestApi
swipeLeft(
    @NonNull GestureScope receiver,
    float startX,
    float endX,
    long durationMillis
)

This method is deprecated. Replaced by TouchInjectionScope.

static final void

This method is deprecated. Replaced by TouchInjectionScope.

static final void
@ExperimentalTestApi
swipeRight(
    @NonNull GestureScope receiver,
    float startX,
    float endX,
    long durationMillis
)

This method is deprecated. Replaced by TouchInjectionScope.

static final void

This method is deprecated. Replaced by TouchInjectionScope.

static final void
@ExperimentalTestApi
swipeUp(
    @NonNull GestureScope receiver,
    float startY,
    float endY,
    long durationMillis
)

This method is deprecated. Replaced by TouchInjectionScope.

static final void
swipeWithVelocity(
    @NonNull GestureScope receiver,
    @NonNull Offset start,
    @NonNull Offset end,
    float endVelocity,
    long durationMillis
)

This method is deprecated. Replaced by TouchInjectionScope.

static final void
up(@NonNull GestureScope receiver, int pointerId)

This method is deprecated. Replaced by TouchInjectionScope.

Public methods

advanceEventTime

@ExperimentalTestApi
public static final void advanceEventTime(@NonNull GestureScope receiver, long durationMillis)

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.

cancel

public static final void cancel(@NonNull GestureScope receiver)

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

click

public static final void click(@NonNull GestureScope receiver, @NonNull Offset position)

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.

Parameters
@NonNull Offset position

The position where to click, in the node's local coordinate system. If omitted, the center position will be used.

doubleClick

public static final void doubleClick(
    @NonNull GestureScope receiver,
    @NonNull Offset position,
    long delayMillis
)

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.

Parameters
@NonNull Offset position

The position of the double click, in the node's local coordinate system. If omitted, the center position will be used.

long delayMillis

The time between the up event of the first click and the down event of the second click

down

public static final void down(@NonNull GestureScope receiver, @NonNull Offset position)

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.

Parameters
@NonNull Offset position

The position of the down event, in the node's local coordinate system

down

public static final void down(
    @NonNull GestureScope receiver,
    int pointerId,
    @NonNull Offset position
)

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.

Parameters
int pointerId

The id of the pointer, can be any number not yet in use by another pointer

@NonNull Offset position

The position of the down event, in the node's local coordinate system

getBottom

public static final float getBottom(@NonNull GestureScope receiver)

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.

getBottomCenter

public static final @NonNull Offset getBottomCenter(@NonNull GestureScope receiver)

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.

getBottomLeft

public static final @NonNull Offset getBottomLeft(@NonNull GestureScope receiver)

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.

getBottomRight

public static final @NonNull Offset getBottomRight(@NonNull GestureScope receiver)

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.

getCenter

public static final @NonNull Offset getCenter(@NonNull GestureScope receiver)

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.

getCenterLeft

public static final @NonNull Offset getCenterLeft(@NonNull GestureScope receiver)

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.

getCenterRight

public static final @NonNull Offset getCenterRight(@NonNull GestureScope receiver)

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.

getCenterX

public static final float getCenterX(@NonNull GestureScope receiver)

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.

getCenterY

public static final float getCenterY(@NonNull GestureScope receiver)

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.

getHeight

public static final int getHeight(@NonNull GestureScope receiver)

Shorthand for size.height

getLeft

public static final float getLeft(@NonNull GestureScope receiver)

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.

getRight

public static final float getRight(@NonNull GestureScope receiver)

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.

getTop

public static final float getTop(@NonNull GestureScope receiver)

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.

getTopCenter

public static final @NonNull Offset getTopCenter(@NonNull GestureScope receiver)

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.

getTopLeft

public static final @NonNull Offset getTopLeft(@NonNull GestureScope receiver)

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.

getTopRight

public static final @NonNull Offset getTopRight(@NonNull GestureScope receiver)

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.

getWidth

public static final int getWidth(@NonNull GestureScope receiver)

Shorthand for size.width

longClick

public static final void longClick(
    @NonNull GestureScope receiver,
    @NonNull Offset position,
    long durationMillis
)

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.

Parameters
@NonNull Offset position

The position of the long click, in the node's local coordinate system. If omitted, the center position will be used.

long durationMillis

The time between the down and the up event

move

public static final void move(@NonNull GestureScope receiver)

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.

moveBy

public static final void moveBy(@NonNull GestureScope receiver, @NonNull Offset delta)

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.

Parameters
@NonNull Offset delta

The position for this move event, relative to the last sent position of the pointer. For example, `delta = Offset(10.px, -10.px) will add 10.px to the pointer's last x-position, and subtract 10.px from the pointer's last y-position.

moveBy

public static final void moveBy(@NonNull GestureScope receiver, int pointerId, @NonNull Offset delta)

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.

Parameters
int pointerId

The id of the pointer to move, as supplied in down

@NonNull Offset delta

The position for this move event, relative to the last sent position of the pointer. For example, `delta = Offset(10.px, -10.px) will add 10.px to the pointer's last x-position, and subtract 10.px from the pointer's last y-position.

movePointerBy

public static final void movePointerBy(
    @NonNull GestureScope receiver,
    int pointerId,
    @NonNull Offset delta
)

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.

Parameters
int pointerId

The id of the pointer to move, as supplied in down

@NonNull Offset delta

The position for this move event, relative to the last sent position of the pointer. For example, `delta = Offset(10.px, -10.px) will add 10.px to the pointer's last x-position, and subtract 10.px from the pointer's last y-position.

movePointerTo

public static final void movePointerTo(
    @NonNull GestureScope receiver,
    int pointerId,
    @NonNull Offset position
)

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.

Parameters
int pointerId

The id of the pointer to move, as supplied in down

@NonNull Offset position

The new position of the pointer, in the node's local coordinate system

moveTo

public static final void moveTo(@NonNull GestureScope receiver, @NonNull Offset position)

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.

Parameters
@NonNull Offset position

The new position of the pointer, in the node's local coordinate system

moveTo

public static final void moveTo(
    @NonNull GestureScope receiver,
    int pointerId,
    @NonNull Offset position
)

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.

Parameters
int pointerId

The id of the pointer to move, as supplied in down

@NonNull Offset position

The new position of the pointer, in the node's local coordinate system

percentOffset

public static final @NonNull Offset percentOffset(@NonNull GestureScope receiver, float x, float y)

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.

pinch

public static final void pinch(
    @NonNull GestureScope receiver,
    @NonNull Offset start0,
    @NonNull Offset end0,
    @NonNull Offset start1,
    @NonNull Offset end1,
    long durationMillis
)

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.

Parameters
@NonNull Offset start0

The start position of the first gesture in the node's local coordinate system

@NonNull Offset end0

The end position of the first gesture in the node's local coordinate system

@NonNull Offset start1

The start position of the second gesture in the node's local coordinate system

@NonNull Offset end1

The end position of the second gesture in the node's local coordinate system

long durationMillis

the duration of the gesture

swipe

public static final void swipe(
    @NonNull GestureScope receiver,
    @NonNull Offset start,
    @NonNull Offset end,
    long durationMillis
)

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.

Parameters
@NonNull Offset start

The start position of the gesture, in the node's local coordinate system

@NonNull Offset end

The end position of the gesture, in the node's local coordinate system

long durationMillis

The duration of the gesture

swipeDown

public static final void swipeDown(@NonNull GestureScope receiver)

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.

swipeDown

@ExperimentalTestApi
public static final void swipeDown(
    @NonNull GestureScope receiver,
    float startY,
    float endY,
    long durationMillis
)

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

Parameters
float startY

The y-coordinate of the start of the swipe. Must be less than or equal to the endY. By default slightly below the top of the node.

float endY

The y-coordinate of the end of the swipe. Must be greater than or equal to the startY. By default the bottom of the node.

long durationMillis

The duration of the swipe. By default 200 milliseconds.

swipeLeft

public static final void swipeLeft(@NonNull GestureScope receiver)

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.

swipeLeft

@ExperimentalTestApi
public static final void swipeLeft(
    @NonNull GestureScope receiver,
    float startX,
    float endX,
    long durationMillis
)

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

Parameters
float startX

The x-coordinate of the start of the swipe. Must be greater than or equal to the endX. By default slightly left of the right of the node.

float endX

The x-coordinate of the end of the swipe. Must be less than or equal to the startX. By default the left of the node.

long durationMillis

The duration of the swipe. By default 200 milliseconds.

swipeRight

public static final void swipeRight(@NonNull GestureScope receiver)

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.

swipeRight

@ExperimentalTestApi
public static final void swipeRight(
    @NonNull GestureScope receiver,
    float startX,
    float endX,
    long durationMillis
)

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

Parameters
float startX

The x-coordinate of the start of the swipe. Must be less than or equal to the endX. By default slightly right of the left of the node.

float endX

The x-coordinate of the end of the swipe. Must be greater than or equal to the startX. By default the right of the node.

long durationMillis

The duration of the swipe. By default 200 milliseconds.

swipeUp

public static final void swipeUp(@NonNull GestureScope receiver)

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.

swipeUp

@ExperimentalTestApi
public static final void swipeUp(
    @NonNull GestureScope receiver,
    float startY,
    float endY,
    long durationMillis
)

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

Parameters
float startY

The y-coordinate of the start of the swipe. Must be greater than or equal to the endY. By default slightly above the bottom of the node.

float endY

The y-coordinate of the end of the swipe. Must be less than or equal to the startY. By default the top of the node.

long durationMillis

The duration of the swipe. By default 200 milliseconds.

swipeWithVelocity

public static final void swipeWithVelocity(
    @NonNull GestureScope receiver,
    @NonNull Offset start,
    @NonNull Offset end,
    float endVelocity,
    long durationMillis
)

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.

Parameters
@NonNull Offset start

The start position of the gesture, in the node's local coordinate system

@NonNull Offset end

The end position of the gesture, in the node's local coordinate system

float endVelocity

The velocity of the gesture at the moment it ends. Must be positive.

long durationMillis

The duration of the gesture in milliseconds. Must be long enough that at least 3 input events are generated, which happens with a duration of 25ms or more.

up

public static final void up(@NonNull GestureScope receiver, int pointerId)

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.

Parameters
int pointerId

The id of the pointer to lift up, as supplied in down