Some thoughts on keyboard shortcuts on Android

When you think about which cool new feature you may want to add to your app, you probably won't immediately shout Hell yes, my app desperately needs keyboard shortcut support. I mean, how often do we use physical keyboards with our mobile devices anyway? The days of Android phones having a keyboard built in are long gone, aren't they?

Well, not really. Chromebooks run Android apps. Many Android tablets are sold with physical keyboards. And Android's desktop mode, which hopefully will gain some traction eventually, allows us to connect our smartphone to big screens. This setup only makes sense when you also pair a mouse and keyboard. So, keyboards most certainly are not a thing of the past. They may not have been very common on Android in recent years, but other platforms have always relied on them. And still do. Why? Because physical keyboards are productivity boosters.

That's where keyboard shortcuts come in. They allow us to trigger an action by simultaneously pressing a few keys. Prime examples are the clipboard-related commands Cut (Control-X), Copy (Control-C), and Paste (Control-V). And yes, it's Command on the Mac.

Have you noticed that I said command? Keyboard shortcuts allow us to trigger an action or command fast. That's why they are called shortcuts. The important point here is: there should always be another way of executing that command. Typically, this other way also advertises the corresponding keyboard shortcut. Take a look:

When we open a menu, we see the command and its associated shortcut, which helps us remember it (eventually). Actually using the shortcut helps us remember it even better, but that's another topic.

But Android doesn't have a menu bar

Traditional menu bars work best with a mouse and a mouse pointer. That's why Android does not have one. However, Android most certainly allows apps to show menus. And these can contain keyboard shortcuts, too. We'll tackle this shortly. But first, let me show you how to define and consume keyboard shortcuts on an app level. The source code of my sample app KeyboardShortcutDemo is available on GitHub. It is a Compose Multiplatform project that targets Android, IOS, and the Desktop. In this article, I focus on Android.

Global shortcuts

Working with global keyboard shortcuts consists of two steps:

• Defining the shortcuts
• Receiving shortcut activations

Both can be implemented on an Activity level. Here's how to define a keyboard shortcut:

private lateinit var listKeyboardShortcutInfo: List<KeyboardShortcutInfo>

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    enableEdgeToEdge()
    listKeyboardShortcutInfo = globalShortcuts.map { shortcut ->
        KeyboardShortcutInfo(
            shortcut.label,
            shortcut.keyAsString.first(),
            shortcut.modifiers()
        )
    }
    …
    setContent {
        val hardKeyboardHidden by
                hardKeyboardHiddenFlow.collectAsStateWithLifecycle()
        val systemInDarkMode = isSystemInDarkTheme()
        var darkMode by rememberSaveable {
                mutableStateOf(systemInDarkMode)
        }
        MaterialTheme(colorScheme = if (darkMode)
                            darkColorScheme()
                        else
                            lightColorScheme()) {
            MainScreen(
                listKeyboardShortcuts = globalShortcuts,
                hardKeyboardHidden = hardKeyboardHidden ==
                    Configuration.HARDKEYBOARDHIDDEN_YES,
                darkMode = darkMode,
                showKeyboardShortcuts = {
                    requestShowKeyboardShortcuts()
                },
                toggleDarkMode = { darkMode = !darkMode }
            )
        }
    }
}

override fun onProvideKeyboardShortcuts(
    data: MutableList<KeyboardShortcutGroup>,
    menu: Menu?,
    deviceId: Int
) {
    super.onProvideKeyboardShortcuts(data, menu, deviceId)
    data.add(KeyboardShortcutGroup(
        getString(R.string.general), listKeyboardShortcutInfo)
    )
}

In onCreate(), we populate a list of KeyboardShortcutInfo instances and, inside onProvideKeyboardShortcuts(), add it to data, which has been passed to us by Android. Please notice the Menu which will usually be null in a Compose-only app.

But what is globalShortcuts? It's defined in GlobalShortcuts.kt.

val globalShortcuts = runBlocking {
    listOf(
        KeyboardShortcut(
            label = getString(Res.string.say_hello),
            key = Key.H,
            keyAsString = "H",
            ctrl = true
        )
    )
}

