androidx.compose.ui.input.key

Interfaces

KeyInputModifierNode

Implement this interface to create a Modifier.Node that can intercept hardware Key events.
Cmn
SoftKeyboardInterceptionModifierNode

Implement this interface to create a Modifier.Node that can intercept hardware Key events before they are sent to the software keyboard.
Cmn

Classes

Key

Represents keys on a keyboard.
Cmn
android
KeyEvent

When a user presses a key on a hardware keyboard, a KeyEvent is sent to the item that is currently focused.
Cmn
KeyEventType

The type of Key Event.
Cmn
NativeKeyEvent

The native platform-specific keyboard key event.
Cmn
android

Type aliases

NativeKeyEvent

The native Android KeyEvent.
android

Top-level functions summary

Key
Key(nativeKeyCode: Int)
android

Extension functions summary

Modifier
Modifier.onInterceptKeyBeforeSoftKeyboard(
    onInterceptKeyBeforeSoftKeyboard: (KeyEvent) -> Boolean
)

Adding this modifier to the modifier parameter of a component will allow it to intercept hardware key events before they are sent to the software keyboard.
Cmn
Modifier
Modifier.onKeyEvent(onKeyEvent: (KeyEvent) -> Boolean)

Adding this modifier to the modifier parameter of a component will allow it to intercept hardware key events when it (or one of its children) is focused.
Cmn
Modifier
Modifier.onPreInterceptKeyBeforeSoftKeyboard(
    onPreInterceptKeyBeforeSoftKeyboard: (KeyEvent) -> Boolean
)

Adding this modifier to the modifier parameter of a component will allow it to intercept hardware key events before they are sent to the software keyboard.
Cmn
Modifier
Modifier.onPreviewKeyEvent(onPreviewKeyEvent: (KeyEvent) -> Boolean)

Adding this modifier to the modifier parameter of a component will allow it to intercept hardware key events when it (or one of its children) is focused.
Cmn

Extension properties summary

Boolean

Indicates whether the Alt key is pressed.
Cmn
android
Boolean

Indicates whether the Ctrl key is pressed.
Cmn
android
Boolean

Indicates whether the Meta key is pressed.
Cmn
android
Boolean

Indicates whether the Shift key is pressed.
Cmn
android
Key

The key that was pressed.
Cmn
android
Int

The native keycode corresponding to this Key.
android
KeyEventType

The type of key event.
Cmn
android
Int

The UTF16 value corresponding to the key event that was pressed.
Cmn
android

Top-level functions

Key

android 
fun Key(nativeKeyCode: Int): Key

Extension functions

onInterceptKeyBeforeSoftKeyboard

Cmn 
fun Modifier.onInterceptKeyBeforeSoftKeyboard(
    onInterceptKeyBeforeSoftKeyboard: (KeyEvent) -> Boolean
): Modifier

Adding this modifier to the modifier parameter of a component will allow it to intercept hardware key events before they are sent to the software keyboard. This can be used to intercept key input from a DPad, or physical keyboard connected to the device and is not applicable to input that is sent to the soft keyboard via spell check or autocomplete.

import androidx.compose.foundation.focusable
import androidx.compose.foundation.layout.Box
import androidx.compose.ui.Modifier
import androidx.compose.ui.input.key.Key
import androidx.compose.ui.input.key.key
import androidx.compose.ui.input.key.onKeyEvent
import androidx.compose.ui.input.key.onPreviewKeyEvent

// When the inner Box is focused, and the user presses a key, the key goes down the hierarchy
// and then back up to the parent. At any stage you can stop the propagation by returning
// true to indicate that you consumed the event.
Box(Modifier.onPreviewKeyEvent { keyEvent1 -> false }.onKeyEvent { keyEvent4 -> false }) {
    Box(
        Modifier.onPreviewKeyEvent { keyEvent2 -> false }
            .onKeyEvent { keyEvent3 -> false }
            .focusable()
    )
}
Parameters
onInterceptKeyBeforeSoftKeyboard: (KeyEvent) -> Boolean

This callback is invoked when the user interacts with the hardware keyboard. While implementing this callback, return true to stop propagation of this event. If you return false, the key event will be sent to this SoftKeyboardInterceptionModifierNode's parent, and ultimately to the software keyboard.

onKeyEvent

Cmn 
fun Modifier.onKeyEvent(onKeyEvent: (KeyEvent) -> Boolean): Modifier

Adding this modifier to the modifier parameter of a component will allow it to intercept hardware key events when it (or one of its children) is focused.

import androidx.compose.foundation.focusable
import androidx.compose.foundation.layout.Box
import androidx.compose.ui.Modifier
import androidx.compose.ui.input.key.Key
import androidx.compose.ui.input.key.key
import androidx.compose.ui.input.key.onKeyEvent
import androidx.compose.ui.input.key.onPreviewKeyEvent

