MouseInjectionScope

interface MouseInjectionScope : InjectionScope

The receiver scope of the mouse input injection lambda from performMouseInput.

The functions in MouseInjectionScope can roughly be divided into two groups: full gestures and individual mouse events. The individual mouse events are: press, moveTo and friends, release, cancel, scroll and advanceEventTime. Full gestures are all the other functions, like MouseInjectionScope.click, MouseInjectionScope.doubleClick, MouseInjectionScope.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 mouse move event can be sent with moveTo and moveBy. The mouse 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 mouse events consistent with actual mouse input, such as a hover exit event. A cancel event can be sent at any time when at least one button is pressed. Use scroll to send a mouse scroll event.

The entire event injection state is shared between all perform.*Input methods, meaning you can continue an unfinished mouse gesture in a subsequent invocation of performMouseInput or performMultiModalInput. Note however that while the mouse'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 performMouseInput 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 performMouseInput has executed its code block.

Example of performing a mouse click:

Example of scrolling the mouse wheel while the mouse button is pressed:

Properties

val currentPosition: Offset

Returns the current position of the mouse. 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 mouse'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 mouse 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 mouse buttons are pressed, a hover event will be sent instead of a move event. If the mouse wasn't hovering yet, a hover enter event is sent as well.

Parameters

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 mouse moved by the given delta.

If no mouse buttons are pressed, a hover event will be sent instead of a move event. If the mouse wasn't hovering yet, a hover enter event is sent as well.

Parameters

fun updatePointerTo(position: Offset)

Updates the position of the mouse to the given position, but does not send a move or hover event. This can be useful to adjust the mouse 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

fun updatePointerBy(delta: Offset)

Updates the position of the mouse by the given delta, but does not send a move or hover event. This can be useful to adjust the mouse position before sending for example a press event.

Parameters

fun press(button: MouseButton = MouseButton.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.

Throws an IllegalStateException if the button is already pressed.

Parameters

fun release(button: MouseButton = MouseButton.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 mouse will enter hovering mode and send an accompanying mouse move event after the button has been released. All events will be sent at the current event time.

Throws an IllegalStateException if the button is not pressed.

Parameters

fun cancel(delayMillis: Long = eventPeriodMillis)

Sends a cancel event delayMillis after the last sent event to cancel a stream of mouse events with pressed mouse buttons. All buttons will be released as a result. A mouse cancel event can only be sent when mouse buttons are pressed.

Parameters

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.

An IllegalStateException will be thrown when mouse buttons are down, or if the mouse is already hovering.

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 mouse 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

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.

An IllegalStateException will be thrown if the mouse was not hovering.

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 mouse 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

fun scroll(delta: Float, scrollWheel: ScrollWheel = ScrollWheel.Vertical)

Sends a scroll event with the given delta on the given scrollWheel. The event will be sent at the current event time.

Positive delta values correspond to scrolling forward (new content appears at the bottom of a column, or at the end of a row), negative values correspond to scrolling backward (new content appears at the top of a column, or at the start of a row).

Note that the correlation between scroll delta and pixels scrolled is platform specific. For example, on Android a scroll delta of 1f corresponds to a scroll of 64.dp. However, on any platform, this conversion factor could change in the future to improve the mouse scroll experience.

Example of how scroll could be used:

Parameters