TrackpadInjectionScope

public interface TrackpadInjectionScope : InjectionScope

The receiver scope of the trackpad input injection lambda from performTrackpadInput.

The functions in TrackpadInjectionScope can roughly be divided into two groups: full gestures and individual trackpad events. The individual trackpad events are: press, moveTo and friends, release, cancel, pan and advanceEventTime. Full gestures are all the other functions, like TrackpadInjectionScope.click, TrackpadInjectionScope.doubleClick, TrackpadInjectionScope.animateMoveTo, etc. These are built on top of the individual events and serve as a good example on how you can build your own full gesture functions.

A trackpad move event can be sent with moveTo and moveBy. The trackpad position can be updated with updatePointerTo and updatePointerBy, which will not send an event and only update the position internally. This can be useful if you want to send an event that is not a move event with a location other than the current location, but without sending a preceding move event. Use press and release to send button pressed and button released events. This will also send all other necessary events that keep the stream of trackpad events consistent with actual trackpad input, such as a hover exit event. A cancel event can be sent at any time when at least one button is pressed. Use pan to send a trackpad pan event.

The entire event injection state is shared between all perform.*Input methods, meaning you can continue an unfinished trackpad gesture in a subsequent invocation of performTrackpadInput or performMultiModalInput. Note however that while the trackpad's position is retained across invocation of perform.*Input methods, it is always manipulated in the current node's local coordinate system. That means that two subsequent invocations of performTrackpadInput on different nodes will report a different currentPosition, even though it is actually the same position on the screen.

All events sent by these methods are batched together and sent as a whole after performTrackpadInput has executed its code block.

Example of performing a trackpad click:

Properties

currentPosition

public 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](/jetpack-compose/androidx.compose.ui/ui-test/properties/topLeft/api) in the node's local coordinate system.

Functions

moveTo

public fun moveTo(position: Offset, delayMillis: Long = eventPeriodMillis)

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.

Parameters

moveBy

public fun moveBy(delta: Offset, delayMillis: Long = eventPeriodMillis)

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.

Parameters

updatePointerTo

public fun updatePointerTo(position: Offset)

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.

Parameters

updatePointerBy

public fun updatePointerBy(delta: Offset)

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.

Parameters

press

public fun press(button: TrackpadButton = TrackpadButton.Primary)

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.

Parameters

Throws: IllegalStateException

if the button is already pressed.

release

public fun release(button: TrackpadButton = TrackpadButton.Primary)

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.

Parameters

Throws: IllegalStateException

if the button is not pressed.

cancel

public fun cancel(delayMillis: Long = eventPeriodMillis)

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.

Parameters

enter

public fun enter(position: Offset = currentPosition, delayMillis: Long = eventPeriodMillis)

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.

Parameters

Throws: IllegalStateException

if buttons are down, or if the trackpad is already hovering.

exit

public fun exit(position: Offset = currentPosition, delayMillis: Long = eventPeriodMillis)

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.

Parameters

Throws: IllegalStateException

if the trackpad was not hovering.

panStart

public fun panStart()

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.

Throws: IllegalStateException

if the trackpad was already sending a pan gesture.

panMoveBy

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

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.

Parameters

Throws: IllegalStateException

if the trackpad is not in a pan gesture started by panStart.

panEnd

public fun panEnd(delayMillis: Long = eventPeriodMillis)

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.

Parameters

Throws: IllegalStateException

if the trackpad is not in a pan gesture started by panStart.

scaleStart

public fun scaleStart()

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.

Throws: IllegalStateException

if the trackpad was already sending a scale gesture.

scaleChangeBy

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

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.

Parameters

Throws: IllegalStateException

if the trackpad is not in a scale gesture started by scaleStart.

scaleEnd

public fun scaleEnd(delayMillis: Long = eventPeriodMillis)

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.

Parameters

Throws: IllegalStateException

if the trackpad is not in a scale gesture started by scaleStart.