KeyboardShortcut is a cross-platform generalisation of KeyboardShortcutInfo, which I defined to be able to refer to keyboard shortcuts beyond Android activities. Have you spotted that I pass globalShortcuts to MainScreen()?

Next, let's look at how to receive keyboard shortcut presses.

override fun onKeyShortcut(
    keyCode: Int, event: KeyEvent
): Boolean {
    listKeyboardShortcutInfo.forEachIndexed { index, info ->
        if (info.keycode == keyCode &&
            event.hasModifiers(info.modifiers)) {
            globalShortcuts[index].triggerAction()
            return true
        }
    }
    return super.onKeyShortcut(keyCode, event)
}

The onKeyShortcut() function receives a keyCode and an event. Using both, it is simple to check if a shortcut defined by our app has been pressed. If this is the case, we return true, otherwise super.onKeyShortcut(keyCode, event).

But what does shortcut.triggerAction() do? Here's how it is implemented:

data class KeyboardShortcut(
    val label: String,
    val key: Key,
    val keyAsString: String,
    val ctrl: Boolean = false,
    val meta: Boolean = false,
    val alt: Boolean = false,
    val shift: Boolean = false,
) {
    private val channel = Channel<Unit>(Channel.CONFLATED)
    val flow = channel.receiveAsFlow()

    fun triggerAction() {
        channel.trySend(Unit)
    }

    val shortcutAsText: String
        get() {
            val parts = mutableListOf<String>()
            if (ctrl) {
                parts.add("Ctrl")
            }
            if (meta) {
                parts.add("Meta")
            }
            if (alt) {
                parts.add("Alt")
            }
            if (shift) {
                parts.add("Shift")
            }
            parts.add(keyAsString)
            return parts.joinToString("+")
        }
}

Since KeyboardShortcutInfo is specific to Android, it makes sense to provide an alternative that we can use across platforms. But even on Android we need a mechanism that allows us to trigger and consume keyboard shortcuts in a modern Kotlin way.

That's what KeyboardShortcut is for. label and shortcutAsText will be used by composables. flow allows us to react upon invocations of the keyboard shortcut. Finally, triggerAction(): as its name implies, it triggers an action by trying to send something to a channel. Kindly recall that we invoke this function inside onKeyShortcut(). What does this mean? Once we have determined that a keyboard shortcut has been invoked by pressing the corresponding keys, we make sure to notify everyone interested in the event. We'll, by the way, also call this function from inside our Compose hierarchy. I'll show you shortly.

But before that, let's take a user's perspective. Android and Chrome OS can display a list of available shortcuts. On most devices, this help screen can be opened by pressing Meta-/, which is known as Search-/ on Chromebooks.

Since not all users may be familiar with this system shortcut, consider allowing the user to summon it from within your app. Kindly recall what my sample app does inside setContent {}:

setContent {
    …
    MaterialTheme(colorScheme = …) {
        MainScreen(
            listKeyboardShortcuts = globalShortcuts,
            hardKeyboardHidden = …,
            darkMode = darkMode,
            showKeyboardShortcuts = {
                requestShowKeyboardShortcuts()
            },
            …
        )
    }
}

requestShowKeyboardShortcuts() (this method is defined in android.app.Activity) requests the Keyboard Shortcuts screen to show up. This will trigger onProvideKeyboardShortcuts() to retrieve the shortcuts for the foreground activity. KeyboardShortcutDemo just shows a Show keyboard shortcuts button. Certainly, there are more clever places to incorporate it.

Let's recap. I showed you how to provide keyboard shortcuts on an Activity level. We can even summon a system dialog that lists them. But how do we react to shortcut presses and how do we visualise the shortcut in our user interface? Finally, how do we mention the shortcut to the user so that they can remember it, similar to what I explained regarding classic menu bars?

