Функция RegisterHotKey (winuser.h)

Статья
08/27/2023

Определяет горячий ключ на уровне системы.

Синтаксис

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

Параметры

[in, optional] hWnd

Тип: HWND

Дескриптор окна, который будет получать WM_HOTKEY сообщения, созданные горячей клавишей. Если этот параметр имеет значение NULL, WM_HOTKEY сообщения отправляются в очередь сообщений вызывающего потока и должны обрабатываться в цикле сообщений.

[in] id

Тип: int

Идентификатор горячего ключа. Если параметр hWnd имеет значение NULL, то горячий ключ связывается с текущим потоком, а не с определенным окном. Если горячий ключ уже существует с теми же параметрами hWnd и id , см. примечания о выполненных действиях.

[in] fsModifiers

Тип: UINT

Клавиши, которые должны быть нажаты в сочетании с клавишей, указанной параметром vk , чтобы создать сообщение WM_HOTKEY . Параметр fsModifiers может быть сочетанием следующих значений.

Значение	Значение
MOD_ALT 0x0001	Обе клавиши ALT должны быть удержаны.
MOD_CONTROL 0x0002	Прижата любая клавиша CTRL.
MOD_NOREPEAT 0x4000	Изменяет поведение клавиши так, чтобы автоматический повтор клавиатуры не возвращал несколько уведомлений с помощью клавиш горячей клавиши. Windows Vista: Этот флаг не поддерживается.
MOD_SHIFT 0x0004	Обе клавиши SHIFT должны быть удерживаются.
MOD_WIN 0x0008	Любая клавиша WINDOWS была удержана. Эти клавиши помечены логотипом Windows. Сочетания клавиш, включающие клавишу WINDOWS, зарезервированы для использования операционной системой.

[in] vk

Тип: UINT

Код виртуального ключа горячего ключа. См . раздел Коды виртуальных ключей.

Возвращаемое значение

Тип: BOOL

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

При нажатии клавиши система ищет совпадение со всеми горячими клавишами. После поиска совпадения система отправляет сообщение WM_HOTKEY в очередь сообщений окна, с которым связана горячая клавиша. Если горячая клавиша не связана с окном, сообщение WM_HOTKEY будет отправлено в поток, связанный с горячей клавишей.

Эта функция не может связать горячий ключ с окном, созданным другим потоком.

RegisterHotKey завершается ошибкой , если нажатия клавиш, указанные для горячего ключа, уже зарегистрированы другим горячим ключом.

Если горячий ключ уже существует с теми же параметрами hWnd и id , он сохраняется вместе с новым горячим ключом. Приложение должно явно вызвать UnregisterHotKey , чтобы отменить регистрацию старого горячего ключа.

Windows Server 2003: Если горячий ключ уже существует с теми же параметрами hWnd и id , он заменяется новым горячим ключом.

Ключ F12 зарезервирован для постоянного использования отладчиком, поэтому его не следует регистрировать как горячий ключ. Даже если вы не выполняете отладку приложения, F12 резервируется на случай, если отладчик режима ядра или JIT-отладчик является резидентом.

Приложение должно указать значение идентификатора в диапазоне 0x0000 по 0xBFFF. Общая библиотека DLL должна указывать значение в диапазоне 0xC000 по 0xFFFF (диапазон, возвращаемый функцией GlobalAddAtom ). Чтобы избежать конфликтов с идентификаторами горячих ключей, определенными другими общими библиотеками DLL, библиотека DLL должна использовать функцию GlobalAddAtom для получения идентификатора горячего ключа.

Примеры

В следующем примере показано, как использовать функцию RegisterHotKey с флагом MOD_NOREPEAT . В этом примере для потока main регистрируется горячая клавиша ALT+b. После нажатия клавиши поток получит WM_HOTKEY сообщение, которое будет получено в вызове GetMessage . Так как в этом примере используется MOD_ALT со значением MOD_NOREPEAT для fsModifiers, поток получит другое сообщение WM_HOTKEY только при освобождении клавиши "b", а затем снова нажатой клавиши ALT.


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

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	winuser.h (включая Windows.h)
Библиотека	User32.lib
DLL	User32.dll