Global Hot Keys by Seth Willits 05-15-04

The Login Welcomer Tutorial
To introduce you to using AddressOf and the Carbon Event system, we created a very simple example which says "Welcome" and "Goodbye" when you switch between users. Reading through that example to familiarize yourself with how Carbon Events work will make this tutorial easier to understand.

The Global Hot Keys Tutorial
In this tutorial, we'll explore how to register for a hot key event. A hot key is a combination of keys that when pressed notifies our application. The application can be in the foreground or background which makes this and ideal solution for bringing up transparent UIElement background applications, like Freaky Trash Manager.

Registering for the Hot Key
In addition to using the InstallEventHandler function (which we use to be notified of hot key events), we'll be using one specifically for hot keys RegisterEventHotKey, which notifies the system that we want to know when the hot key combination is pressed. When it is, our event handler installed with InstallEventHandler is fired. The parameters to the RegisterEventHotKey function are similar to that of InstallEventHandler. They are:

• UInt32 inHotKeyCode
• UInt32 inHotKeyModifiers
• EventHotKeyID inHotKeyID
• EventTargetRef inTarget
• OptionBits inOptions
• EventHotKeyRef * outRef

The first part of the method we'll use to install the handler involves the Declares. The three Declares we need are InstallEventHandler, GetApplicationEventTarget, and NewEventHandlerUPP. They are as follows:


Sub InstallHotKey()
   Declare Function RegisterEventHotKey Lib Carbon (KeyCode as Integer, KeyModifiers as Integer, EventHotKeySig as Integer, EventHotKeyID as Integer, EventTargetRef as Ptr, options as integer, ByRef HotKeyRef as integer) as Integer
   Declare Function InstallEventHandler Lib Carbon (eventTarget as Ptr, handler as Ptr, numTypes as integer, types as ptr, userdata as integer, ByRef EventHandlerRef as integer) as Integer
   Declare Function GetApplicationEventTarget Lib Carbon () as Ptr
   Declare Function NewEventHandlerUPP Lib Carbon (address as Ptr) as Ptr
   
   
   dim err, eventRef as integer
   dim eventType, keyID as MemoryBlock
   dim attributes as integer
   dim modifiers as integer
   
   // Event Types List
   eventType = NewMemoryBlock(8)
   eventType.StringValue(0, 4) = kEventClassKeyboard
   eventType.Long(4) = kEventHotKeyPressed


So far we've only done the standard Declare statements, dimmed our variables, and created the EventTypeSpec for the hot key event. Below we create an ID for our hot key registration and then install the event handler. This ID is the direct object parameter sent to our event handler. It is how we know which hot key was pressed.

   // Key ID
   keyID = NewMemoryBlock(8)
   keyID.StringValue(0, 4) = "t3st"
   KeyID.Long(4) = 0
   
   // Install Event Handler
   err = InstallEventhandler(GetApplicationEventTarget(), NewEventHandlerUPP(AddressOf HotKeyPressed), 1, eventType, 0, HotKeyEventHandlerRef)
   if err <> noErr then
      MsgBox "InstallEventHandler" + EndOfLine + EndOfLine + str(err)
   end if

Below we use Bitwise Or to combine the modifiers we want to be part of the key combination. Here we're using Command, Option, and Control. The key itself is the "T" key (&h11).

   // Register HotKey
   modifiers = Bitwise.BitOr(modifiers, cmdKey)
   modifiers = Bitwise.BitOr(modifiers, optionKey)
   modifiers = Bitwise.BitOr(modifiers, controlKey)
   err = RegisterEventHotKey(&h11, modifiers, keyID.Long(0), keyID.Long(4), GetApplicationEventTarget(), 0, HotKeyRef)
   if err <> noErr then
      MsgBox "RegisterEventHotKey Error" + EndOfLine + EndOfLine + str(err)
   end if
End Sub



The event handler itself is far simpler:

Function HotKeyPressed(EventHandlerCallRef as Integer, EventRef as Integer, UserData as Integer) As Integer
   Window1.Show
   
   return noErr
End Function


Now our handler is so simple since we're only registering for one key. If we registered for multiple keys, we'd need to get the direct object parameter from the EventRef to find out which key was pressed.

To unregister a hot key, we use the UnregisterEventHotKey function which takes a pointer to the hot key reference. Note that we'd also need to unregister the event handler too if for some reason we did unregister the hot key.

Sub UninstallHotKey()
   Declare Function UnregisterEventHotKey Lib Carbon (EventHotKeyRef as Integer) as Integer
   Declare Function RemoveEventHandler Lib Carbon (EventHandlerRef as Integer) as Integer
   
   
   dim err as integer
   
   err = UnregisterEventHotKey(HotKeyRef)
   if err <> noErr then
      MsgBox "UnregisterEventHotKey Error" + EndOfLine + EndOfLine + str(err)
   end if
   
   err = RemoveEventHandler(HotKeyEventHandlerRef)
   if err <> noErr then
      MsgBox "RemoveEventHandler Error" + EndOfLine + EndOfLine + str(err)
   end if
End Sub


As always, you can download the project for this tutorial.