@Composable
fun MainScreen(
    listKeyboardShortcuts: List<KeyboardShortcut>,
    hardKeyboardHidden: Boolean,
    darkMode: Boolean,
    showKeyboardShortcuts: () -> Unit,
    toggleDarkMode: () -> Unit,
) {
    var snackbarMessage by remember { mutableStateOf("") }
    val helloMessage = stringResource(Res.string.hello)
    LaunchedEffect(listKeyboardShortcuts) {
        listKeyboardShortcuts.forEach { shortcut ->
            launch {
                shortcut.flow.collectLatest {
                    snackbarMessage = helloMessage
                }
            }
        }
    }
    KeyboardShortcutDemo(
        hardwareKeyboardHidden = hardKeyboardHidden,
        snackbarMessage = snackbarMessage,
        shortcuts = listKeyboardShortcuts,
        darkMode = darkMode,
        showKeyboardShortcuts = showKeyboardShortcuts,
        clearSnackbarMessage = { snackbarMessage = "" },
        toggleDarkMode = toggleDarkMode,
    )
}

When a keyboard shortcut is invoked, the sample app shows a snackbar message. We keep the text in snackbarMessage. listKeyboardShortcuts is the list of keyboard shortcuts. KeyboardShortcutDemo() (this composable is invoked from MainScreen()) uses it to populate a menu. hardKeyboardHidden is used to determine if a physical keyboard is ready to use. Kindly just ignore it, I will detail on this in a follow-up article.

So far, I still haven't explained how we react to shortcut presses. The magic happens inside LaunchedEffect(). For each keyboard shortcut, we invoke shortcut.flow.collectLatest {}. In my example, we always set the snackbar message. Real-world apps would certainly provide different implementations, depending on the shortcut.

Menus and keyboard shortcuts in Jetpack Compose

When looking at the KeyboardShortcutDemo() composable, kindly recall the screenshot of the app to understand its structure:

• an app bar at the top, including the app name and a menu
• a text field (not further discussed in this article)
• a switch with an accompanying label (not further discussed in this article)
• a button to open the keyboard shortcuts dialog
• (not visible in the screenshot) a text when no physical keyboard is ready to use

fun KeyboardShortcutDemo(
    hardwareKeyboardHidden: Boolean,
    shortcuts: List<KeyboardShortcut>,
    snackbarMessage: String,
    darkMode: Boolean,
    showKeyboardShortcuts: () -> Unit,
    clearSnackbarMessage: () -> Unit,
    toggleDarkMode: () -> Unit,
) {
    val snackBarHostState = remember { SnackbarHostState() }
    var showMenu by remember { mutableStateOf(false) }
    …
    Scaffold(
        modifier = Modifier.fillMaxSize()
        …,
        topBar = {
            TopAppBar(
                title = {
                    Text(stringResource(Res.string.app_name)) 
                },
                actions = {
                    IconButton(onClick = { showMenu = !showMenu }) {
                        Icon(
                            imageVector = Icons.Filled.MoreVert,
                            contentDescription = stringResource(
                                Res.string.more_options)
                        )
                    }
                    DropdownMenu(
                        expanded = showMenu,
                        onDismissRequest = { showMenu = false }
                    ) {
                        shortcuts.forEach { shortcut ->
                            DropdownMenuItemWithShortcut(
                                text = shortcut.label,
                                shortcut = shortcut.shortcutAsText,
                                onClick = {
                                    showMenu = false
                                    shortcut.triggerAction()
                                }
                            )
                        }
                    }
                }
            )
        },
        snackbarHost = { SnackbarHost(snackBarHostState) }
    ) { innerPadding ->
        Box(
            modifier = Modifier
                …
                .padding(innerPadding)
                .fillMaxSize(),
            contentAlignment = Alignment.Center
        ) {
            …
            Column(
                horizontalAlignment = Alignment.CenterHorizontally,
                verticalArrangement = Arrangement.spacedBy(16.dp)
            ) {
                …
                Button(
                    onClick = showKeyboardShortcuts,
                ) {
                    TextWithUnderlinedChar(stringResource(
                        Res.string.show_keyboard_shortcuts))
                }
            }
            if (hardwareKeyboardHidden) {
                Text(
                    text = stringResource(
                        Res.string.hardware_keyboard_hidden),
                    modifier = Modifier.align(Alignment.BottomCenter)
                                       .safeContentPadding(),
                    style = MaterialTheme.typography.headlineSmall,
                    color = MaterialTheme.colorScheme.error
                )
            }
        }
        LaunchedEffect(snackbarMessage) {
            if (snackbarMessage.isNotBlank()) {
                snackBarHostState.showSnackbar(snackbarMessage)
                clearSnackbarMessage()
            }
        }
    }
}

