KeyboardShortcuts

public enum KeyboardShortcuts

Global keyboard shortcuts for your macOS app.

  • Remove all handlers receiving keyboard shortcuts events.

    This can be used to reset the handlers before re-creating them to avoid having multiple handlers for the same shortcut.

    Declaration

    Swift

    public static func removeAllHandlers()
  • Disable a keyboard shortcut.

    Declaration

    Swift

    public static func disable(_ name: Name)
  • Enable a disabled keyboard shortcut.

    Declaration

    Swift

    public static func enable(_ name: Name)
  • Reset the keyboard shortcut for one or more names.

    If the Name has a default shortcut, it will reset to that.

    import SwiftUI
    import KeyboardShortcuts
    
    struct PreferencesView: View {
        var body: some View {
            VStack {
                // …
                Button("Reset All") {
                    KeyboardShortcuts.reset(
                        .toggleUnicornMode,
                        .showRainbow
                    )
                }
            }
        }
    }
    

    Declaration

    Swift

    public static func reset(_ names: Name...)
  • Reset the keyboard shortcut for one or more names.

    If the Name has a default shortcut, it will reset to that.

    Note

    This overload exists as Swift doesn’t support splatting.
    import SwiftUI
    import KeyboardShortcuts
    
    struct PreferencesView: View {
        var body: some View {
            VStack {
                // …
                Button("Reset All") {
                    KeyboardShortcuts.reset(
                        .toggleUnicornMode,
                        .showRainbow
                    )
                }
            }
        }
    }
    

    Declaration

    Swift

    public static func reset(_ names: [Name])
  • Set the keyboard shortcut for a name.

    Setting it to nil removes the shortcut, even if the Name has a default shortcut defined. Use .reset() if you want it to respect the default shortcut.

    You would usually not need this as the user would be the one setting the shortcut in a preferences user-interface, but it can be useful when, for example, migrating from a different keyboard shortcuts package.

    Declaration

    Swift

    public static func setShortcut(_ shortcut: Shortcut?, for name: Name)
  • Get the keyboard shortcut for a name.

    Declaration

    Swift

    public static func getShortcut(for name: Name) -> Shortcut?
  • Listen to the keyboard shortcut with the given name being pressed.

    You can register multiple listeners.

    You can safely call this even if the user has not yet set a keyboard shortcut. It will just be inactive until they do.

    import Cocoa
    import KeyboardShortcuts
    
    @main
    final class AppDelegate: NSObject, NSApplicationDelegate {
        func applicationDidFinishLaunching(_ notification: Notification) {
            KeyboardShortcuts.onKeyDown(for: .toggleUnicornMode) { [self] in
                isUnicornMode.toggle()
            }
        }
    }
    

    Declaration

    Swift

    public static func onKeyDown(for name: Name, action: @escaping KeyAction)
  • Listen to the keyboard shortcut with the given name being pressed.

    You can register multiple listeners.

    You can safely call this even if the user has not yet set a keyboard shortcut. It will just be inactive until they do.

    import Cocoa
    import KeyboardShortcuts
    
    @main
    final class AppDelegate: NSObject, NSApplicationDelegate {
        func applicationDidFinishLaunching(_ notification: Notification) {
            KeyboardShortcuts.onKeyUp(for: .toggleUnicornMode) { [self] in
                isUnicornMode.toggle()
            }
        }
    }
    

    Declaration

    Swift

    public static func onKeyUp(for name: Name, action: @escaping KeyAction)
  • Key

    Represents a key on the keyboard.

    See more

    Declaration

    Swift

    public struct Key : Hashable, RawRepresentable
  • The strongly-typed name of the keyboard shortcut.

    After registering it, you can use it in, for example, KeyboardShortcut.Recorder and KeyboardShortcut.onKeyUp().

    import KeyboardShortcuts
    
    extension KeyboardShortcuts.Name {
        static let toggleUnicornMode = Self("toggleUnicornMode")
    }
    
    See more

    Declaration

    Swift

    public struct Name : Hashable
    extension KeyboardShortcuts.Name: RawRepresentable
  • A SwiftUI View that lets the user record a keyboard shortcut.

    You would usually put this in your preferences window.

    It automatically prevents choosing a keyboard shortcut that is already taken by the system or by the app’s main menu by showing a user-friendly alert to the user.

    It takes care of storing the keyboard shortcut in UserDefaults for you.

    import SwiftUI
    import KeyboardShortcuts
    
    struct PreferencesView: View {
        var body: some View {
            HStack {
                Text("Toggle Unicorn Mode:")
                KeyboardShortcuts.Recorder(for: .toggleUnicornMode)
            }
        }
    }
    
    See more

    Declaration

    Swift

    public struct Recorder : NSViewRepresentable
  • A NSView that lets the user record a keyboard shortcut.

    You would usually put this in your preferences window.

    It automatically prevents choosing a keyboard shortcut that is already taken by the system or by the app’s main menu by showing a user-friendly alert to the user.

    It takes care of storing the keyboard shortcut in UserDefaults for you.

    import Cocoa
    import KeyboardShortcuts
    
    final class PreferencesViewController: NSViewController {
        override func loadView() {
            view = NSView()
    
            let recorder = KeyboardShortcuts.RecorderCocoa(for: .toggleUnicornMode)
            view.addSubview(recorder)
        }
    }
    
    See more

    Declaration

    Swift

    public final class RecorderCocoa : NSSearchField, NSSearchFieldDelegate
  • A keyboard shortcut.

    See more

    Declaration

    Swift

    public struct Shortcut : Hashable, Codable
    extension KeyboardShortcuts.Shortcut: CustomStringConvertible