system wide shortcut for Mac OS X

Question

So I was asked to port some internal helper applications to Mac OS X 10.7.

Works all quite welll as the platform dependent code is minimal anyhow, but one application needs a system wide shortcut to function (i.e. RegisterHotkey functionality) and I can't find any documentation on how I'd do this on a Mac.

The program is using a PyQt gui with Python 3.2. and the corresponding code for windows is basically:

def register_hotkey(self):
    hwnd = int(self.winId())
    modifiers, key = self._get_hotkey()
    user32.RegisterHotKey(hwnd, self._MESSAGE_ID, modifiers, key)

and then to receive the hotkey events:

def winEvent(self, msg):
    if msg.message == w32.WM_HOTKEY:
        self.handle_hotkey()
        return True, id(msg)
    return False, id(msg)

Note that I don't need a python variant, I can easily write a simple c extension - so C/objective-c solutions are welcome as well.

Answer 1

Let me get to the good part first: I've written a small Python module to make this easy: QuickMacHotKey.

Using it looks like this:

@quickHotKey(virtualKey=kVK_ANSI_X,
             modifierMask=mask(cmdKey, controlKey, optionKey))
def handler() -> None:
    print("handled ⌘⌃⌥X")

You can get it with pip install quickmachotkey.

Now for the history and details as to why this is necessary:

Unfortunately the accepted answer is using a documented, public API that requires obnoxious security prompts and full accessibility access in order to use. Higher level APIs like addGlobalMonitorForEventsMatchingMask:handler: also require that sort of accessibility access. As the documentation for that method puts it:

Key-related events may only be monitored if accessibility is enabled or if your application is trusted for accessibility access (see AXIsProcessTrusted).

The way to register global hotkeys without triggering accessibility prompts is still to use the ancient Carbon API RegisterEventHotKey, and that's not a hyperlink because there's no official documentation any more; you just have to know this exists by having worked with earlier versions of macOS. The best documentation tends to be other open source projects muddling through this discovery themselves. It's just a leftover function from a framework that is so deprecated that almost all of it has been removed; this one, specific function has just never been replaced because there's still no alternative, despite the vast majority of the framework being gone now.

This API used to be available to Python via the built-in Carbon module, but that was removed in Python 3 because it was wrapping a framework that was, as I said, going away. With the introduction of 64-bit macs, big chunks of that framework were never even ported, and 32-bit executables on macOS have not been supported for many years now.

So, what my module is doing is simply using a PyObjC API which is, itself, deprecated, with no replacement, although its maintainer is somewhat more responsive than Apple, so I'd expect that my concerns will actually be addressed before the framework release that fully breaks it comes out :).