registerHotKey 函式 (winuser.h)

發行項
03/04/2024

定義全系統的熱鍵。

語法

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 和 標識符 參數，請參閱以瞭解所採取的動作。

[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 和 標識符 參數，則會與新的熱鍵一起維護。應用程式必須明確呼叫 UnregisterHotKey ，才能取消註冊舊的熱鍵。

Windows Server 2003： 如果熱鍵已經存在具有相同 hWnd 和 標識符 參數，則會由新的熱鍵取代。

F12 金鑰會保留供調試程式隨時使用，因此不應註冊為熱鍵。即使您未偵錯應用程式，F12 仍會保留，以防內核模式調試程式或 Just-In-Time 調試程式是駐留的。

應用程式必須在範圍0x0000 0xBFFF中指定標識碼值。共用 DLL 必須在範圍0xC000 0xFFFF (GlobalAddAtom 函式所傳回的範圍) 指定值。為了避免與其他共用 DLL 所定義的熱鍵標識符發生衝突，DLL 應該使用 GlobalAddAtom 函式來取得熱鍵識別碼。

範例

下列範例示範如何使用 RegisterHotKey 函式搭配 MOD_NOREPEAT 旗標。在此範例中，主線程會註冊快捷鍵『ALT+b』。按下快捷鍵時，線程會收到 WM_HOTKEY 訊息，這會在 GetMessage 呼叫中挑選。由於此範例會使用 MOD_ALT 搭配 fsModifiers的MOD_NOREPEAT值，因此線程只會在 'b' 鍵放開時收到另一個WM_HOTKEY訊息，然後在按下 '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
標頭	winuser.h (包含 Windows.h)
程式庫	User32.lib
Dll	User32.dll