Investigate a possibility to use `CGEvent.tapCreate` for global hotkeys

[nikitabobko]

Right now, we use Carbon API. It's a deprecated framework, but since a looot of apps use, I don't think that Apple is gonna drop it in foreseeable future

The alternative API I recently found is
https://developer.apple.com/documentation/coregraphics/cgevent/1454426-tapcreate
https://forums.developer.apple.com/forums/thread/735223

Copying the response from apple forum in case it gets deleted:

I was recently asked a very similar question in a DTS incident. Pasted in below are the relevant snippets from my response.

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

There are two parts to creating an app like this:

  - Ensuring your app runs in the background (A)

  - Monitoring key presses (B)

I’ll cover each in turn.

With regards point A, running in the background, the approach I recommend is to split the core of your app off into a separate app that you then nest within your main app. Set the [LSUIElement property](https://developer.apple.com/documentation/bundleresources/information_property_list/lsuielement) on the nested app, so it doesn’t show up in the Dock or have its own menu bar.

In that nested app, use a [menu bar status item](https://developer.apple.com/documentation/appkit/menus_cursors_and_the_dock#2871629) to present your UI.

Note If you’re using SwiftUI, there’s now a [SwiftUI equivalent](https://developer.apple.com/documentation/swiftui/scenes#creating-a-menu-bar-extra).

In your main app, have a UI to control whether the nested app runs as a login item, that is, runs while the user is logged in. Use the [SMAppService.loginItem(identifier:) method](https://developer.apple.com/documentation/servicemanagement/smappservice/3945411-loginitem) to configure this.

If you need to support older system, use the [SMLoginItemSetEnabled function](https://developer.apple.com/documentation/servicemanagement/1501557-smloginitemsetenabled) instead..

IMPORTANT App Review has specific constraints about the use of login items. See clause 2.4.5(iii) of the [App Store Review Guidelines](https://developer.apple.com/app-store/review/).

With regards B, monitoring key presses, there are a variety of APIs to monitor keyboard events, including:

  - The [CGEventTap subsystme](https://developer.apple.com/documentation/coregraphics/cgevent/1454426-tapcreate)

  - AppKit’s [global event monitor](https://developer.apple.com/documentation/appkit/nsevent/1535472-addglobalmonitorforevents)

  - RegisterEventHotKey

Of these the one I like the most is RegisterEventHotKey. However, it’s intimately tied to the legacy Carbon toolbox and thus I can’t honestly recommend it.

Of the remaining options, I prefer CGEventTap because of its interactions with TCC. More on this below.

Note This is called CGEventTap because of the API name in C-based languages, CGEventTapCreate.

TCC stands for Transparency, Consent, and Control. It’s the subsystem behind the privileges in System Settings > Privacy and Security. To listen for keyboard events you’ll need the Input Monitoring privilege.

One reason I like CGEventTap is that it’s clearly associated with the APIs to determine whether you have that privilege (CGPreflightListenEventAccess) and to request that privilege (CGRequestListenEventAccess).

CGEventTap is compatible with the App Sandbox, starting with macOS 10.15.

CGEventTap is a bit tricky to use from Swift. See [this post](https://developer.apple.com/forums/thread/707680?answerId=716892022#716892022) for an example.

Maybe the alternative API allows to distinguish left and right modifiers (#28) and fn key (#1011)

Related

#1472

Follow ups

#1931

[nikitabobko]

Another useful link:
https://developer.apple.com/forums/thread/707680?answerId=716892022#716892022

Details

Yes, but you have to take a slightly different tack. Rather than using an NSEvent global event monitor, use a CGEventTap. For weird historical reasons, the former requires the Accessibility privilege whereas the latter requires the Input Monitoring privilege. The Input Monitoring privilege is easily available to sandboxed apps, and even apps published on the Mac App Store. It even has APIs to check for (CGPreflightListenEventAccess) and explicitly request (CGRequestListenEventAccess) that privilege.

CGEventTap is not exactly fun to call from Swift. Pasted in below is a snippet that shows the basics. I pulled this out of a large test project, and removed some code that shouldn’t matter to you, so I apologise if this doesn’t compile out of the box.

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

	final class CGEventTapAction {
	 
	    init(log: OSLog) {
	        self.log = log
	    }
	    
	    let log: OSLog
	 
	    private var runState: RunState? = nil
	 
	    private struct RunState {
	        let port: CFMachPort
	        let setStatus: (String) -> Void
	    }
	    
	    func start(_ setStatus: @escaping (String) -> Void) {
	        precondition(self.runState == nil)
	        
	        os_log(.debug, log: self.log, "will create tap")
	        let info = Unmanaged.passRetained(self).toOpaque()
	        let mask = CGEventMask(1 << CGEventType.keyDown.rawValue)
	        guard let port = CGEvent.tapCreate(
	            tap: .cgSessionEventTap,
	            place: .headInsertEventTap,
	            options: .listenOnly,
	            eventsOfInterest: mask,
	            callback: { (proxy, type, event, info) -> Unmanaged<CGEvent>? in
	                let obj = Unmanaged<CGEventTapAction>.fromOpaque(info!).takeUnretainedValue()
	                obj.didReceiveEvent(event)
	                // We don’t replace the event, so the new event is the same as
	                // the old event, so we return it unretained.
	                return Unmanaged.passUnretained(event)
	            },
	            userInfo: info
	        ) else {
	            os_log(.debug, log: self.log, "did not create tap")
	            // We retained `self` above, but the event tap didn’t get created so
	            // we need to clean up.
	            Unmanaged<CGEventTapAction>.fromOpaque(info).release()
	            setStatus("Failed to create event tap.")
	            return
	        }
	        let rls = CFMachPortCreateRunLoopSource(nil, port, 0)!
	        CFRunLoopAddSource(CFRunLoopGetCurrent(), rls, .defaultMode)
	        self.runState = RunState(port: port, setStatus: setStatus)
	        os_log(.debug, log: self.log, "did create tap")
	    }
	    
	    private func didReceiveEvent(_ event: CGEvent) {
	        os_log(.debug, log: self.log, "did receive event")
	        guard let runState = self.runState else { return }
	        runState.setStatus("Last event at \(Date()).")
	    }
	 
	    func stop() {
	        guard let runState = self.runState else { return }
	        self.runState = nil
	 
	        os_log(.debug, log: self.log, "will stop tap")
	        CFMachPortInvalidate(runState.port)
	        // We passed a retained copy of `self` to the `info` parameter
	        // when we created the tap.  We need to release that now that we’ve
	        // invalidated the tap.
	        Unmanaged.passUnretained(self).release()
	        os_log(.debug, log: self.log, "did stop tap")
	    }
	}

[Akazm]

You might want to look at my projects.

This one is a Swift 6-ready package for asynchronous, concurrency safe event processing:

https://github.com/Akazm/tap-guard

This one helps with shortcut detection and also detects sequences (you know, like combos in martial arts video games):

https://github.com/Akazm/shortcut-detection-kit

This might be of interest to you as well:

https://github.com/Akazm/window-scaling-kit

All 3 of which are at least somewhat mature to some degree and I'd be happy to continue developing them.

However, I'm not sure what consumers might require, and I'm also looking for contributions.