Keyboard Shortcuts Sample

English | Español

A clean Android sample app that shows how to implement keyboard shortcuts in a modern Jetpack Compose app.

This project is meant to be a small public reference for Android developers who want to support:

• app-level keyboard shortcuts
• screen-level keyboard shortcuts
• Android Keyboard Shortcuts Helper integration
• a single-Activity architecture with Navigation Compose

Overview

The sample uses the official Android APIs for keyboard shortcuts:

• Activity.onKeyShortcut(...) to execute shortcuts
• Activity.onProvideKeyboardShortcuts(...) to publish shortcuts to the system helper
• Activity.requestShowKeyboardShortcuts() to open the helper programmatically

Compose screens register their local shortcuts through a shared registry. The same registry is also used to build KeyboardShortcutGroup objects for the Android system helper.

What This Sample Shows

• A single-Activity Compose app with Navigation Compose
• Global app shortcuts that work from any screen
• Local screen shortcuts that are active only while a screen is visible
• Screen shortcuts taking precedence over app shortcuts when the same key combination is reused
• Shortcut execution and system discoverability driven by the same definitions

Included Shortcuts

App shortcuts

• Ctrl + 1 -> Go to Blue screen
• Ctrl + 2 -> Go to Green screen
• Ctrl + 0 -> Go to Home

Blue screen shortcuts

• Ctrl + B -> Toggle blue shade
• Ctrl + H -> Go Home

Green screen shortcuts

• Ctrl + G -> Toggle green shade
• Ctrl + H -> Go Home

Why This Sample Exists

Many keyboard shortcut examples stop at raw key handling. This sample focuses on the more complete Android story:

• executing shortcuts with official APIs
• publishing shortcuts to Android Keyboard Shortcuts Helper
• keeping global and screen-specific shortcuts organized in a readable structure
• avoiding restricted APIs and unnecessary workarounds

Architecture

The app keeps the structure intentionally small and explicit:

com.haynlo.keyboardshortcuts
├── MainActivity.kt
├── navigation
│   ├── AppDestinations.kt
│   └── AppNavHost.kt
├── shortcuts
│   └── ShortcutRegistry.kt
└── ui
    ├── BlueScreen.kt
    ├── GreenScreen.kt
    ├── HomeScreen.kt
    ├── common
    │   └── DemoScreen.kt
    ├── registration
    │   ├── AppShortcutsEffect.kt
    │   └── ScreenShortcutsEffect.kt
    └── theme
        ├── Color.kt
        └── Theme.kt

How It Works

1. Activity integrates with Android system APIs

MainActivity is the bridge between Android and Compose:

• onKeyShortcut(...) asks the registry to resolve and execute the active shortcut
• onProvideKeyboardShortcuts(...) asks the registry to publish the active shortcut groups

2. App shortcuts are registered once

AppShortcutsEffect registers global navigation shortcuts from AppNavHost.

3. Screens register local shortcuts while visible

ScreenShortcutsEffect registers screen-specific shortcuts from each screen.

When a screen leaves composition, its local shortcuts are removed automatically.

4. Screen shortcuts override app shortcuts

ShortcutRegistry resolves screen groups before app groups, so local shortcuts win when both match the same combination.

Keyboard Events vs System Shortcuts

For simple key handling inside a focused composable, Modifier.onKeyEvent can be enough.

This sample focuses on a different use case: discoverable shortcuts that should be integrated with Android Keyboard Shortcuts Helper. For that reason, it uses Activity.onKeyShortcut(...) and onProvideKeyboardShortcuts(...) instead.

Running The Sample

Requirements

• Android Studio
• Android SDK
• minSdk 25

Build

./gradlew build

Notes

• UI strings are available in English and Spanish.
• The sample keeps the UI intentionally minimal so the shortcut behavior stays easy to follow.
• The project avoids dispatchKeyShortcutEvent() and does not use @SuppressLint("RestrictedApi").

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.