// When the inner Box is focused, and the user presses a key, the key goes down the hierarchy
// and then back up to the parent. At any stage you can stop the propagation by returning
// true to indicate that you consumed the event.
Box(Modifier.onPreviewKeyEvent { keyEvent1 -> false }.onKeyEvent { keyEvent4 -> false }) {
    Box(
        Modifier.onPreviewKeyEvent { keyEvent2 -> false }
            .onKeyEvent { keyEvent3 -> false }
            .focusable()
    )
}
Parameters
onKeyEvent: (KeyEvent) -> Boolean

This callback is invoked when the user interacts with the hardware keyboard. While implementing this callback, return true to stop propagation of this event. If you return false, the key event will be sent to this onKeyEvent's parent.

onPreInterceptKeyBeforeSoftKeyboard

Cmn 
fun Modifier.onPreInterceptKeyBeforeSoftKeyboard(
    onPreInterceptKeyBeforeSoftKeyboard: (KeyEvent) -> Boolean
): Modifier

Adding this modifier to the modifier parameter of a component will allow it to intercept hardware key events before they are sent to the software keyboard. This can be used to intercept key input from a DPad, or physical keyboard connected to the device and is not applicable to input that is sent to the soft keyboard via spell check or autocomplete. This modifier is similar to onInterceptKeyBeforeSoftKeyboard, but allows a parent composable to intercept the hardware key event before any child.

import androidx.compose.foundation.focusable
import androidx.compose.foundation.layout.Box
import androidx.compose.ui.Modifier
import androidx.compose.ui.input.key.Key
import androidx.compose.ui.input.key.key
import androidx.compose.ui.input.key.onKeyEvent
import androidx.compose.ui.input.key.onPreviewKeyEvent

// When the inner Box is focused, and the user presses a key, the key goes down the hierarchy
// and then back up to the parent. At any stage you can stop the propagation by returning
// true to indicate that you consumed the event.
Box(Modifier.onPreviewKeyEvent { keyEvent1 -> false }.onKeyEvent { keyEvent4 -> false }) {
    Box(
        Modifier.onPreviewKeyEvent { keyEvent2 -> false }
            .onKeyEvent { keyEvent3 -> false }
            .focusable()
    )
}
Parameters
onPreInterceptKeyBeforeSoftKeyboard: (KeyEvent) -> Boolean

This callback is invoked when the user interacts with the hardware keyboard. It gives ancestors of a focused component the chance to intercept a KeyEvent. Return true to stop propagation of this event. If you return false, the key event will be sent to this SoftKeyboardInterceptionModifierNode's child. If none of the children consume the event, it will be sent back up to the root KeyInputModifierNode using the onKeyEvent callback, and ultimately to the software keyboard.

onPreviewKeyEvent

Cmn 
fun Modifier.onPreviewKeyEvent(onPreviewKeyEvent: (KeyEvent) -> Boolean): Modifier

Adding this modifier to the modifier parameter of a component will allow it to intercept hardware key events when it (or one of its children) is focused.

import androidx.compose.foundation.focusable
import androidx.compose.foundation.layout.Box
import androidx.compose.ui.Modifier
import androidx.compose.ui.input.key.Key
import androidx.compose.ui.input.key.key
import androidx.compose.ui.input.key.onKeyEvent
import androidx.compose.ui.input.key.onPreviewKeyEvent

// When the inner Box is focused, and the user presses a key, the key goes down the hierarchy
// and then back up to the parent. At any stage you can stop the propagation by returning
// true to indicate that you consumed the event.
Box(Modifier.onPreviewKeyEvent { keyEvent1 -> false }.onKeyEvent { keyEvent4 -> false }) {
    Box(
        Modifier.onPreviewKeyEvent { keyEvent2 -> false }
            .onKeyEvent { keyEvent3 -> false }
            .focusable()
    )
}
Parameters
onPreviewKeyEvent: (KeyEvent) -> Boolean

This callback is invoked when the user interacts with the hardware keyboard. It gives ancestors of a focused component the chance to intercept a KeyEvent. Return true to stop propagation of this event. If you return false, the key event will be sent to this onPreviewKeyEvent's child. If none of the children consume the event, it will be sent back up to the root KeyInputModifierNode using the onKeyEvent callback.

Extension properties

isAltPressed

Cmn android 
val KeyEvent.isAltPressed: Boolean

Indicates whether the Alt key is pressed.

import androidx.compose.foundation.focusable
import androidx.compose.foundation.layout.Box
import androidx.compose.ui.Modifier
import androidx.compose.ui.input.key.Key
import androidx.compose.ui.input.key.isAltPressed
import androidx.compose.ui.input.key.key
import androidx.compose.ui.input.key.onKeyEvent

