RegisterHotKey-Funktion (winuser.h)

Artikel
03/06/2024

Definiert eine systemweite Abkürzungstaste

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 vom Hot key generiert werden. Wenn dieser Parameter NULL ist, werden WM_HOTKEY Nachrichten an die Nachrichtenwarteschlange des aufrufenden Threads gesendet und müssen in der Nachrichtenschleife verarbeitet werden.

[in] id

Typ: int

Der Bezeichner des Schlüssels. 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 denselben hWnd - und id-Parametern vorhanden ist, lesen Sie die Hinweise zur ausgeführten Aktion.

[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 Meldung zu generieren. Der fsModifiers-Parameter kann eine Kombination der folgenden Werte sein.

Wert	Bedeutung
MOD_ALT 0x0001	Beide ALT-Tasten müssen gedrückt gehalten werden.
MOD_CONTROL 0x0002	Beide Tastenkombinationen müssen gedrückt gehalten werden.
MOD_NOREPEAT 0x4000	Ändert das Verhalten der Tastenkombination, sodass die automatische Tastaturwiederholung keine Benachrichtigungen mit mehreren Hotkeys liefert. Windows Vista: Dieses Flag wird nicht unterstützt.
MOD_SHIFT 0x0004	Beide UMSCHALTTASTEn müssen gedrückt gehalten werden.
MOD_WIN 0x0008	Eine WINDOWSTASTE wurde gedrückt gehalten. Diese Tasten sind mit dem Windows-Logo gekennzeichnet. Tastenkombinationen, die die WINDOWS-Taste enthalten, sind für die Verwendung durch das Betriebssystem reserviert.

[in] vk

Typ: UINT

Der Virtuelle Schlüsselcode des Schlüssels. Weitere Informationen finden Sie unter Virtuelle Schlüsselcodes.

Rückgabewert

Typ: BOOL

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

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Wenn eine Taste gedrückt wird, sucht das System nach einer Übereinstimmung mit allen Tastenkombinationen. Wenn eine Übereinstimmung gefunden wird, sendet das System die WM_HOTKEY Nachricht an die Nachrichtenwarteschlange des Fensters, dem der Hot key zugeordnet ist. Wenn die Tastenkombination nicht einem Fenster zugeordnet ist, wird die WM_HOTKEY Meldung an den Thread gesendet, der dem Hot key zugeordnet ist.

Diese Funktion kann einem Fenster, das von einem anderen Thread erstellt wurde, keine Hot Key-Taste zuordnen.

RegisterHotKey schlägt fehl, wenn die für den Hot key angegebenen Tastatureingaben bereits von einem anderen Hot key registriert wurden.

Wenn bereits ein Hot Key mit denselben hWnd - und id-Parametern vorhanden ist, wird er zusammen mit dem neuen Hot Key verwaltet. Die Anwendung muss explizit UnregisterHotKey aufrufen, um die Registrierung des alten Hot Keys aufzuheben.

Windows Server 2003: Wenn bereits ein Hot Key mit denselben hWnd - und id-Parametern vorhanden ist, wird er durch den neuen Hot key ersetzt.

Die F12-Taste ist jederzeit für die Verwendung durch den Debugger reserviert, sodass sie nicht als Hot Key registriert werden sollte. Auch 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 angeben, der 0xC000 bis 0xFFFF (der bereich, der von der GlobalAddAtom-Funktion zurückgegeben wird). Um Konflikte mit Hot-Key-Bezeichnern zu vermeiden, die von anderen freigegebenen DLLs definiert werden, sollte eine DLL die GlobalAddAtom-Funktion verwenden, um den Hot-Key-Bezeichner abzurufen.

Beispiele

Im folgenden Beispiel wird gezeigt, wie die RegisterHotKey-Funktion mit dem MOD_NOREPEAT-Flag verwendet wird. In diesem Beispiel wird der Hotkey "ALT+b" für den Standard Thread registriert. Wenn die Hotkey gedrückt wird, erhält der Thread eine WM_HOTKEY Nachricht, die im GetMessage-Aufruf erfasst wird. Da in diesem Beispiel MOD_ALT mit dem MOD_NOREPEAT-Wert für fsModifiers verwendet wird, erhält der Thread nur eine weitere WM_HOTKEY Meldung, wenn die Taste "b" losgelassen 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
Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winuser.h (windows.h einschließen)
Bibliothek	User32.lib
DLL	User32.dll