This plugin allows Flutter desktop apps to defines system/inapp wide hotkey (i.e. shortcut).

---

---

• hotkey_system
  • Platform Support
  • Quick Start
    • Installation
      • Linux requirements
    • Usage
  • Who's using it?
  • API
    • HotKeySystem
  • Related Links
  • License

Platform Support

Linux	macOS	Windows
✔️	✔️	✔️

Quick Start

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  hotkey_system: ^0.0.9

Or

dependencies:
  hotkey_system:
    git:
      url: https://github.com/suysoftware/hotkey_system.git
      ref: main

Linux requirements

• keybinder-3.0

Run the following command

sudo apt-get install keybinder-3.0

Usage

import 'package:hotkey_system/hotkey_system.dart';

void main() async {
  // Must add this line.
  WidgetsFlutterBinding.ensureInitialized();
  // For hot reload, `unregisterAll()` needs to be called.
  await hotKeySystem.unregisterAll();

  runApp(MyApp());
}

Register/Unregsiter a system/inapp wide hotkey.

// ⌥ + Q
HotKey _hotKey = HotKey(
  KeyCode.keyQ,
  modifiers: [KeyModifier.alt],
  // Set hotkey scope (default is HotKeyScope.system)
  scope: HotKeyScope.inapp, // Set as inapp-wide hotkey.
);
await hotKeySystem.register(
  _hotKey,
  keyDownHandler: (hotKey) {
    print('onKeyDown+${hotKey.toJson()}');
  },
  // Only works on macOS.
  keyUpHandler: (hotKey){
    print('onKeyUp+${hotKey.toJson()}');
  } ,
);

await hotKeySystem.unregister(_hotKey);

await hotKeySystem.unregisterAll();

Use HotKeyRecorder widget to help you record a hotkey.

HotKeyRecorder(
  onHotKeyRecorded: (hotKey) {
    _hotKey = hotKey;
    setState(() {});
  },
),

Use HotKeyRecorder widget with initialHotkey

HotKeyRecorder(
  onHotKeyRecorded: (hotKey) {
    _hotKey = hotKey;
    setState(() {});
  },
  initialHotKey: HotKey.fromJson({"keyCode":"keyR","modifiers":["meta"],"identifier":"fdf8484b-5249-42bb-b473-d99bfb7bb3e8","scope":"system"})
),

Register with identifier

// ⌥ + Q
HotKey _hotKey = HotKey(
  KeyCode.keyQ,
  modifiers: [KeyModifier.alt],
  identifier: "examleidentifier"
  // Set hotkey scope (default is HotKeyScope.system)
  scope: HotKeyScope.inapp, // Set as inapp-wide hotkey.
);
await hotKeySystem.register(
  _hotKey,
  keyDownHandler: (hotKey) {
    print('onKeyDown+${hotKey.toJson()}');
  },
  // Only works on macOS.
  keyUpHandler: (hotKey){
    print('onKeyUp+${hotKey.toJson()}');
  } ,
);

Hotkey.fromJson usage

HotKey _hotKey = HotKey.fromJson({"keyCode":"keyR","modifiers":["meta"],"identifier":"fdf8484b-5249-42bb-b473-d99bfb7bb3e8","scope":"system"})
await hotKeySystem.register(
  _hotKey,
  keyDownHandler: (hotKey) {
    print('onKeyDown+${hotKey.toJson()}');
  },
  // Only works on macOS.
  keyUpHandler: (hotKey){
    print('onKeyUp+${hotKey.toJson()}');
  } ,
);

HotKeyVirtualView usage

 
return HotKeyVirtualView(HotKey.fromJson({"keyCode":"keyR","modifiers":["meta"],"identifier":"fdf8484b-5249-42bb-b473-d99bfb7bb3e8","scope":"system"}));

Package Parsers

// Parsing a string to a KeyModifier
KeyModifier modifier = KeyModifierParser.parse("shift");

// Getting the ModifierKey from a KeyModifier
ModifierKey modKey = modifier.modifierKey;

// Getting LogicalKeyboardKeys from a KeyModifier
List<LogicalKeyboardKey> keys = modifier.logicalKeys;

// Getting the label for a KeyModifier
String label = modifier.keyLabel;

// Convert LogicalKeyboardKey to KeyCode
KeyCode keyCode = KeyCodeParser.fromLogicalKey(LogicalKeyboardKey.keyA);

// Retrieve the LogicalKeyboardKey from a KeyCode
LogicalKeyboardKey logicalKey = keyCode.logicalKey;

// Parse a string to a KeyCode
KeyCode parsedKeyCode = KeyCodeParser.parse("keyA");

// Get the key label
String keyLabel = keyCode.keyLabel;

Modifiers

KeyModifier.alt // macOS: option & windows: alt

KeyModifier.shift // macOS: shift & windows: shift

KeyModifier.meta // macOS: cmd & windows: windows key

KeyModifier.control // macOS: control & windows: control

// For Control Key
String controlKeyLabel = KeyCode.control.keyLabel; // Returns '⌃' on macOS, 'Ctrl' on Windows

// For Shift Key
String shiftKeyLabel = KeyCode.shift.keyLabel; // Returns '⇧'

// For Alt Key
String altKeyLabel = KeyCode.alt.keyLabel; // Returns '⌥' on macOS, 'Alt' on Windows

// For Meta Key
String metaKeyLabel = KeyCode.meta.keyLabel; // Returns '⌘' on macOS, '⊞' on Windows

HotKey Object

enum HotKeyScope {
  system,
  inapp,
}

class HotKey {
  HotKey(
    this.keyCode, {
    this.modifiers,
    String? identifier,
    HotKeyScope? scope,
  }) {
    if (identifier != null) this.identifier = identifier;
    if (scope != null) this.scope = scope;
  }

  factory HotKey.fromJson(Map<String, dynamic> json) {
    return HotKey(
      KeyCodeParser.parse(json['keyCode']),
      modifiers: List<String>.from(json['modifiers'])
          .map((e) => KeyModifierParser.parse(e))
          .toList(),
      identifier: json['identifier'],
      scope: HotKeyScope.values.firstWhere(
        (e) => e.name == json['scope'],
        orElse: () => HotKeyScope.system,
      ),
    );
  }

  KeyCode keyCode;
  List<KeyModifier>? modifiers;
  String identifier = DateTime.now().millisecondsSinceEpoch.toString();
  HotKeyScope scope = HotKeyScope.system;

  Map<String, dynamic> toJson() {
    return {
      'keyCode': keyCode.name,
      'modifiers': modifiers?.map((e) => e.name).toList() ?? [],
      'identifier': identifier,
      'scope': scope.name.toString(),
    };
  }

  @override
  String toString() {
    return '${modifiers?.map((e) => e.keyLabel).join('')}${keyCode.keyLabel}';
  }
}

Please see the example app of this plugin for a full example.

Who's using it?

• ThinkBuddy - Made for native MacOS experience integrated with AI

API

HotKeySystem

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.	✔️	✔️	✔️

Related Links

• https://github.com/soffes/HotKey
• https://github.com/kupferlauncher/keybinder
• https://github.com/leanflutter/hotkey_manager

License

MIT