Box(
    Modifier.onKeyEvent {
            if (it.isAltPressed && it.key == Key.A) {
                println("Alt + A is pressed")
                true
            } else {
                false
            }
        }
        .focusable()
)

isCtrlPressed

Cmn android 
val KeyEvent.isCtrlPressed: Boolean

Indicates whether the Ctrl key is pressed.

import androidx.compose.foundation.focusable
import androidx.compose.foundation.layout.Box
import androidx.compose.ui.Modifier
import androidx.compose.ui.input.key.Key
import androidx.compose.ui.input.key.isCtrlPressed
import androidx.compose.ui.input.key.key
import androidx.compose.ui.input.key.onKeyEvent

Box(
    Modifier.onKeyEvent {
            if (it.isCtrlPressed && it.key == Key.A) {
                println("Ctrl + A is pressed")
                true
            } else {
                false
            }
        }
        .focusable()
)

isMetaPressed

Cmn android 
val KeyEvent.isMetaPressed: Boolean

Indicates whether the Meta key is pressed.

import androidx.compose.foundation.focusable
import androidx.compose.foundation.layout.Box
import androidx.compose.ui.Modifier
import androidx.compose.ui.input.key.Key
import androidx.compose.ui.input.key.isMetaPressed
import androidx.compose.ui.input.key.key
import androidx.compose.ui.input.key.onKeyEvent

Box(
    Modifier.onKeyEvent {
            if (it.isMetaPressed && it.key == Key.A) {
                println("Meta + A is pressed")
                true
            } else {
                false
            }
        }
        .focusable()
)

isShiftPressed

Cmn android 
val KeyEvent.isShiftPressed: Boolean

Indicates whether the Shift key is pressed.

import androidx.compose.foundation.focusable
import androidx.compose.foundation.layout.Box
import androidx.compose.ui.Modifier
import androidx.compose.ui.input.key.Key
import androidx.compose.ui.input.key.isShiftPressed
import androidx.compose.ui.input.key.key
import androidx.compose.ui.input.key.onKeyEvent

Box(
    Modifier.onKeyEvent {
            if (it.isShiftPressed && it.key == Key.A) {
                println("Shift + A is pressed")
                true
            } else {
                false
            }
        }
        .focusable()
)

key

Cmn android 
val KeyEvent.key: Key

The key that was pressed.

import androidx.compose.foundation.focusable
import androidx.compose.foundation.layout.Box
import androidx.compose.ui.Modifier
import androidx.compose.ui.input.key.Key
import androidx.compose.ui.input.key.isAltPressed
import androidx.compose.ui.input.key.key
import androidx.compose.ui.input.key.onKeyEvent

Box(
    Modifier.onKeyEvent {
            if (it.isAltPressed && it.key == Key.A) {
                println("Alt + A is pressed")
                true
            } else {
                false
            }
        }
        .focusable()
)

nativeKeyCode

android 
val Key.nativeKeyCode: Int

The native keycode corresponding to this Key.

type

Cmn android 
val KeyEvent.type: KeyEventType

The type of key event.

import androidx.compose.foundation.focusable
import androidx.compose.foundation.layout.Box
import androidx.compose.ui.Modifier
import androidx.compose.ui.input.key.Key
import androidx.compose.ui.input.key.KeyEventType.Companion.KeyDown
import androidx.compose.ui.input.key.KeyEventType.Companion.KeyUp
import androidx.compose.ui.input.key.KeyEventType.Companion.Unknown
import androidx.compose.ui.input.key.key
import androidx.compose.ui.input.key.onKeyEvent
import androidx.compose.ui.input.key.type

Box(
    Modifier.onKeyEvent {
            when (it.type) {
                KeyUp -> println("KeyUp Pressed")
                KeyDown -> println("KeyUp Pressed")
                Unknown -> println("Unknown key type")
                else -> println("New KeyType (for future use)")
            }
            false
        }
        .focusable()
)

utf16CodePoint

Cmn android 
val KeyEvent.utf16CodePoint: Int

The UTF16 value corresponding to the key event that was pressed. The unicode character takes into account any meta keys that are pressed (eg. Pressing shift results in capital alphabets). The UTF16 value uses the U+n notation[http://www.unicode.org/reports/tr27/#notation] of the Unicode Standard.

An Int is used instead of a Char so that we can support supplementary characters. The Unicode Standard allows for characters whose representation requires more than 16 bits. The range of legal code points is U+0000 to U+10FFFF, known as Unicode scalar value.

The set of characters from U+0000 to U+FFFF is sometimes referred to as the Basic Multilingual Plane (BMP). Characters whose code points are greater than U+FFFF are called supplementary characters. In this representation, supplementary characters are represented as a pair of char values, the first from the high-surrogates range, (\uD800-\uDBFF), the second from the low-surrogates range (\uDC00-\uDFFF).