Função RegisterHotKey (winuser.h)

Artigo
08/27/2023

Define uma tecla de acesso para todo o sistema.

Sintaxe

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

Parâmetros

[in, optional] hWnd

Digite: HWND

Um identificador para a janela que receberá WM_HOTKEY mensagens geradas pela tecla de acesso. Se esse parâmetro for NULL, WM_HOTKEY mensagens serão postadas na fila de mensagens do thread de chamada e deverão ser processadas no loop de mensagem.

[in] id

Tipo: int

O identificador da tecla de acesso. Se o parâmetro hWnd for NULL, a tecla de acesso será associada ao thread atual em vez de a uma janela específica. Se já existir uma tecla de acesso com os mesmos parâmetros hWnd e id , consulte Comentários para a ação executada.

[in] fsModifiers

Tipo: UINT

As teclas que devem ser pressionadas em combinação com a tecla especificada pelo parâmetro vk para gerar a mensagem WM_HOTKEY . O parâmetro fsModifiers pode ser uma combinação dos valores a seguir.

Valor	Significado
MOD_ALT 0x0001	Qualquer tecla ALT deve ser mantida pressionada.
MOD_CONTROL 0x0002	Qualquer tecla CTRL deve ser mantida pressionada.
MOD_NOREPEAT 0x4000	Altera o comportamento da tecla de atalho para que a repetição automática do teclado não gere várias notificações de tecla de acesso. Windows Vista: Não há suporte para esse sinalizador.
MOD_SHIFT 0x0004	Qualquer tecla SHIFT deve ser mantida pressionada.
MOD_WIN 0x0008	Alguma tecla WINDOWS foi mantida pressionada. Essas teclas estão rotuladas com o logotipo do Windows. Os atalhos de teclado que envolvem a tecla WINDOWS são reservados para uso pelo sistema operacional.

[in] vk

Tipo: UINT

O código de chave virtual da tecla de acesso. Confira Códigos de chave virtual.

Retornar valor

Tipo: BOOL

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Quando uma tecla é pressionada, o sistema procura uma correspondência em relação a todas as teclas de acesso. Ao encontrar uma correspondência, o sistema posta a mensagem WM_HOTKEY na fila de mensagens da janela à qual a tecla de acesso está associada. Se a tecla de acesso não estiver associada a uma janela, a mensagem WM_HOTKEY será postada no thread associado à tecla de acesso.

Essa função não pode associar uma tecla de acesso a uma janela criada por outro thread.

RegisterHotKey falhará se os pressionamentos de tecla especificados para a tecla de acesso já tiverem sido registrados por outra tecla de acesso.

Se uma tecla de acesso já existir com os mesmos parâmetros hWnd e id , ela será mantida junto com a nova tecla de acesso. O aplicativo deve chamar Explicitamente UnregisterHotKey para cancelar o registro da tecla de acesso antiga.

Windows Server 2003: Se uma tecla de acesso já existir com os mesmos parâmetros hWnd e id , ela será substituída pela nova tecla de acesso.

A tecla F12 é reservada para uso pelo depurador o tempo todo, portanto, não deve ser registrada como uma tecla de acesso. Mesmo quando você não está depurando um aplicativo, F12 é reservado caso um depurador no modo kernel ou um depurador just-in-time seja residente.

Um aplicativo deve especificar um valor de ID no intervalo 0x0000 até 0xBFFF. Uma DLL compartilhada deve especificar um valor no intervalo 0xC000 até 0xFFFF (o intervalo retornado pela função GlobalAddAtom ). Para evitar conflitos com identificadores de chave quente definidos por outras DLLs compartilhadas, uma DLL deve usar a função GlobalAddAtom para obter o identificador de chave quente.

Exemplos

O exemplo a seguir mostra como usar a função RegisterHotKey com o sinalizador MOD_NOREPEAT . Neste exemplo, a tecla de atalho 'ALT+b' é registrada para o thread de main. Quando a tecla de acesso for pressionada, o thread receberá uma mensagem WM_HOTKEY , que será captada na chamada GetMessage . Como este exemplo usa MOD_ALT com o valor MOD_NOREPEAT para fsModifiers, o thread só receberá outra mensagem WM_HOTKEY quando a tecla 'b' for liberada e pressionada novamente enquanto a tecla 'ALT' estiver sendo pressionada para baixo.


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

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winuser.h (inclua Windows.h)
Biblioteca	User32.lib
DLL	User32.dll