Keyboard events

Events in a focused component

This approach implies that pressing a key on a keyboard triggers event handlers for the currently focused component.

A typical scenario is to define keyboard handlers for active controls like TextField. To intercept a key event before it triggers the default action, you can use both the onKeyEvent and onPreviewKeyEvent modifiers. With the onKeyEvent modifier, you can handle an individual keystroke, while onPreviewKeyEvent is preferable for defining shortcuts.

The following sample demonstrates TextField interactions with different actions depending on which key is pressed while you hold Ctrl:

modifier = Modifier.onPreviewKeyEvent { when
 {...}

Gif

Events in a window scope

To define keyboard event handlers that are always active within the current window, use the onPreviewKeyEvent and onKeyEvent parameters, available for the Window, singleWindowApplication, and Dialog functions. They differ in how the event is dispatched when it is not consumed: onPreviewKeyEvent dispatches the event to its first child, and onKeyEvent dispatches the event to the composable's parent. Typically, onPreviewKeyEvent is preferred for intercepting events, as it allows implementing even screen-wide keyboard shortcuts.

The following sample demonstrates window interactions such as closing a pop-up dialog by pressing Escape and changing the window content by pressing the Ctrl+Shift+C shortcut:

if (it.isCtrlPressed && it.isShiftPressed && it.key == Key.C &&
 {...}

Gif

What's next?

• See the API reference for details.

• Explore the tutorials about other desktop components.