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

MouseInjectionScope

@ExperimentalTestApi
public interface MouseInjectionScope extends 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.animateTo, 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:

import androidx.compose.ui.test.click
import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.performMouseInput

composeTestRule.onNodeWithTag("myComponent")
    .performMouseInput {
        click(center)
    }

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

import androidx.compose.ui.test.onNodeWithTag
import androidx.compose.ui.test.performMouseInput

composeTestRule.onNodeWithTag("myComponent")
    .performMouseInput {
        press()
        repeat(6) {
            advanceEventTime()
            scroll(-1f)
        }
        advanceEventTime()
        release()
    }
See also
InjectionScope

Summary

Public methods

abstract void
cancel(long delayMillis)

Sends a cancel event delayMillis after the last sent event to cancel a stream of mouse events with pressed mouse buttons.

abstract void
enter(@NonNull Offset position, long delayMillis)

Sends a hover enter event at the given position, delayMillis after the last sent event.

abstract void
exit(@NonNull Offset position, long delayMillis)

Sends a hover exit event at the given position, delayMillis after the last sent event.

abstract @NonNull Offset

Returns the current position of the mouse.

default void
moveBy(@NonNull Offset delta, long delayMillis)

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.

abstract void
moveTo(@NonNull Offset position, long delayMillis)

Sends a move event delayMillis after the last sent event on the associated node, with the position of the mouse updated to position.

abstract void

Sends a down and button pressed event for the given button on the associated node.

abstract void

Sends a button released and up event for the given button on the associated node.

abstract void
scroll(float delta, @NonNull ScrollWheel scrollWheel)

Sends a scroll event with the given delta on the given scrollWheel.

default void

Updates the position of the mouse by the given delta, but does not send a move or hover event.

abstract void

Updates the position of the mouse to the given position, but does not send a move or hover event.

Extension functions

default final void
@ExperimentalTestApi
MouseInjectionScopeKt.animateAlong(
    @NonNull MouseInjectionScope receiver,
    @NonNull Function1<@NonNull Long, @NonNull Offset> curve,
    long durationMillis
)

Move the mouse along the given curve, sending a stream of move events to get an animated path of durationMillis milliseconds.

default final void
@ExperimentalTestApi
MouseInjectionScopeKt.animateBy(
    @NonNull MouseInjectionScope receiver,
    @NonNull Offset delta,
    long durationMillis
)

Move the mouse from the current position by the given delta, sending a stream of move events to get an animated path of durationMillis milliseconds.

default final void
@ExperimentalTestApi
MouseInjectionScopeKt.animateTo(
    @NonNull MouseInjectionScope receiver,
    @NonNull Offset position,
    long durationMillis
)

Move the mouse from the current position to the given position, sending a stream of move events to get an animated path of durationMillis milliseconds.

default final void

Click on position, or on the current mouse position if position is unspecified.

default final void

Double-click on position, or on the current mouse position if position is unspecified.

default final void
@ExperimentalTestApi
MouseInjectionScopeKt.dragAndDrop(
    @NonNull MouseInjectionScope receiver,
    @NonNull Offset start,
    @NonNull Offset end,
    long durationMillis
)

Drag and drop something from start to end in durationMillis milliseconds.

default final void

Long-click on position, or on the current mouse position if position is unspecified.

default final void

Secondary-click on position, or on the current mouse position if position is unspecified.

default final void
@ExperimentalTestApi
MouseInjectionScopeKt.smoothScroll(
    @NonNull MouseInjectionScope receiver,
    float scrollAmount,
    long durationMillis,
    @NonNull ScrollWheel scrollWheel
)

Rotate the mouse's scrollWheel by the given scrollAmount.

default final void

Triple-click on position, or on the current mouse position if position is unspecified.

Inherited methods

From androidx.compose.ui.unit.Density
abstract float

The logical density of the display.

abstract float

Current user preference for the scaling factor for fonts.

default int