The menu will contain as many items as shortcuts has elements. When an element is selected, a snack bar will appear. That's because onClick() of each DropdownMenuItemWithShortcut() invokes shortcut.triggerAction(). The onClick() of the button just invokes the showKeyboardShortcuts lambda.

That's been quite a bit to digest, right? Fortunately, there is only one piece of the puzzle missing. What is DropdownMenuItemWithShortcut()?

Unlike the traditional Activity-level options menu, DropDownMenuItem() (which comes with Jetpack Compose) does not support shortcuts out of the box. This means we need to somehow add this to the Text() composable. The most basic approach is to just add the shortcut at the end of the String. While this works, this does not look particularly pleasing. Besides, that's not how we build UIs with Jetpack Compose.

Here's a composable that provides a DropDownMenuItem() with a shortcut at the end of the text:

@Composable
fun DropdownMenuItemWithShortcut(
    text: String,
    shortcut: String?,
    onClick: () -> Unit,
    modifier: Modifier = Modifier
) {
    DropdownMenuItem(
        text = { ShortcutText(text = text, shortcut = shortcut) },
        onClick = onClick,
        modifier = modifier
    )
}

@Composable
fun ShortcutText(
    text: String,
    shortcut: String?,
) {
    Row(
        modifier = Modifier.fillMaxWidth(),
        horizontalArrangement = Arrangement.SpaceBetween
    ) {
        Text(
            text = text,
            modifier = Modifier.alignByBaseline()
        )
        shortcut?.let { shortcut ->
            Text(
                text = shortcut,
                style = MaterialTheme.typography.bodyMedium,
                color = MaterialTheme.colorScheme.onSurface
                            .copy(alpha = 0.6f),
                modifier = Modifier
                    .alignByBaseline()
                    .padding(start = 16.dp)
            )
        }
    }
}

Have you spotted the alignByBaseline() modifier? While most examples using Row() just vertically center the children, this is a nightmare from a UX perspective. The texts have to be baseline-aligned to be readable nicely.

That looks pretty nice, doesn't it?

You may be wondering where the shortcut text is created. In the KeyboardShortcutDemo() composable, it's passed like this:

shortcuts.forEach { shortcut ->
    DropdownMenuItemWithShortcut(
        text = shortcut.label,
        shortcut = shortcut.shortcutAsText,
        onClick = {
            showMenu = false
            shortcut.triggerAction()
        }
    )
}

So, what is shortcut.shortcutAsText? Kindly recall my custom KeyboardShortcut class:

data class KeyboardShortcut(
    val label: String,
    val key: Key,
    val keyAsString: String,
    val ctrl: Boolean = false,
    val meta: Boolean = false,
    val alt: Boolean = false,
    val shift: Boolean = false,
) {
    …

    val shortcutAsText: String
        get() {
            val parts = mutableListOf<String>()
            if (ctrl) {
                parts.add("Ctrl")
            }
            if (meta) {
                parts.add("Meta")
            }
            if (alt) {
                parts.add("Alt")
            }
            if (shift) {
                parts.add("Shift")
            }
            parts.add(keyAsString)
            return parts.joinToString("+")
        }
}

I was surprised to learn that there seems to be no public-facing API in Android that provides a locale-aware String representation of KeyboardShortcutInfo. However, a function that achieves this must be around somewhere, since the often-mentioned keyboard shortcuts dialog needs something similar, too. Since I couldn't find one, I decided to write my own. Checking the modifiers and the key code isn't too difficult, but there are some nuances that need to be taken into account. For example, on Chromebooks, Meta should be Search or some corresponding symbol. I omitted this for brevity. In a real-world app, you would want to take the string from the resources and handle device-specific variations.

Conclusion

Adding keyboard shortcut support to your app may not sound particularly fancy at first sight, but in my opinion brings a lot of added value. Do your apps already support them? How did you handle the visual representation of the shortcuts? Please share your thoughts in the comments.