shortcut_atlas library

Enterprise keyboard shortcuts for Flutter desktop.

Declare a ShortcutCommand once and it becomes the single source of truth for both dispatch (real Flutter Shortcuts/Actions/Focus) and a contextual cheat-sheet HUD revealed by holding Alt (peek-then-act).

Install ShortcutAtlas at the root (via MaterialApp.builder), wrap regions in ShortcutScope, and use command / primary to declare shortcuts.

Classes

ActivatorCodec
Serializes a ShortcutActivator to a JSON-able map and back, so user re-bindings can be persisted. Keys are stored by stable LogicalKeyboardKey.keyId and restored with LogicalKeyboardKey.findKeyByKeyId.
ActivatorSignature
A normalized, comparable identity for a ShortcutActivator, used to dedup bindings that resolve to the same chord (so the HUD never shows two rows for what is really one shortcut). PlatformActivator is resolved for the current platform first, so primary(keyS) dedups with SingleActivator(keyS, …).
ActiveBinding
A command resolved against the live focus context: whether it is currently enabled, its dedup signature, and its distance from the focused node (used only for shadow precedence, never for display order).
AltHoldClock
Injectable timer factory so the hold threshold is deterministic under test.
AltHoldDetector
A single, non-consuming HardwareKeyboard handler implementing peek-then-act: hold Alt alone past a threshold to reveal, release (or press any other key) to dismiss.
AltHoldOptions
AtlasActionButton
A button whose onPressed and a keyboard shortcut share one Intent and one enablement gate.
AtlasCommandPalette
The Cmd/Ctrl+K command palette layer. Reads controller.paletteOpen and, when open, shows a searchable, keyboard-navigable list of the currently active commands. Invoking one routes through the same dispatch path a keypress would use.
AtlasConfig
Immutable configuration for ShortcutAtlas.
AtlasController
Owns the shortcut registry, the live HUD view-model, and the contextual active-set computation. Created once by ShortcutAtlas.
AtlasLocalizations
Localized words used when rendering shortcut glyphs on non-Apple platforms (Apple platforms use the literal symbols ⌃⌥⇧⌘ instead of words).
AtlasPaletteEntry
One row in the command palette: a resolved command and whether it can be invoked right now.
AtlasPlatform
Platform-awareness helpers. Everything resolves against defaultTargetPlatform (not dart:io), so it is correct on the web and respects debugDefaultTargetPlatformOverride in tests.
AtlasTheme
Resolves the active AtlasThemeData, preferring an explicit AtlasThemeScope, then a ThemeData extension, then a theme-derived default.
AtlasThemeData
Visual configuration for the hold-Alt HUD, supplied as a ThemeExtension.
CommandAction
The single root action for callback commands created with command. All CommandIntents route here and are dispatched by id, so nesting can never shadow a callback by intent type.
CommandIntent
The Intent dispatched by callback commands created with command. All callback commands share this type and are routed by id to the single root command action installed by ShortcutAtlas.
FakeAltHoldClock
A deterministic AltHoldClock for tests: timers fire only when elapse advances the clock past their deadline.
GlyphSet
Renders a ShortcutActivator into a list of display glyph tokens, one per key cap, in platform-correct order (⌃⌥⇧⌘ on Apple; Ctrl/Alt/Shift words elsewhere).
HudRowModel
One row in the HUD: a resolved command, its effective activator (after any re-binding), and whether it is currently enabled.
HudSectionModel
One grouped section in the HUD.
HudViewModel
The immutable snapshot the HUD renders. null (in the controller's notifier) means "hidden".
InMemoryKeymapStore
A non-persistent store (re-bindings last for the session only).
Keymap
A layered map of command id → activator: factory < admin < user.
KeymapStore
Persists user re-bindings. Implement this to store them wherever you like (the example wires shared_preferences). The package ships InMemoryKeymapStore; persistence is opt-in and dependency-free.
KeyRecorder
A focusable widget that records the next key chord the user presses, for "press a key to rebind" UIs. Click it (or focus it), then press a chord; the resulting SingleActivator is reported via onRecorded. Escape cancels.
PlatformActivator
A ShortcutActivator that uses the platform's primary modifier: Command (Meta) on macOS/iOS, Control everywhere else.
ScopeRegistration
A live registration of one ShortcutScope's commands, anchored to the focus node that scopes them.
ShortcutAtlas
The root of the shortcut system. Install it once via MaterialApp.builder:
ShortcutCommand<T extends Intent>
The single unit of truth: a key binding plus the human metadata needed to dispatch it, gate it, and display it in the HUD.
ShortcutGroup
A HUD section / palette bucket. The stable id enables ordering and (later) localization.
ShortcutMenu
A top-level menu and the commands it contains.
ShortcutMenuBar
A Material MenuBar generated from ShortcutCommands — one source of truth for the key binding, the HUD, the palette, and the menu.
ShortcutScope
Declares a region of the app where commands are active.
ShortcutSurfaces
Which read-only surfaces a command projects into: the hold-Alt hud, the searchable command palette, and the generated menu bar.
SystemAltHoldClock

Enums

AltHoldPhase
ScopeKind
The scope precedence band. Precedence is ultimately emergent from the focus tree; this is metadata used for diagnostics and HUD grouping.

Functions

command(String id, {required ShortcutActivator activator, required String label, required ShortcutGroup group, required VoidCallback onInvoke, ValueListenable<bool>? enableWhen, String labelBuilder(BuildContext context)?, String? description, IconData? icon, int order = 0, ShortcutSurfaces surfaces = ShortcutSurfaces.all, bool webSafe = true}) → ShortcutCommand<CommandIntent>
Sugar for the common case: bind a key to a callback. Wraps the callback in a real CommandIntent so it still flows through dispatch and enable-gating (rather than the metadata-less CallbackShortcuts path).
primary(LogicalKeyboardKey trigger, {bool shift = false}) → ShortcutActivator
Ctrl+<key> on Windows/Linux, Cmd+<key> on macOS.
primaryShift(LogicalKeyboardKey trigger) → ShortcutActivator
Ctrl+Shift+<key> on Windows/Linux, Cmd+Shift+<key> on macOS.