Funzione RegisterHotKey (winuser.h)

Articolo
07/16/2024

Definisce un tasto 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 per la finestra che riceverà WM_HOTKEY messaggi generati dal tasto di scelta rapida. Se questo parametro è NULL, WM_HOTKEY messaggi vengono inviati alla coda di messaggi del thread chiamante e devono essere elaborati nel ciclo di messaggi.

[in] id

Tipo: int

Identificatore del tasto di scelta rapida. Se il parametro hWnd è NULL, il tasto di scelta rapida viene associato al thread corrente anziché a una determinata finestra. Se esiste già un tasto di scelta rapida con lo stesso hWnd e id parametri, vedere La sezione 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	Entrambi i tasti ALT devono essere mantenuti.
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 tasto di scelta rapida. Windows Vista: Questo flag non è supportato.
MOD_SHIFT 0x0004	Il tasto MAIUSC deve essere premuto.
MOD_WIN 0x0008	È necessario tenere premuto uno dei due tasti WINDOWS. Queste chiavi sono etichettate con il logo di Windows. I tasti di scelta rapida che coinvolgono il tasto WINDOWS sono riservati per l'uso da parte del sistema operativo.

[in] vk

Tipo: UINT

Codice della chiave virtuale del tasto di scelta rapida. Vedere Codici di 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 ottenere informazioni estese sull'errore, chiamare GetLastError.

Questa funzione ha esito negativo se si tenta di associare un tasto di scelta rapida a una finestra creata da un altro thread.

In genere, RegisterHotKey anche se le sequenze di tasti specificate per il tasto di scelta rapida sono già state registrate per un altro tasto di scelta rapida. Tuttavia, alcuni tasti di scelta rapida predefiniti registrati dal sistema operativo (ad esempio PrintScreen, che avvia lo strumento Snipping) possono essere sottoposti a override da un'altra registrazione con chiave di scelta rapida quando una delle finestre dell'app è in primo piano.

Osservazioni

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

Se esiste già un tasto di scelta rapida con lo stesso hWnd e i parametri ID, viene mantenuto insieme al nuovo tasto di scelta rapida. L'applicazione deve chiamare in modo esplicito UnregisterHotKey per annullare la registrazione del tasto di scelta rapida precedente.

La chiave F12 è riservata per l'uso da parte del debugger in qualsiasi momento, pertanto non deve essere registrata come tasto di scelta rapida. Anche quando non si esegue il debug di un'applicazione, F12 è riservato nel caso in cui si trovi un debugger in modalità kernel o un debugger JIT.

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

**Windows Server 2003: **Se esiste già un tasto di scelta rapida con lo stesso hWnd e id parametri, viene sostituito dal nuovo tasto di scelta rapida.

Esempi

Nell'esempio seguente viene illustrato come usare la funzione RegisterHotKey con il flag MOD_NOREPEAT.

In questo esempio, il tasto di scelta rapida "ALT+b" viene registrato per il thread principale. Quando si preme il tasto di scelta rapida, il thread riceverà un messaggio di WM_HOTKEY, che verrà prelevato nella chiamata GetMessage. Poiché questo esempio usa MOD_ALT con il valore di MOD_NOREPEAT per fsModifiers, il thread riceverà solo un altro messaggio WM_HOTKEY quando il tasto 'b' viene rilasciato e quindi premuto di nuovo mentre viene premuto il tasto '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;
}

Fabbisogno

Requisito	Valore
client minimo supportato	Windows Vista [solo app desktop]
server minimo supportato	Windows Server 2003 [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	winuser.h (include Windows.h)
libreria	User32.lib
dll	User32.dll