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

Cmn 
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

Cmn 
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

Cmn 
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

Cmn
Added in 1.2.0
val isCapsLockOn: Boolean

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

Cmn
Added in 1.2.0
val isNumLockOn: Boolean

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

Cmn
Added in 1.2.0
val isScrollLockOn: Boolean

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

Cmn 
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

Cmn 
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

Cmn 
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

Cmn 
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

Cmn 
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

Cmn 
val KeyInjectionScope.isAltDown: Boolean

Verifies whether either of the alt keys are down.

Returns
Boolean

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

isCtrlDown

Cmn 
val KeyInjectionScope.isCtrlDown: Boolean

Verifies whether either of the control keys are down.

Returns
Boolean

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

isFnDown

Cmn 
val KeyInjectionScope.isFnDown: Boolean

Verifies whether the function key is down.

Returns
Boolean

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

isMetaDown

Cmn 
val KeyInjectionScope.isMetaDown: Boolean

Verifies whether either of the meta keys are down.

Returns
Boolean

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

isShiftDown

Cmn 
val KeyInjectionScope.isShiftDown: Boolean

Verifies whether either of the shift keys are down.

Returns
Boolean

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