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 theName
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.
-
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)
-
Represents a key on the keyboard.
See moreDeclaration
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
andKeyboardShortcut.onKeyUp()
.
See moreimport KeyboardShortcuts extension KeyboardShortcuts.Name { static let toggleUnicornMode = Self("toggleUnicornMode") }
Declaration
-
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.
See moreimport SwiftUI import KeyboardShortcuts struct PreferencesView: View { var body: some View { HStack { Text("Toggle Unicorn Mode:") KeyboardShortcuts.Recorder(for: .toggleUnicornMode) } } }
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.
See moreimport Cocoa import KeyboardShortcuts final class PreferencesViewController: NSViewController { override func loadView() { view = NSView() let recorder = KeyboardShortcuts.RecorderCocoa(for: .toggleUnicornMode) view.addSubview(recorder) } }
Declaration
Swift
public final class RecorderCocoa : NSSearchField, NSSearchFieldDelegate
-
A keyboard shortcut.
See moreDeclaration
Swift
public struct Shortcut : Hashable, Codable
extension KeyboardShortcuts.Shortcut: CustomStringConvertible