Función RegisterHotKey (winuser.h)

Artículo
07/16/2024

Define una clave activa de todo el sistema.

Sintaxis

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

Parámetros

[in, optional] hWnd

Tipo: HWND

Identificador de la ventana que recibirá WM_HOTKEY mensajes generados por la tecla activa. Si este parámetro es null, los mensajes de WM_HOTKEY se publican en la cola de mensajes del subproceso de llamada y se deben procesar en el bucle de mensajes.

[in] id

Tipo: int

Identificador de la clave activa. Si el parámetro hWnd es NULL, la clave activa se asocia con el subproceso actual en lugar de con una ventana determinada. Si ya existe una clave activa con la misma hWnd y id. parámetros, vea Comentarios para la acción realizada.

[in] fsModifiers

Tipo: UINT

Las teclas que se deben presionar en combinación con la tecla especificada por el parámetro vk para generar el mensaje de WM_HOTKEY. El parámetro fsModifiers puede ser una combinación de los valores siguientes.

valor	significado
MOD_ALT 0x0001	Cualquier tecla ALT debe mantenerse presionada.
MOD_CONTROL 0x0002	Se debe mantener presionada la tecla CTRL.
MOD_NOREPEAT 0x4000	Cambia el comportamiento de la tecla de acceso rápido para que el teclado repita automáticamente no produzca varias notificaciones de teclas de acceso rápido. Windows Vista: Esta marca no se admite.
MOD_SHIFT 0x0004	Se debe mantener presionada la tecla MAYÚS.
MOD_WIN 0x0008	Se debe mantener presionada cualquiera de las teclas WINDOWS. Estas claves se etiquetan con el logotipo de Windows. Los métodos abreviados de teclado que implican la tecla WINDOWS están reservados para su uso por parte del sistema operativo.

[in] vk

Tipo: UINT

Código de clave virtual de la clave activa. Consulte códigos de clave virtual.

Valor devuelto

Tipo: BOOL de

Si la función se ejecuta correctamente, el valor devuelto es distinto de cero.

Si se produce un error en la función, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Esta función produce un error si intenta asociar una clave activa a una ventana creada por otro subproceso.

Normalmente, RegisterHotKey también produce un error si las pulsaciones de tecla especificadas para la tecla activa ya se han registrado para otra tecla activa. Sin embargo, algunas teclas de acceso rápido predeterminadas y preexistentes registradas por el sistema operativo (como PrintScreen, que inicia la herramienta Snipping) pueden invalidarse mediante otro registro de teclas activas cuando una de las ventanas de la aplicación está en primer plano.

Observaciones

Cuando se presiona una tecla, el sistema busca una coincidencia con todas las teclas de acceso rápido. Después de encontrar una coincidencia, el sistema envía el mensaje WM_HOTKEY a la cola de mensajes de la ventana con la que está asociada la tecla activa. Si la tecla activa no está asociada a una ventana, el mensaje de WM_HOTKEY se publica en el subproceso asociado a la tecla activa.

Si ya existe una clave activa con el mismo hWnd y id parámetros, se mantiene junto con la nueva clave activa. La aplicación debe llamar explícitamente a UnregisterHotKey para anular el registro de la clave activa anterior.

La clave F12 está reservada para su uso por parte del depurador en todo momento, por lo que no debe registrarse como una clave activa. Incluso cuando no depura una aplicación, F12 está reservado en caso de que un depurador en modo kernel o un depurador Just-In-Time resida.

Una aplicación debe especificar un valor id en el intervalo 0x0000 a través de 0xBFFF. Un archivo DLL compartido debe especificar un valor en el intervalo 0xC000 a través de 0xFFFF (el intervalo devuelto por la función GlobalAddAtom ). Para evitar conflictos con identificadores de clave activa definidos por otros archivos DLL compartidos, un archivo DLL debe usar la función GlobalAddAtom para obtener el identificador de clave activa.

**Windows Server 2003: **Si ya existe una clave activa con la misma hWnd y id parámetros, se reemplaza por la nueva clave activa.

Ejemplos

En el ejemplo siguiente se muestra cómo usar la función RegisterHotKey con la marca MOD_NOREPEAT.

En este ejemplo, la tecla de acceso rápido "ALT+b" se registra para el subproceso principal. Cuando se presiona la tecla de acceso rápido, el subproceso recibirá un mensaje WM_HOTKEY, que se recogerá en la llamada GetMessage. Dado que en este ejemplo se usa MOD_ALT con el valor de MOD_NOREPEAT para fsModifiers, el subproceso solo recibirá otro mensaje de WM_HOTKEY cuando se libere la tecla "b" y, a continuación, se presione de nuevo mientras se presiona la tecla "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;
}

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows Vista [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows Server 2003 [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	winuser.h (incluya Windows.h)
biblioteca de	User32.lib
DLL de	User32.dll