RegisterHotKey-Funktion (winuser.h)

Artikel
07/16/2024

Definiert einen systemweiten Hot key.

Syntax

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

Parameter

[in, optional] hWnd

Typ: HWND-

Ein Handle für das Fenster, das WM_HOTKEY Nachrichten empfängt, die von der Abkürzungstaste generiert werden. Wenn dieser Parameter NULL-ist, werden WM_HOTKEY Nachrichten in die Nachrichtenwarteschlange des aufrufenden Threads gepostet und müssen in der Nachrichtenschleife verarbeitet werden.

[in] id

Typ: int

Der Bezeichner der Abkürzungstaste. Wenn der hWnd Parameter NULL ist, wird der Hot key dem aktuellen Thread und nicht einem bestimmten Fenster zugeordnet. Wenn bereits ein Hot Key mit demselben hWnd- vorhanden ist und ID Parametern vorhanden ist, finden Sie informationen zu den ausgeführten Aktionen.

[in] fsModifiers

Typ: UINT-

Die Tasten, die in Kombination mit der durch den vk Parameter angegebenen Taste gedrückt werden müssen, um die WM_HOTKEY Nachricht zu generieren. Der fsModifiers Parameter kann eine Kombination der folgenden Werte sein.

Wert	Bedeutung
MOD_ALT 0x0001	Beide ALT-TASTE müssen gedrückt gehalten werden.
MOD_CONTROL 0x0002	Beide STRG-TASTE müssen gedrückt gehalten werden.
MOD_NOREPEAT 0x4000	Ändert das Hotkey-Verhalten, sodass die Tastatur automatisch wiederholt nicht mehrere Hotkey-Benachrichtigungen liefert. Windows Vista: Dieses Flag wird nicht unterstützt.
MOD_SHIFT 0x0004	Beide UMSCHALTTASTEn müssen gedrückt gehalten werden.
MOD_WIN 0x0008	Beide WINDOWS-Taste müssen gedrückt gehalten werden. Diese Tasten werden mit dem Windows-Logo beschriftet. Tastenkombinationen, die die WINDOWS-Taste umfassen, sind für die Verwendung durch das Betriebssystem reserviert.

[in] vk

Typ: UINT-

Der virtuelle Schlüsselcode der Abkürzungstaste. Siehe virtuelle Schlüsselcodes.

Rückgabewert

Typ: BOOL-

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlschlägt, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Diese Funktion schlägt fehl, wenn Sie versuchen, einen Hot Key einem Fenster zuzuordnen, das von einem anderen Thread erstellt wurde.

In der Regel schlägt RegisterHotKey auch fehl, wenn die für den Hot Key angegebenen Tastenfolgen bereits für einen anderen Hot Key registriert wurden. Einige bereits vorhandene Standard-Hotkeys, die vom Betriebssystem registriert wurden (z. B. PrintScreen, das das Snipping-Tool startet), werden jedoch möglicherweise durch eine weitere Registrierung mit Hot Key überschrieben, wenn sich eines der Fenster der App im Vordergrund befindet.

Bemerkungen

Wenn eine Taste gedrückt wird, sucht das System nach einer Übereinstimmung mit allen Tastenkombinationen. Nach dem Suchen einer Übereinstimmung sendet das System die WM_HOTKEY Nachricht in die Nachrichtenwarteschlange des Fensters, dem die Abkürzungstaste zugeordnet ist. Wenn die Abkürzungstaste keinem Fenster zugeordnet ist, wird die WM_HOTKEY Nachricht an den Thread gepostet, der dem Hot key zugeordnet ist.

Wenn bereits ein Hot Key mit demselben hWnd- und ID- Parameter vorhanden ist, wird er zusammen mit dem neuen Hot key beibehalten. Die Anwendung muss explizit UnregisterHotKey- aufrufen, um die Registrierung des alten Hot Keys aufzuheben.

Der F12-Schlüssel ist für die Verwendung durch den Debugger jederzeit reserviert, sodass er nicht als Hot Key registriert werden sollte. Selbst wenn Sie keine Anwendung debuggen, ist F12 reserviert, falls ein Kernelmodusdebugger oder ein Just-in-Time-Debugger vorhanden ist.

Eine Anwendung muss einen ID-Wert im Bereich angeben, der bis 0xBFFF 0x0000. Eine freigegebene DLL muss einen Wert im Bereich 0xC000 bis 0xFFFF angeben (der von der GlobalAddAtom--Funktion zurückgegebene Bereich). Um Konflikte mit Hot-Key-IDs zu vermeiden, die von anderen freigegebenen DLLs definiert werden, sollte eine DLL die GlobalAddAtom--Funktion verwenden, um den Hot-Key-Bezeichner abzurufen.

**Windows Server 2003: **Wenn bereits ein Hot Key mit demselben hWnd- und ID Parameter vorhanden ist, wird sie durch den neuen Hot key ersetzt.

Beispiele

Das folgende Beispiel zeigt, wie Sie die RegisterHotKey--Funktion mit dem MOD_NOREPEAT-Flag verwenden.

In diesem Beispiel wird der Hotkey "ALT+b" für den Hauptthread registriert. Wenn der Hotkey gedrückt wird, empfängt der Thread eine WM_HOTKEY Nachricht, die im GetMessage Anruf aufgenommen wird. Da in diesem Beispiel MOD_ALT mit dem MOD_NOREPEAT Wert für fsModifiersverwendet wird, empfängt der Thread nur eine weitere WM_HOTKEY Nachricht, wenn die Taste "b" losgelassen wird und dann erneut gedrückt wird, während die ALT-TASTE gedrückt wird.

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

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows Vista [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	winuser.h (enthalten Windows.h)
Library	User32.lib
DLL-	User32.dll