HotKeyManager

Powerful, modern, and easy-to-use keyboard shortcut manager for macOS

🇨🇳中文 | 🇬🇧English

---

HotKeyManager is a powerful, modern, and easy-to-use keyboard shortcut manager for macOS, built with SwiftUI and Swift Concurrency. It provides a robust way to record, store, and monitor global hotkeys in your application.

Features

• 🚀 Modern API: Built with Swift Concurrency (async/await) and SwiftUI.
• 🎯 Double Tap Support: Detects double-tap shortcuts (e.g., double-tap Cmd).
• 🎨 Beautiful UI: Includes a polished, customizable HotKeyRecorder view.
• 💾 Persistence: Automatically saves and loads shortcuts using UserDefaults.
• 🛡️ Safe & Robust: Handles edge cases like implicit Fn keys on laptops and prevents conflicts.
• 🌍 Localized: Supports English, Chinese, Japanese, Spanish, French, and German and more.

Installation

Add HotKeyManager to your Package.swift:

dependencies: [
    .package(url: "https://github.com/L1cardo/HotKeyManager", branch: "main")
]

Usage

1. Define Shortcuts

Use HotKeyManager.Name to define your shortcuts. You can use string literals for convenience.

import HotKeyManager

extension HotKeyManager.Name {
    // With a default value
    static let startRecording = Self("startRecording", default: HotKey(key: nil, modifiers: [.command], isDoubleTap: true))
    // Without a default value
    static let stopRecording = Self("stopRecording")
}

2. Record Shortcuts

Add the HotKeyRecorder view to your settings UI.

import HotKeyManager
import SwiftUI

struct SettingsView: View {
    var body: some View {
        Form {
            Section("General") {
                HotKeyManager.Recorder(for: .startRecording)
                HotKeyManager.Recorder(for: .stopRecording)
            }
        }
    }
}

3. Listen for Events

Register handlers for your shortcuts. You can listen for .keyDown, .keyUp.

@main
struct MyApp: App {
    @NSApplicationDelegateAdaptor(AppDelegate.self) var appDelegate

    var body: some Scene {
        ...
    }
}

class AppDelegate: NSResponder, NSApplicationDelegate {
    func applicationDidFinishLaunching(_: Notification) {
        HotKeyManager.on(.keyDown, for: .startRecording) {
            print("Key Down Triggered!")
        }

        HotKeyManager.on(.keyUp, for: .stopRecording) {
            print("Key Up Triggered!")
        }
    }
}

Advanced

Modifier Side Selection

You can allow users to distinguish between left and right modifiers (e.g., Left Cmd vs Right Cmd).

HotKeyManager.Recorder(for: .toggleApp, modifirsSide: true)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• KeyboardShortcuts
• Sauce
• Hex

📞 Support

• Email: albert.abdilim@foxmail.com
• GitHub Issues: Report issues here