KeyInjectionScope


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 functions

Boolean
isKeyDown(key: Key)

Checks if the given key is down.

Cmn
Unit
keyDown(key: Key)

Sends a key down event for the given key.

Cmn
Unit
keyUp(key: Key)

Sends a key up event for the given key.

Cmn

Public properties

Boolean

Indicates whether caps lock is on or not.

Cmn
Boolean

Indicates whether num lock is on or not.

Cmn
Boolean

Indicates whether scroll lock is on or not.

Cmn

Extension functions

Unit
KeyInjectionScope.pressKey(key: Key, pressDurationMillis: Long)

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.

Cmn
Unit

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

Cmn
Unit

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

Cmn
Unit

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

Cmn
Unit

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

Cmn

Extension properties

Boolean

Verifies whether either of the alt keys are down.

Cmn
Boolean

Verifies whether either of the control keys are down.

Cmn
Boolean

Verifies whether the function key is down.

Cmn
Boolean

Verifies whether either of the meta keys are down.

Cmn
Boolean

Verifies whether either of the shift keys are down.

Cmn

Inherited functions

From androidx.compose.ui.unit.Density
open Int

Convert Dp to Int by rounding

Cmn
open Int

Convert Sp to Int by rounding

Cmn
open Dp

Convert an Int pixel value to Dp.

Cmn
open Dp

Convert a Float pixel value to a Dp

Cmn
open DpSize

Convert a Size to a DpSize.

Cmn
open Float

Convert Dp to pixels.

Cmn
open Float

Convert Sp to pixels.

Cmn
open Rect

Convert a DpRect to a Rect.

Cmn
open Size

Convert a DpSize to a Size.

Cmn
open TextUnit

Convert an Int pixel value to Sp.

Cmn
open TextUnit

Convert a Float pixel value to a Sp

Cmn
From androidx.compose.ui.unit.FontScaling
open Dp

Convert Sp to Dp.

Cmn
open TextUnit

Convert Dp to Sp.

Cmn
From androidx.compose.ui.test.InjectionScope
Unit
advanceEventTime(durationMillis: Long)

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

Cmn
open Offset

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

Cmn

Inherited properties

From androidx.compose.ui.unit.Density
Float

The logical density of the display.

Cmn
From androidx.compose.ui.unit.FontScaling
Float

Current user preference for the scaling factor for fonts.

Cmn
From androidx.compose.ui.test.InjectionScope
open 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.

Cmn
open 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.

Cmn
open 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.

Cmn
open 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.

Cmn
open 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.

Cmn
open 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.

Cmn
open 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.

Cmn
open 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.

Cmn
open 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.

Cmn
open Long

The default time between two successive events.

Cmn
open Int

The height of the node in px.

Cmn
open 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.

Cmn
open 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.

Cmn
open 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.

Cmn
open 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.

Cmn
open 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.

Cmn
open 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.

Cmn
ViewConfiguration

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

Cmn
IntSize

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

Cmn
open Int

The width of the node in px.

Cmn

Public functions

isKeyDown

fun isKeyDown(key: Key): Boolean

Checks if the given key is down.

Parameters
key: Key

The key to be checked.

Returns
Boolean

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

keyDown

fun keyDown(key: Key): Unit

Sends a key down event for the given key.

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

Parameters
key: Key

The key to be pressed down.

keyUp

fun keyUp(key: Key): Unit

Sends a key up event for the given key.

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

Parameters
key: Key

The key to be released.

Public properties

isCapsLockOn

val isCapsLockOnBoolean

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

isNumLockOn

val isNumLockOnBoolean

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

val isScrollLockOnBoolean

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

Extension functions

pressKey

fun KeyInjectionScope.pressKey(
    key: Key,
    pressDurationMillis: Long = DefaultKeyPressDurationMillis
): Unit

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
key: Key

The key to be pressed down.

pressDurationMillis: Long = DefaultKeyPressDurationMillis

Duration of press in milliseconds.

withKeyDown

fun KeyInjectionScope.withKeyDown(key: Key, block: KeyInjectionScope.() -> Unit): Unit

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
key: Key

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

block: KeyInjectionScope.() -> Unit

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

withKeyToggled

fun KeyInjectionScope.withKeyToggled(key: Key, block: KeyInjectionScope.() -> Unit): Unit

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
key: Key

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

block: KeyInjectionScope.() -> Unit

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

withKeysDown

fun KeyInjectionScope.withKeysDown(keys: List<Key>, block: KeyInjectionScope.() -> Unit): Unit

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
keys: List<Key>

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

block: KeyInjectionScope.() -> Unit

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

withKeysToggled

fun KeyInjectionScope.withKeysToggled(keys: List<Key>, block: KeyInjectionScope.() -> Unit): Unit

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
keys: List<Key>

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

block: KeyInjectionScope.() -> Unit

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

Extension properties

isAltDown

val KeyInjectionScope.isAltDownBoolean

Verifies whether either of the alt keys are down.

Returns
Boolean

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

isCtrlDown

val KeyInjectionScope.isCtrlDownBoolean

Verifies whether either of the control keys are down.

Returns
Boolean

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

isFnDown

val KeyInjectionScope.isFnDownBoolean

Verifies whether the function key is down.

Returns
Boolean

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

isMetaDown

val KeyInjectionScope.isMetaDownBoolean

Verifies whether either of the meta keys are down.

Returns
Boolean

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

isShiftDown

val KeyInjectionScope.isShiftDownBoolean

Verifies whether either of the shift keys are down.

Returns
Boolean

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