RegisterHotKey function (winuser.h)

Defines a system-wide hot key.

Syntax

BOOL RegisterHotKey(
  [in, optional] HWND hWnd,
  [in]           int  id,
  [in]           UINT fsModifiers,
  [in]           UINT vk
);

Parameters

[in, optional] hWnd

Type: HWND

A handle to the window that will receive WM_HOTKEY messages generated by the hot key. If this parameter is NULL, WM_HOTKEY messages are posted to the message queue of the calling thread and must be processed in the message loop.

[in] id

Type: int

The identifier of the hot key. If the hWnd parameter is NULL, then the hot key is associated with the current thread rather than with a particular window. If a hot key already exists with the same hWnd and id parameters, see Remarks for the action taken.

[in] fsModifiers

Type: UINT

The keys that must be pressed in combination with the key specified by the vk parameter in order to generate the WM_HOTKEY message. The fsModifiers parameter can be a combination of the following values.

Value Meaning
MOD_ALT
0x0001
Either ALT key must be held down.
MOD_CONTROL
0x0002
Either CTRL key must be held down.
MOD_NOREPEAT
0x4000
Changes the hotkey behavior so that the keyboard auto-repeat does not yield multiple hotkey notifications.
Windows Vista: This flag is not supported.
MOD_SHIFT
0x0004
Either SHIFT key must be held down.
MOD_WIN
0x0008
Either WINDOWS key must be held down. These keys are labeled with the Windows logo. Keyboard shortcuts that involve the WINDOWS key are reserved for use by the operating system.

[in] vk

Type: UINT

The virtual-key code of the hot key. See Virtual Key Codes.

Return value

Type: BOOL

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

This function fails if you try to associate a hot key with a window created by another thread.

Typically, RegisterHotKey also fails if the keystrokes specified for the hot key have already been registered for another hot key. However, some pre-existing, default hotkeys registered by the OS (such as PrintScreen, which launches the Snipping tool) may be overridden by another hot key registration when one of the app's windows is in the foreground.

Remarks

When a key is pressed, the system looks for a match against all hot keys. Upon finding a match, the system posts the WM_HOTKEY message to the message queue of the window with which the hot key is associated. If the hot key is not associated with a window, then the WM_HOTKEY message is posted to the thread associated with the hot key.

If a hot key already exists with the same hWnd and id parameters, it is maintained along with the new hot key. The application must explicitly call UnregisterHotKey to unregister the old hot key.

The F12 key is reserved for use by the debugger at all times, so it should not be registered as a hot key. Even when you are not debugging an application, F12 is reserved in case a kernel-mode debugger or a just-in-time debugger is resident.

An application must specify an id value in the range 0x0000 through 0xBFFF. A shared DLL must specify a value in the range 0xC000 through 0xFFFF (the range returned by the GlobalAddAtom function). To avoid conflicts with hot-key identifiers defined by other shared DLLs, a DLL should use the GlobalAddAtom function to obtain the hot-key identifier.

**Windows Server 2003:  **If a hot key already exists with the same hWnd and id parameters, it is replaced by the new hot key.

Examples

The following example shows how to use the RegisterHotKey function with the MOD_NOREPEAT flag.

In this example, the hotkey 'ALT+b' is registered for the main thread. When the hotkey is pressed, the thread will receive a WM_HOTKEY message, which will get picked up in the GetMessage call. Because this example uses MOD_ALT with the MOD_NOREPEAT value for fsModifiers, the thread will only receive another WM_HOTKEY message when the 'b' key is released and then pressed again while the 'ALT' key is being pressed down.

#include "stdafx.h"

int _cdecl _tmain (
    int argc, 
    TCHAR *argv[])
{           
    if (RegisterHotKey(
        NULL,
        1,
        MOD_ALT | MOD_NOREPEAT,
        0x42))  //0x42 is 'b'
    {
        _tprintf(_T("Hotkey 'ALT+b' registered, using MOD_NOREPEAT flag\n"));
    }
 
    MSG msg = {0};
    while (GetMessage(&msg, NULL, 0, 0) != 0)
    {
        if (msg.message == WM_HOTKEY)
        {
            _tprintf(_T("WM_HOTKEY received\n"));            
        }
    } 
 
    return 0;
}

Requirements

Requirement Value
Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Target Platform Windows
Header winuser.h (include Windows.h)
Library User32.lib
DLL User32.dll

See also

GlobalAddAtom

Keyboard Input

Register hotkey for the current app (CSRegisterHotkey)

Register hotkey for the current app (CppRegisterHotkey)

UnregisterHotKey

WM_HOTKEY