TrackpadInjectionScope

Interface
Common
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 then 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

Common
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`` in the node's local coordinate system.

Functions

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
position The new position of the trackpad, in the node's local coordinate system
delayMillis The time between the last sent event and this event. eventPeriodMillis by default. 
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
delta The position for this move event, relative to the current position of the trackpad. For example, `delta = Offset(10.px, -10.px) will add 10.px to the trackpad's x-position, and subtract 10.px from the trackpad's y-position.
delayMillis The time between the last sent event and this event. eventPeriodMillis by default. 
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
position The new position of the trackpad, in the node's local coordinate system 
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
delta The position for this move event, relative to the current position of the trackpad. For example, `delta = Offset(10.px, -10.px) will add 10.px to the trackpad's x-position, and subtract 10.px from the trackpad's y-position. 
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
button The button that is pressed. By default the primary button. 
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
button The button that is released. By default the primary button. 
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
delayMillis The time between the last sent event and this event. eventPeriodMillis by default. 
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
position The new position of the trackpad, in the node's local coordinate system. currentPosition by default.
delayMillis The time between the last sent event and this event. eventPeriodMillis by default. 
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
position The new position of the trackpad, in the node's local coordinate system currentPosition by default.
delayMillis The time between the last sent event and this event. eventPeriodMillis by default. 
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.

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
delta the incremental change in the pan offset.
delayMillis The time between the last sent event and this event. eventPeriodMillis by default. 
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
delayMillis The time between the last sent event and this event. eventPeriodMillis by default. 
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.

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
scaleFactor the incremental multiplicative change in the scale factor.
delayMillis The time between the last sent event and this event. eventPeriodMillis by default. 
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
delayMillis The time between the last sent event and this event. eventPeriodMillis by default.

Code Examples

trackpadInputClick

fun trackpadInputClick() {
    composeTestRule.onNodeWithTag("myComponent").performTrackpadInput {
        // Click in the middle of the node
        click(center)
    }
}