---
title: "TrackpadInjectionScope"
description: "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:"
type: "interface"
---
Interface
Common
```kotlin
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
```kotlin
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
```kotlin
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. |
```kotlin
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. |
```kotlin
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 |
```kotlin
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. |
```kotlin
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. |
```kotlin
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. |
```kotlin
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. |
```kotlin
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. |
```kotlin
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. |
```kotlin
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.
```kotlin
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. |
```kotlin
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. |
```kotlin
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.
```kotlin
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. |
```kotlin
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
```kotlin
fun trackpadInputClick() {
composeTestRule.onNodeWithTag("myComponent").performTrackpadInput {
// Click in the middle of the node
click(center)
}
}
```