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

KeyInjectionScope

public interface KeyInjectionScope extends InjectionScope


The receiver scope of the key input injection lambda from performKeyInput.

All sequences and patterns of key input can be expressed using the two fundamental methods of this API - keyDown and keyUp. All other injection functions are provided as abstractions built on top of these two methods in order to improve test code readability/maintainability and decrease development time.

The entire event injection state is shared between all perform.*Input methods, meaning you can continue an unfinished key input sequence in a subsequent invocation of performKeyInput or performMultiModalInput.

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

When a key is held down - i.e. the virtual clock is forwarded whilst the key is pressed down, repeat key down events will be sent. In a fashion consistent with Android's implementation, the first repeat key event will be sent after a key has been held down for 500ms. Subsequent repeat events will be sent at 50ms intervals, until the key is released or another key is pressed down.

The sending of repeat key events is handled as an implicit side-effect of advanceEventTime, which is called within the injection scope. As such, no repeat key events will be sent if MainTestClock.advanceTimeBy is used to advance the time.

See also
InjectionScope

Summary

Public methods

abstract boolean

Indicates whether caps lock is on or not.

abstract boolean

Checks if the given key is down.

abstract boolean

Indicates whether num lock is on or not.

abstract boolean

Indicates whether scroll lock is on or not.

abstract void

Sends a key down event for the given key.

abstract void

Sends a key up event for the given key.

Extension functions

default final boolean

Verifies whether either of the alt keys are down.

default final boolean

Verifies whether either of the control keys are down.

default final boolean

Verifies whether the function key is down.

default final boolean

Verifies whether either of the meta keys are down.

default final boolean

Verifies whether either of the shift keys are down.

default final void
KeyInjectionScopeKt.pressKey(
    @NonNull KeyInjectionScope receiver,
    @NonNull Key key,
    long pressDurationMillis
)

Holds down the given key for the given pressDurationMillis by sending a key down event, advancing the event time and sending a key up event.

default final void

Executes the keyboard sequence specified in the given block, whilst holding down the given key.

default final void

Executes the keyboard sequence specified in the given block, in between presses to the given key.

default final void

Executes the keyboard sequence specified in the given block, whilst holding down the each of the given keys.

default final void

Executes the keyboard sequence specified in the given block, in between presses to the given keys.

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

isCapsLockOn

abstract boolean isCapsLockOn()

Indicates whether caps lock is on or not.

Note that this reflects the state of the injected input only, it does not correspond to the state of an actual keyboard attached to the device on which a test is run

isKeyDown

abstract boolean isKeyDown(@NonNull Key key)

Checks if the given key is down.

Parameters
@NonNull Key key

The key to be checked.

Returns
boolean

true if the given key is pressed down, false otherwise.

isNumLockOn

abstract boolean isNumLockOn()

Indicates whether num lock is on or not.

Note that this reflects the state of the injected input only, it does not correspond to the state of an actual keyboard attached to the device on which a test is run

isScrollLockOn

abstract boolean isScrollLockOn()

Indicates whether scroll lock is on or not.

Note that this reflects the state of the injected input only, it does not correspond to the state of an actual keyboard attached to the device on which a test is run

keyDown

abstract void keyDown(@NonNull Key key)

Sends a key down event for the given key.

If the given key is already down, an IllegalStateException will be thrown.

Parameters
@NonNull Key key

The key to be pressed down.

keyUp

abstract void keyUp(@NonNull Key key)

Sends a key up event for the given key.

If the given key is already up, an IllegalStateException will be thrown.

Parameters
@NonNull Key key

The key to be released.

Extension functions

KeyInjectionScopeKt.isAltDown

default final boolean KeyInjectionScopeKt.isAltDown(@NonNull KeyInjectionScope receiver)

Verifies whether either of the alt keys are down.

Returns
boolean

true if an alt key is currently down, false otherwise.

KeyInjectionScopeKt.isCtrlDown

default final boolean KeyInjectionScopeKt.isCtrlDown(@NonNull KeyInjectionScope receiver)

Verifies whether either of the control keys are down.

Returns
boolean

true if a control key is currently down, false otherwise.

KeyInjectionScopeKt.isFnDown

default final boolean KeyInjectionScopeKt.isFnDown(@NonNull KeyInjectionScope receiver)