Convert Dp to Int by rounding

default int

Convert Sp to Int by rounding

default @NonNull Dp

Convert Sp to Dp.

default @NonNull Dp
orgKt.toDp(int receiver)

Convert an Int pixel value to Dp.

default @NonNull Dp
orgKt.toDp(float receiver)

Convert a Float pixel value to a Dp

default @NonNull DpSize

Convert a Size to a DpSize.

default float
orgKt.toPx(@NonNull Dp receiver)

Convert Dp to pixels.

default float

Convert Sp to pixels.

default @NonNull Rect

Convert a DpRect to a Rect.

default @NonNull Size

Convert a DpSize to a Size.

default @NonNull TextUnit
orgKt.toSp(@NonNull Dp receiver)

Convert Dp to Sp.

default @NonNull TextUnit
orgKt.toSp(int receiver)

Convert an Int pixel value to Sp.

default @NonNull TextUnit
orgKt.toSp(float receiver)

Convert a Float pixel value to a Sp

From androidx.compose.ui.test.InjectionScope
abstract void
advanceEventTime(long durationMillis)

Adds the given durationMillis to the current event time, delaying the next event by that time.

default float

The y-coordinate for the bottom of the node we're interacting with in px, in the node's local coordinate system, where (0, 0) is the top left corner of the node.

default @NonNull Offset

The center of the bottom edge of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node.

default @NonNull Offset

The bottom left corner of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node.

default @NonNull Offset

The bottom right corner of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node.

default @NonNull Offset

The center of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node.

default @NonNull Offset

The center of the left edge of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node.

default @NonNull Offset

The center of the right edge of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node.

default float

The x-coordinate for the center of the node we're interacting with in px, in the node's local coordinate system, where (0, 0) is the top left corner of the node.

default float

The y-coordinate for the center of the node we're interacting with in px, in the node's local coordinate system, where (0, 0) is the top left corner of the node.

default long

The default time between two successive events.

default int

The height of the node in px.

default float

The x-coordinate for the left edge of the node we're interacting with in px, in the node's local coordinate system, where (0, 0) is the top left corner of the node.

default float

The x-coordinate for the right edge of the node we're interacting with in px, in the node's local coordinate system, where (0, 0) is the top left corner of the node.

default float

The y-coordinate for the bottom of the node we're interacting with in px, in the node's local coordinate system, where (0, 0) is the top left corner of the node.

default @NonNull Offset

The center of the top edge of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node.

default @NonNull Offset

The top left corner of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node.

default @NonNull Offset

The top right corner of the node we're interacting with, in the node's local coordinate system, where (0, 0) is the top left corner of the node.

abstract @NonNull ViewConfiguration

The ViewConfiguration in use by the SemanticsNode from the SemanticsNodeInteraction on which the input injection method is called.

abstract @NonNull IntSize

The size of the visible part of the node we're interacting with in px, i.e. its clipped bounds.

default int

The width of the node in px.

default @NonNull Offset
percentOffset(float x, float y)

Creates an Offset relative to the size of the node we're interacting with.

Public methods

cancel

abstract void cancel(long delayMillis)

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
long delayMillis

The time between the last sent event and this event. eventPeriodMillis by default.

enter

abstract void enter(@NonNull Offset position, long delayMillis)

Sends a hover enter event at the given position, delayMillis after the last sent event.

Note that it is discouraged to manually send a hover enter event followed by a moveTo event. moveTo does this for you automatically, making sure the event times of the two events are in sync. Only use this method for special scenarios where the hover enter event is not sent as a side effect of another 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.

Parameters
@NonNull Offset position

The new position of the mouse, in the node's local coordinate system. currentPosition by default.

long delayMillis

The time between the last sent event and this event. eventPeriodMillis by default.

exit

abstract void exit(@NonNull Offset position, long delayMillis)

Sends a hover exit event at the given position, delayMillis after the last sent event.

