androidmenukeyboard-shortcutsandroid-hardware-keyboard

Register hardware keyboard shortcuts in Android's help menu

Android supports external hardware keyboards as input, which may send keyboard shortcuts (e.g. Ctrl+A) in which there are some ways to program my app to accept shortcuts from external keyboards (e.g. like this: Custom keyboard shortcuts).

I came across this keyboard shortcut "help" screen in Android (activated by pressing OS + /) (see picture below)

Generic shortcut help screen App specific keyboard shortcut help screen

and noticed some apps have some keyboard shortcuts directly registered within the system shortcuts help screen(these screens are not provided by the app, they can be found by pressing OS + /).

So far, the apps that I see that have this feature are:

I cannot find any way to register my keyboard shortcuts in my app programmatically such that they will be recognised by the system. How can I possibly implement it in my app?

I do know iOS/iPadOS has such a feature.

Perhaps Android does have such a feature too? It seems like it would be quite useful to app developers and users, not sure why it's not documented at all in Android Developer documentation.

Thanks.

Solution

  • This feature is not documented in the Android Developer website, so I had to search around.

    Since it is supported by AOSP, this is not a proprietary method/function by Google. No root is required on your users' devices.

    Since this feature is available in Chromium-based browsers, I decided to check up the open-source Chromium Android source code (a mirror on GitHub is available here by someone: https://github.com/kuoruan/Chromium-Android) and I have discovered how this feature is implemented.

    The relevant lines are here:

    In any Activity, you can override the method onProvideKeyboardShortcuts.
    It provides 3 parameters: data, menu, and deviceId, in which we only need data here.

    Here is the method signature:

    fun onProvideKeyboardShortcuts(
        data: MutableList<KeyboardShortcutGroup>?,
        menu: Menu?,
        deviceId: Int
    )

    This only works on API 24 (Android Nougat) and above.

    data is a mutable list of KeyboardShortcutGroup, which is a group of keyboard shortcuts.

    So, you can have multiple groups containing multiple shortcuts, useful for grouping the shortcuts for your users.

    To register your shortcuts,

    1. Create a KeyboardShortcutGroup. This is required to store and group your keyboard shortcuts together. The class accepts a CharSequence as a parameter for the name of the group, so you have to use getString(R.string.your_resource) for string resources.
    val keyboardShortcutGroup = KeyboardShortcutGroup(/* the name of your group here: */ "Test Group")
    1. Define your keyboard shortcuts. Keyboard shortcuts are defined using KeyboardShortcutInfo objects, which accepts 3 parameters in it's constructor - a label, the key(e.g. A/ Z/ 8/ 9), and the modifier key.

      A single keyboard shortcut is created this way:
    KeyboardShortcutInfo("Shortcut One" /*label*/, KeyEvent.KEYCODE_Z/*key*/, KeyEvent.META_ALT_ON/*modifier*/)

    You need to pass in key codes into the constructor for the key and the modifier key.
    The key and modifier key must be passed in seperately.

    Here are the list of available key codes: https://developer.android.com/reference/android/view/KeyEvent#KEYCODE_0 (See those prefixed with KEYCODE)

    Based on testing, the modifier keys which work are:

    META_SYM_ON may work(have not tested yet), but Caps Lock doesn't work.

    To combine modifier keys,
    in Java, use the bitwise operator: KeyEvent.META_ALT_LEFT_ON | KeyEvent.META_CTRL_ON
    in Kotlin, use the or operator: KeyEvent.META_ALT_LEFT_ON or KeyEvent.META_CTRL_ON

    1. To this KeyboardShortcutGroup, add shortcuts using addItem.
    keyboardShortcutGroup.addItem(shortcut /* <-- the shortcut created earlier */)
    1. Add your KeyboardShortcutGroup to data
    data.add(keyboardShortcutGroup)

    Your code should look like this:

        override fun onProvideKeyboardShortcuts(
        data: MutableList<KeyboardShortcutGroup>?,
        menu: Menu?,
        deviceId: Int
    ) {
        super.onProvideKeyboardShortcuts(data, menu, deviceId)

        // Requires API 24
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.N) {

            val keyboardShortcutGroup = KeyboardShortcutGroup("Test Group")
            keyboardShortcutGroup.addItem(KeyboardShortcutInfo("Shortcut One", KeyEvent.KEYCODE_Z, KeyEvent.META_ALT_ON))
            data?.add(keyboardShortcutGroup)
        }
    }

    You should see the end result: menu screenshot

    You can use this to inform users of available shortcuts. Note that this does not implement them, it merely adds a listing to the Android shortcut menu.