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

TouchInjectionScopeKt

public final class TouchInjectionScopeKt


Summary

Public methods

static final void

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

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

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

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

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

static final void
@ExperimentalTestApi
multiTouchSwipe(
    @NonNull TouchInjectionScope receiver,
    @NonNull List<@NonNull Function1<@NonNull Long, @NonNull Offset>> curves,
    long durationMillis,
    @NonNull List<@NonNull Long> keyTimes
)

Performs a multi touch swipe gesture on the associated node.

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

Performs a pinch gesture on the associated node.

static final void
swipe(
    @NonNull TouchInjectionScope receiver,
    @NonNull Function1<@NonNull Long, @NonNull Offset> curve,
    long durationMillis,
    @NonNull List<@NonNull Long> keyTimes
)

Performs a swipe gesture on the associated node.

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

Performs a swipe gesture on the associated node.

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

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

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

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

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

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

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

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

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

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

Public methods

click

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

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.

Parameters
@NonNull Offset position

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

doubleClick

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

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.

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

longClick

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

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.

Parameters
@NonNull Offset position

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

long durationMillis

The time between the down and the up event

multiTouchSwipe

@ExperimentalTestApi
public static final void multiTouchSwipe(
    @NonNull TouchInjectionScope receiver,
    @NonNull List<@NonNull Function1<@NonNull Long, @NonNull Offset>> curves,
    long durationMillis,
    @NonNull List<@NonNull Long> keyTimes
)

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.

Will stay experimental until support has been added to start and end each pointer at different times.

Parameters
@NonNull List<@NonNull Function1<@NonNull Long, @NonNull Offset>> curves

The functions that define the position of the gesture over time

long durationMillis

The duration of the gesture

@NonNull List<@NonNull Long> keyTimes

An optional list of timestamps in milliseconds at which a move event must be sampled

pinch

public static final void pinch(
    @NonNull TouchInjectionScope 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 TouchInjectionScope receiver,
    @NonNull Function1<@NonNull Long, @NonNull Offset> curve,
    long durationMillis,
    @NonNull List<@NonNull Long> keyTimes
)

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.

Parameters
@NonNull Function1<@NonNull Long, @NonNull Offset> curve

The function that defines the position of the gesture over time

long durationMillis

The duration of the gesture

@NonNull List<@NonNull Long> keyTimes

An optional list of timestamps in milliseconds at which a move event must be sampled

swipe

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

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.

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 TouchInjectionScope receiver,
    float startY,
    float endY,
    long durationMillis
)

Performs a swipe down gesture along x = [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 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 TouchInjectionScope receiver,
    float startX,
    float endX,
    long durationMillis
)

Performs a swipe left gesture along y = [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 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 TouchInjectionScope receiver,
    float startX,
    float endX,
    long durationMillis
)

Performs a swipe right gesture along y = [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 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 TouchInjectionScope receiver,
    float startY,
    float endY,
    long durationMillis
)

Performs a swipe up gesture along x = [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 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 TouchInjectionScope receiver,
    @NonNull Offset start,
    @NonNull Offset end,
    float endVelocity,
    long durationMillis
)

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.

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 in px/second. 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 40ms or more. If omitted, a duration is calculated such that a valid swipe with velocity can be created.

Throws
kotlin.IllegalArgumentException

When no swipe can be generated that will result in the desired velocity. The error message will suggest changes to the input parameters such that a swipe will become feasible.