In this post, we will look at how to register your hot key listeners with the OS. It is not rocket science, really. All you have to do is implement one method and call two methods. First, we will look at what exactly are HotKeys. Then the three methods need to implement a HotKey and finally, the implementation itself.

What are HotKeys?
HotKeys are combinations of key presses that user uses to take advantage of a feature. For example, the Spotlight in Mac OS X has a default HotKey of Cmd+Space. Similarly, different applications use different HotKeys to simply the usage of the application.

Methods Required

OSStatus MyHotKeyHandler(EventHandlerCallRef nextHandler,EventRef theEvent,void *userData);

The above method is the one you would have to implement to handle the hot keys. The function name is not a issue, you can be creative with it.

InstallApplicationEventHandler( handler, numTypes, list, userData, outHandlerRef );

The above method will install the event handler with the OS. When the user presses the appropriate keys, the OS will invoke the handler with the userData and the EventRef.

extern OSStatus RegisterEventHotKey(
     UInt32            inHotKeyCode,
     UInt32            inHotKeyModifiers,
     EventHotKeyID     inHotKeyID,
     EventTargetRef    inTarget,
     OptionBits        inOptions,
     EventHotKeyRef *  outRef);

This is the method that actually registers for the HotKeys. The points below will give you some idea of how to use this method.

  1. inHotKeyModifiers: This parameter takes the key codes for the command(cmdKey),alt/option(optionKey),crtl(controlKey) and shift(shiftKey) keys. The variables in the brackets are the key codes that you would have to use. You can mix and the match the key codes. For example, you can say cmdKey+shiftKey or controlKey+cmdKey, etc…
  2. inHotKeyCode: This parameter takes the virtual key codes of the keyboard. The virtual key codes can be found here . For example, if you want to use cmdKey+m as your HotKey. You would register the cmdKey in the previous parameter and the char ‘m’ in the this parameter.
  3. inHotKeyID: This parameter will be used to differentiate one HotKey from another. The EventHotKeyID will contain a signature and a id. The signature is to ensure the HotKey is registered with your app and the id will identify which hot key was invoked.
  4. inTarget: This is generally GetEventDispatcherTarget();
  5. outRef: The EventHotKeyRef is required for the unregistering the HotKey later on. Be sure to keep track of one EventHotKeyRef for each HotKey. This will help you when you are trying to modify just one HotKey.

Implementation
First we are going to implement the method that handles the HotKey events.

OSStatus MyHotKeyHander(EventHandlerCallRef nextHandler,EventRef theEvent,void *userData){
	//Do something once the key is pressed
	EventHotKeyID hotKeyID;
	GetEventParameter(theEvent,kEventParamDirectObject,typeEventHotKeyID,
                                        NULL,sizeof(hotKeyID),NULL,&hotKeyID);
	int temphotKeyId = hotKeyID.id; //Get the id, so we can know which HotKey we are handling.
        switch(temphotKeyId){
             //Now you know which HotKey. Do something...
       }
}

Then we are going to install a ApplicationEventHandler.

     EventTypeSpec _eventType;
     _eventType.eventClass = kEventClassKeyboard;
     _eventType.eventKind = kEventHotKeyPressed;
     InstallApplicationEventHandler(&MyHotKeyHander,1,_eventType,self,NULL);
     //Here i am returning 'self' as the user data. So when the MyHotKeyHandler
     // is called, it will contain self as the data. You can
     // declare any object you want and that will end up as the userData in
     // MyHotKeyHandler.

Now the final step to register the HotKeys.

	OSStatus error;
	EventHotKeyID hotKeyID;
	EventHotKeyRef hotKeyRef;

	hotKeyID.signature='hk';
	hotKeyID.id	= 1;

	error = RegisterEventHotKey(cmdKey+optionKey, 123 , hotKeyID,
                                 GetEventDispatcherTarget(), 0, &hotKeyRef);
                                 // cmd+option+(left arrow)

	if(error){
		//handle error
	}

If you want to unregister the HotKey, all you would have to do is call the UnregisterEventHotKey method with the EventHotKeyRef.

        OSStatus error;
	EventHotKeyRef hotKeyRef = // The HotKeyRef for the HotKey you want to unregister;
	error = UnregisterEventHotKey(hotKeyRef);
	if(error){
		//handle error
	}

Thats it folks! Good luck! Comments are always welcome.