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.

[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

See also

GlobalAddAtom

Keyboard Input

Register hotkey for the current app (CSRegisterHotkey)

Register hotkey for the current app (CppRegisterHotkey)

UnregisterHotKey

WM_HOTKEY