Verifies whether the function key is down.

Returns
boolean

true if the function key is currently down, false otherwise.

KeyInjectionScopeKt.isMetaDown

default final boolean KeyInjectionScopeKt.isMetaDown(@NonNull KeyInjectionScope receiver)

Verifies whether either of the meta keys are down.

Returns
boolean

true if a meta key is currently down, false otherwise.

KeyInjectionScopeKt.isShiftDown

default final boolean KeyInjectionScopeKt.isShiftDown(@NonNull KeyInjectionScope receiver)

Verifies whether either of the shift keys are down.

Returns
boolean

true if a shift key is currently down, false otherwise.

KeyInjectionScopeKt.pressKey

default final void KeyInjectionScopeKt.pressKey(
    @NonNull KeyInjectionScope receiver,
    @NonNull Key key,
    long pressDurationMillis
)

Holds down the given key for the given pressDurationMillis by sending a key down event, advancing the event time and sending a key up event.

If the given key is already down, an IllegalStateException will be thrown.

Parameters
@NonNull Key key

The key to be pressed down.

long pressDurationMillis

Duration of press in milliseconds.

KeyInjectionScopeKt.withKeyDown

default final void KeyInjectionScopeKt.withKeyDown(
    @NonNull KeyInjectionScope receiver,
    @NonNull Key key,
    @ExtensionFunctionType @NonNull Function1<@NonNull KeyInjectionScopeUnit> block
)

Executes the keyboard sequence specified in the given block, whilst holding down the given key. This key must not be used within the block.

If the given key is already down, an IllegalStateException will be thrown.

Parameters
@NonNull Key key

The key to be held down during injection of the block.

@ExtensionFunctionType @NonNull Function1<@NonNull KeyInjectionScopeUnit> block

Sequence of KeyInjectionScope methods to be injected with the given key down.

KeyInjectionScopeKt.withKeyToggled

default final void KeyInjectionScopeKt.withKeyToggled(
    @NonNull KeyInjectionScope receiver,
    @NonNull Key key,
    @ExtensionFunctionType @NonNull Function1<@NonNull KeyInjectionScopeUnit> block
)

Executes the keyboard sequence specified in the given block, in between presses to the given key. This key can also be used within the block, as long as it is not down at the end of the block.

If the given key is already down, an IllegalStateException will be thrown.

Parameters
@NonNull Key key

The key to be toggled around the injection of the block.

@ExtensionFunctionType @NonNull Function1<@NonNull KeyInjectionScopeUnit> block

Sequence of KeyInjectionScope methods to be injected with the given key down.

KeyInjectionScopeKt.withKeysDown

default final void KeyInjectionScopeKt.withKeysDown(
    @NonNull KeyInjectionScope receiver,
    @NonNull List<@NonNull Key> keys,
    @ExtensionFunctionType @NonNull Function1<@NonNull KeyInjectionScopeUnit> block
)

Executes the keyboard sequence specified in the given block, whilst holding down the each of the given keys. Each of the keys will be pressed down and released simultaneously. These keys must not be used within the block.

If any of the given keys are already down, an IllegalStateException will be thrown.

Parameters
@NonNull List<@NonNull Key> keys

List of keys to be held down during injection of the block.

@ExtensionFunctionType @NonNull Function1<@NonNull KeyInjectionScopeUnit> block

Sequence of KeyInjectionScope methods to be injected with the given keys down.

KeyInjectionScopeKt.withKeysToggled

default final void KeyInjectionScopeKt.withKeysToggled(
    @NonNull KeyInjectionScope receiver,
    @NonNull List<@NonNull Key> keys,
    @ExtensionFunctionType @NonNull Function1<@NonNull KeyInjectionScopeUnit> block
)

Executes the keyboard sequence specified in the given block, in between presses to the given keys. Each of the keys will be toggled simultaneously.These keys can also be used within the block, as long as they are not down at the end of the block.

If any of the given keys are already down, an IllegalStateException will be thrown.

Parameters
@NonNull List<@NonNull Key> keys

The keys to be toggled around the injection of the block.

@ExtensionFunctionType @NonNull Function1<@NonNull KeyInjectionScopeUnit> block

Sequence of KeyInjectionScope methods to be injected with the given keys down.