🚀 Ship Your App Faster: Try Fastforge - The simplest way to build, package and distribute your Flutter apps.
This plugin allows Flutter desktop apps to defines system/inapp wide hotkey (i.e. shortcut).
English | 简体中文
System shortcuts use the C++ nativeapi core through Dart FFI. No per-platform native hotkey_manager plugin or method channel is needed.
Requires Dart 3.13+, Flutter 3.47+ and nativeapi/cnativeapi 0.5.4+ with native keycode support. Until that dependency release is published, these compatibility fixes require the matching nativeapi workspace sources through local dependency overrides.
import 'package:hotkey_manager/native.dart' as hotkey;
final manager = hotkey.ShortcutManager.instance;
final listenerId = manager.addListener((event) {
if (event is hotkey.ShortcutActivatedEvent) {
print('Pressed: ${event.accelerator}');
} else if (event is hotkey.ShortcutReleasedEvent) {
print('Released: ${event.accelerator}'); // macOS
}
});
final shortcut = manager.registerWithOptions(const hotkey.ShortcutOptions(
accelerator: 'Ctrl+Alt+Q',
description: 'Quick action',
scope: hotkey.ShortcutScope.global,
enabled: true,
));
if (shortcut == null) {
throw StateError('Shortcut unavailable or unsupported');
}
// When the registration is no longer needed:
manager.unregisterWithId(shortcut.id);
shortcut.dispose();
manager.removeListener(listenerId);Use addListener for Flutter callbacks: events are delivered asynchronously to
the registering Dart isolate. A shortcut handle must be unregistered before it
is disposed; disposing the handle alone does not remove the native registration.
The existing HotKeyManager, HotKey, HotKeyRecorder, HotKeyVirtualView,
GlobalShortcuts and CallbackGlobalShortcuts remain available from the original
package:hotkey_manager/hotkey_manager.dart import, and from package:hotkey_manager/legacy.dart. Old hotkey JSON is supported.
In-app shortcuts continue to use Flutter's HardwareKeyboard, with down and up
events on all Flutter platforms. System key-up events are available on macOS;
Windows and Linux report system key-down only. Fn is supported on macOS;
CapsLock is supported on macOS and Linux. Windows retains the old behavior of
ignoring Fn/CapsLock, and Linux ignores Fn. Unmapped system keys throw
PlatformException. The original platform keycodes preserve media, international
and keypad keys, and Windows system shortcuts retain native automatic repetition.
Linux system shortcuts require X11 (including XWayland), not native Wayland.
The original injectable HotKeyManagerPlatform and MethodChannelHotKeyManager
interfaces are retained; the default implementation uses nativeapi. The native
shortcut types are exported separately from package:hotkey_manager/native.dart
to avoid collisions with Flutter’s ShortcutManager.
Repeated registration of the same identifier retains any omitted handlers.
registeredHotKeyList remains a live list. Different identifiers with the same combination share one native registration and each
receive events. hotKeyManager.unregisterAll() clears this package's shortcuts,
including leftovers after a hot restart, while preserving shortcuts registered
directly through ShortcutManager.
| Linux | macOS | Windows |
|---|---|---|
| ✔️ | ✔️ | ✔️ |
Use the Git dependency for the nativeapi migration described here:
dependencies:
hotkey_manager:
git:
path: packages/hotkey_manager
url: https://github.com/leanflutter/hotkey_manager.git
ref: mainsudo apt-get install clang cmake ninja-build pkg-config libgtk-3-dev libx11-dev libxi-devimport 'package:hotkey_manager/hotkey_manager.dart';
void main() async {
// Must add this line.
WidgetsFlutterBinding.ensureInitialized();
// Reclaim native registrations left over after a hot restart.
await hotKeyManager.unregisterAll();
runApp(MyApp());
}Register/Unregsiter a system/inapp wide hotkey.
// ⌥ + Q
HotKey _hotKey = HotKey(
key: PhysicalKeyboardKey.keyQ,
modifiers: [HotKeyModifier.alt],
// Set hotkey scope (default is HotKeyScope.system)
scope: HotKeyScope.inapp, // Set as inapp-wide hotkey.
);
await hotKeyManager.register(
_hotKey,
keyDownHandler: (hotKey) {
print('onKeyDown+${hotKey.toJson()}');
},
// System key-up is macOS only; in-app key-up works on all platforms.
keyUpHandler: (hotKey){
print('onKeyUp+${hotKey.toJson()}');
} ,
);
await hotKeyManager.unregister(_hotKey);
await hotKeyManager.unregisterAll();Use HotKeyRecorder widget to help you record a hotkey.
HotKeyRecorder(
onHotKeyRecorded: (hotKey) {
_hotKey = hotKey;
setState(() {});
},
),Please see the example app of this plugin for a full example.
- Airclap - Send any file to any device. cross platform, ultra fast and easy to use.
- AuthPass - Password Manager based on Flutter for all platforms. Keepass 2.x (kdbx 3.x) compatible.
- Biyi (比译) - A convenient translation and dictionary app.
| Method | Description | Linux | macOS | Windows |
|---|---|---|---|---|
| register | register an system/inapp wide hotkey. | ✔️ | ✔️ | ✔️ |
| unregister | unregister an system/inapp wide hotkey. | ✔️ | ✔️ | ✔️ |
| unregisterAll | unregister all system/inapp wide hotkeys. | ✔️ | ✔️ | ✔️ |