Funzione RegisterHotKey (winuser.h)

Articolo
03/04/2024

Definisce una chiave di scelta rapida a livello di sistema.

Sintassi

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

Parametri

[in, optional] hWnd

Tipo: HWND

Handle alla finestra che riceverà WM_HOTKEY messaggi generati dalla chiave di scelta rapida. Se questo parametro è NULL, WM_HOTKEY i messaggi vengono pubblicati nella coda dei messaggi del thread chiamante e devono essere elaborati nel ciclo del messaggio.

[in] id

Tipo: int

Identificatore della chiave di scelta rapida. Se il parametro hWnd è NULL, il tasto di scelta rapida è associato al thread corrente anziché a una determinata finestra. Se esiste già una chiave di scelta rapida con gli stessi parametri hWnd e ID , vedere Osservazioni per l'azione eseguita.

[in] fsModifiers

Tipo: UINT

I tasti che devono essere premuti in combinazione con il tasto specificato dal parametro vk per generare il messaggio di WM_HOTKEY . Il parametro fsModifiers può essere una combinazione dei valori seguenti.

Valore	Significato
MOD_ALT 0x0001	È necessario tenere premuto il tasto ALT.
MOD_CONTROL 0x0002	È necessario tenere premuto il tasto CTRL.
MOD_NOREPEAT 0x4000	Modifica il comportamento del tasto di scelta rapida in modo che la ripetizione automatica della tastiera non restituisca più notifiche con tasti di scelta rapida. Windows Vista: Questo flag non è supportato.
MOD_SHIFT 0x0004	È necessario tenere premuto il tasto MAIUSC.
MOD_WIN 0x0008	La chiave WINDOWS è stata tenuta premuta. Queste chiavi vengono etichettate con il logo di Windows. I tasti di scelta rapida che coinvolgono il tasto WINDOWS sono riservati per l'uso dal sistema operativo.

[in] vk

Tipo: UINT

Codice della chiave virtuale della chiave di scelta rapida. Vedere Codici chiave virtuale.

Valore restituito

Tipo: BOOL

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Quando viene premuto un tasto, il sistema cerca una corrispondenza con tutti i tasti di scelta rapida. Dopo aver trovato una corrispondenza, il sistema pubblica il messaggio di WM_HOTKEY alla coda di messaggi della finestra con cui è associata la chiave di scelta rapida. Se il tasto di scelta rapida non è associato a una finestra, il messaggio di WM_HOTKEY viene inviato al thread associato alla chiave di scelta rapida.

Questa funzione non può associare una chiave di scelta rapida a una finestra creata da un altro thread.

RegisterHotKey ha esito negativo se le sequenze di tasti specificate per la chiave di scelta rapida sono già state registrate da un'altra chiave di scelta rapida.

Se esiste già una chiave di scelta rapida con gli stessi parametri hWnd e ID , viene mantenuta insieme alla nuova chiave di scelta rapida. L'applicazione deve chiamare in modo esplicito UnregisterHotKey per annullare la registrazione della chiave di scelta rapida precedente.

Windows Server 2003: Se esiste già una chiave di scelta rapida con gli stessi parametri hWnd e ID , viene sostituito dalla nuova chiave di scelta rapida.

La chiave F12 è riservata all'uso da parte del debugger in ogni momento, quindi non deve essere registrata come chiave di scelta rapida. Anche quando non si esegue il debug di un'applicazione, F12 è riservato nel caso in cui un debugger in modalità kernel o un debugger just-in-time sia residente.

Un'applicazione deve specificare un valore ID nell'intervallo 0x0000 tramite 0xBFFF. Una DLL condivisa deve specificare un valore nell'intervallo 0xC000 tramite 0xFFFF (intervallo restituito dalla funzione GlobalAddAtom ). Per evitare conflitti con identificatori a chiave rapida definiti da altre DLL condivise, una DLL deve usare la funzione GlobalAddAtom per ottenere l'identificatore a chiave rapida.

Esempio

Nell'esempio seguente viene illustrato come usare la funzione RegisterHotKey con il flag di MOD_NOREPEAT . In questo esempio, il tasto di scelta rapida "ALT+b" viene registrato per il thread principale. Quando viene premuto il tasto di scelta rapida, il thread riceverà un messaggio di WM_HOTKEY , che verrà raccolto nella chiamata GetMessage . Poiché questo esempio usa MOD_ALT con il valore MOD_NOREPEAT per fsModifiers, il thread riceverà solo un altro messaggio WM_HOTKEY quando viene rilasciato il tasto 'b' e quindi premuto di nuovo mentre il tasto 'ALT' viene premuto verso il basso.


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

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winuser.h (include Windows.h)
Libreria	User32.lib
DLL	User32.dll