Note that it is discouraged to manually send a hover exit event followed by a moveTo that is outside the boundaries of the Compose root or pressing a button. These methods do this for you automatically, making sure the event times of the two events are in sync. Only use this method for special scenarios where the hover exit event is not sent as a side effect of another 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.

Parameters
@NonNull Offset position

The new position of the mouse, in the node's local coordinate system currentPosition by default.

long delayMillis

The time between the last sent event and this event. eventPeriodMillis by default.

getCurrentPosition

abstract @NonNull Offset getCurrentPosition()

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.

moveBy

default void moveBy(@NonNull Offset delta, long delayMillis)

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
@NonNull Offset delta

The position for this move event, relative to the current position of the mouse. For example, `delta = Offset(10.px, -10.px) will add 10.px to the mouse's x-position, and subtract 10.px from the mouse's y-position.

long delayMillis

The time between the last sent event and this event. eventPeriodMillis by default.

moveTo

abstract void moveTo(@NonNull Offset position, long delayMillis)

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
@NonNull Offset position

The new position of the mouse, in the node's local coordinate system

long delayMillis

The time between the last sent event and this event. eventPeriodMillis by default.

press

abstract void press(@NonNull MouseButton button)

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
@NonNull MouseButton button

The mouse button that is pressed. By default the primary mouse button.

release

abstract void release(@NonNull MouseButton button)

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
@NonNull MouseButton button

The mouse button that is released. By default the primary mouse button.

scroll

abstract void scroll(float delta, @NonNull ScrollWheel scrollWheel)

Sends a scroll event with the given delta on the given scrollWheel. The event will be sent at the current event time. Negative delta values correspond to rotating the scroll wheel leftward or upward, positive values correspond to rotating the scroll wheel rightward or downward.

Parameters
float delta

The amount of scroll

@NonNull ScrollWheel scrollWheel

Which scroll wheel to rotate. Can be either ScrollWheel.Vertical (the default) or ScrollWheel.Horizontal.

updatePointerBy

default void updatePointerBy(@NonNull Offset delta)

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
@NonNull Offset delta

The position for this move event, relative to the current position of the mouse. For example, `delta = Offset(10.px, -10.px) will add 10.px to the mouse's x-position, and subtract 10.px from the mouse's y-position.

updatePointerTo

abstract void updatePointerTo(@NonNull Offset position)

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
@NonNull Offset position

The new position of the mouse, in the node's local coordinate system

Extension functions

MouseInjectionScopeKt.animateAlong

@ExperimentalTestApi
default final void MouseInjectionScopeKt.animateAlong(
    @NonNull MouseInjectionScope receiver,
    @NonNull Function1<@NonNull Long, @NonNull Offset> curve,
    long durationMillis
)

Move the mouse along the given curve, sending a stream of move events to get an animated path of durationMillis milliseconds. The mouse will initially be moved to the start of the path, curve(0), if it is not already there. The positions defined by the curve are in the node's local coordinate system, where (0, 0) is the top left corner of the node.

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

The function that defines the position of the mouse over time for this gesture, in the node's local coordinate system.

long durationMillis

The duration of the gesture. By default 300 milliseconds.

MouseInjectionScopeKt.animateBy

@ExperimentalTestApi
default final void MouseInjectionScopeKt.animateBy(
    @NonNull MouseInjectionScope receiver,
    @NonNull Offset delta,
    long durationMillis
)

Move the mouse from the current position by the given delta, sending a stream of move events to get an animated path of durationMillis milliseconds.

Parameters
@NonNull Offset delta

