Export (0) Print
Expand All

RegisterHotKey function

Defines a system-wide hot key.

Syntax


BOOL WINAPI RegisterHotKey(
  _In_opt_  HWND hWnd,
  _In_      int id,
  _In_      UINT fsModifiers,
  _In_      UINT vk
);

Parameters

hWnd [in, optional]

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.

id [in]

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.

fsModifiers [in]

Type: UINT

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

ValueMeaning
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 and Windows XP/2000:  This flag is not supported.

MOD_SHIFT
0x0004

Either SHIFT key must be held down.

MOD_WIN
0x0008

Either WINDOWS key was 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.

 

vk [in]

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.

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.

This function cannot associate a hot key with a window created by another thread.

RegisterHotKey fails if the keystrokes specified for the hot key have already been registered by another 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.

Windows Server 2003, Windows XP, and Windows 2000:  If a hot key already exists with the same hWnd and id parameters, it is replaced by the new 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.

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;
}


To download the complete project, visit MSDN Code Gallery.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Winuser.h (include Windows.h)

Library

User32.lib

DLL

User32.dll

See also

Reference
GlobalAddAtom
UnregisterHotKey
WM_HOTKEY
Conceptual
Keyboard Input

 

 

Community Additions

ADD
Show:
© 2014 Microsoft