.NET 1.1+

Registering System-Wide Hot Keys

Some Windows applications execute in the background and are activated only as required. To enhance such a program's usability it is useful to register a system-wide hot key. This allows the software to activate when a specific key combination is pressed.

RegisterHotKey API Function

It is a common requirement, when developing Windows Forms software, that an entire program or some element of it will execute in the background. Often, the user will need to interact with the application only occasionally. At this time they will click a system tray icon or press a special key combination to show the user interface. Two good examples of this are Microsoft Outlook, which may be minimised to the system tray, and Launchy, which has no user interface until summoned.

The .NET framework does not provide a simple manner in which to detect keypresses for a Windows Forms application that is not currently active. However, using Platform Invocation Services (P/Invoke), we can call a Windows API function that registers a system-wide hot key and links it to a form. Once registered, if the user presses the specified key, or combination of keys, a message will automatically be sent to the appropriate form. This message will be received even if the form is inactive.

Hot Key Sample

In this article we will create a simple Windows Forms program that includes registering a hot key. When the key is pressed, the program's form will be activated. To begin, create a new Windows Forms application. The project should include a single form by default. All of the code for the sample will be contained within this form.

Declaring the API Functions

As the code in this sample uses P/Invoke, we will be using attributes from the System.Runtime.InteropServices namespace. To keep the code as simple to read as possible, add the following using directive to the top of the form's code file.

There are two API functions that should be used when registering system-wide hot keys. The first is used to set up the hot key and is named "RegisterHotKey". The second function is used to remove the registration when it is no longer required. This is named "UnregisterHotKey".

To declare the two functions, add the following code within the form class' code block.

[DllImport("user32.dll")]
private static extern bool RegisterHotKey(IntPtr hWnd, int id, int fsModifiers, int vlc);

[DllImport("user32.dll")]
private static extern bool UnregisterHotKey(IntPtr hWnd, int id);

The RegisterHotKey uses the following four parameters:

• hWnd. The hWnd parameter is used to specify a handle to the window that should receive messages when the hot key is pressed. In the sample we will provide the handle of the form using its in-built Handle property.
• id. Each hot key is registered with an identification number using this parameter. This value is unique for the specified window handle. If the id is already in use, the previous registration is replaced with a new version.
• fsModifiers. Hot keys are almost always registered as a combination of keys so that they are less likely to interfere with the operation of other software. The fsModifiers parameter is used to specify one or more keys that must be pressed at the same time as the hot key. The modifiers can be Ctrl, Alt, Shift, the Windows key or any combination of these four keys.
• vlc. The final parameter is used to provide the virtual key code for the hot key itself.

The function returns a Boolean value. If the process is successful, the value will be true. If it fails, the return value will be false. A failure usually indicates that the hot key combination is already in use or is reserved by the operating system.

The UnregisterHotKey uses the first two of the above parameters only. It does not need to be provided with the hot key or the modifiers, as the combination of handle and unique ID provides enough information to remove the registration.