The position where to move the mouse to, relative to the current position of the mouse. For example, `delta = Offset(100.px, -100.px) will move the mouse 100 pixels to the right and 100 pixels upwards.

long durationMillis

The duration of the gesture. By default 300 milliseconds.

MouseInjectionScopeKt.animateTo

@ExperimentalTestApi
default final void MouseInjectionScopeKt.animateTo(
    @NonNull MouseInjectionScope receiver,
    @NonNull Offset position,
    long durationMillis
)

Move the mouse from the current position to the given position, sending a stream of move events to get an animated path of durationMillis milliseconds. Move the mouse to the desired start position if you want to start from a different position. 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 move the mouse to, in the node's local coordinate system

long durationMillis

The duration of the gesture. By default 300 milliseconds.

MouseInjectionScopeKt.click

@ExperimentalTestApi
default final void MouseInjectionScopeKt.click(
    @NonNull MouseInjectionScope receiver,
    @NonNull Offset position
)

Click on position, or on the current mouse position if position is unspecified. 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. If unspecified, clicks on the current mouse position.

MouseInjectionScopeKt.doubleClick

@ExperimentalTestApi
default final void MouseInjectionScopeKt.doubleClick(
    @NonNull MouseInjectionScope receiver,
    @NonNull Offset position
)

Double-click on position, or on the current mouse position if position is unspecified. 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. If unspecified, clicks on the current mouse position.

MouseInjectionScopeKt.dragAndDrop

@ExperimentalTestApi
default final void MouseInjectionScopeKt.dragAndDrop(
    @NonNull MouseInjectionScope receiver,
    @NonNull Offset start,
    @NonNull Offset end,
    long durationMillis
)

Drag and drop something from start to end in durationMillis milliseconds. This gesture uses the primary mouse button to drag with, and does not reset any mouse buttons prior to starting the gesture. The mouse position is updated to the start position before starting the gesture. The positions defined by the start and end are in the node's local coordinate system, where (0, 0) is the top left corner of the node.

Parameters
@NonNull Offset start

The position where to press the primary mouse button and initiate the drag, in the node's local coordinate system.

@NonNull Offset end

The position where to release the primary mouse button and end the drag, in the node's local coordinate system.

long durationMillis

The duration of the gesture. By default 300 milliseconds.

MouseInjectionScopeKt.longClick

@ExperimentalTestApi
default final void MouseInjectionScopeKt.longClick(
    @NonNull MouseInjectionScope receiver,
    @NonNull Offset position
)

Long-click on position, or on the current mouse position if position is unspecified. 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. If unspecified, clicks on the current mouse position.

MouseInjectionScopeKt.rightClick

@ExperimentalTestApi
default final void MouseInjectionScopeKt.rightClick(
    @NonNull MouseInjectionScope receiver,
    @NonNull Offset position
)

Secondary-click on position, or on the current mouse position if position is unspecified. While the secondary mouse button is not necessarily the right mouse button (e.g. on left-handed mice), this method is still called rightClick for it's widespread use. 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. If unspecified, clicks on the current mouse position.

MouseInjectionScopeKt.smoothScroll

@ExperimentalTestApi
default final void MouseInjectionScopeKt.smoothScroll(
    @NonNull MouseInjectionScope receiver,
    float scrollAmount,
    long durationMillis,
    @NonNull ScrollWheel scrollWheel
)

Rotate the mouse's scrollWheel by the given scrollAmount. The total scroll delta is linearly smoothed out over a stream of scroll events with roughly the InjectionScope.eventPeriodMillis between each scroll event. Negative scrollAmount values correspond to rotating the scroll wheel leftward or downward, positive values correspond to rotating the scroll wheel rightward or upward.

Parameters
float scrollAmount

The total delta to scroll the scrollWheel by

long durationMillis

The duration of the gesture. By default 300 milliseconds.

@NonNull ScrollWheel scrollWheel

Which scroll wheel will be rotated. By default ScrollWheel.Vertical.

MouseInjectionScopeKt.tripleClick

@ExperimentalTestApi
default final void MouseInjectionScopeKt.tripleClick(
    @NonNull MouseInjectionScope receiver,
    @NonNull Offset position
)

Triple-click on position, or on the current mouse position if position is unspecified. 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. If unspecified, clicks on the current mouse position.