Función ToUnicodeEx (winuser.h)

Artículo
04/14/2023

Traduce el código de tecla virtual y el estado del teclado especificados al carácter o caracteres Unicode correspondientes.

Sintaxis

int ToUnicodeEx(
  [in]           UINT       wVirtKey,
  [in]           UINT       wScanCode,
  [in]           const BYTE *lpKeyState,
  [out]          LPWSTR     pwszBuff,
  [in]           int        cchBuff,
  [in]           UINT       wFlags,
  [in, optional] HKL        dwhkl
);

Parámetros

[in] wVirtKey

Tipo: UINT

Código de clave virtual que se va a traducir. Consulte Códigos de clave virtual.

[in] wScanCode

Tipo: UINT

Código de examen de hardware de la clave que se va a traducir. El bit de orden superior de este valor se establece si la clave está arriba.

[in] lpKeyState

Tipo: const BYTE*

Puntero a una matriz de 256 bytes que contiene el estado actual del teclado. Cada elemento (byte) de la matriz contiene el estado de una clave.

Si se establece el bit de orden superior de un byte, la clave está inactiva. El bit bajo, si se establece, indica que la tecla está activada. En esta función, solo es relevante el bit de alternancia de la tecla CAPS LOCK. Se omite el estado de alternancia de las teclas NUM LOCK y SCROLL LOCK. Consulta GetKeyboardState para obtener más información.

[out] pwszBuff

Tipo: LPWSTR

Búfer que recibe el carácter traducido o caracteres como matriz de unidades de código UTF-16. Este búfer se puede devolver sin terminar en null, aunque el nombre de la variable sugiere que está terminado en null. Puede usar el valor devuelto de este método para determinar cuántos caracteres se escribieron.

[in] cchBuff

Tipo: int

Tamaño, en caracteres, del búfer al que apunta el parámetro pwszBuff .

[in] wFlags

Tipo: UINT

Comportamiento de la función.

Si se establece el bit 0, hay un menú activo. En este modo, no se controlan las combinaciones de teclas alt+numéricas del teclado .

Si se establece el bit 1, ToUnicodeEx traducirá los códigos de examen marcados como eventos de interrupción de clave además de su tratamiento habitual de eventos de creación de claves.

Si se establece el bit 2, el estado del teclado no cambia (Windows 10, versión 1607 y posterior)

Todos los demás bits (hasta 31) están reservados.

[in, optional] dwhkl

Tipo: HKL

Identificador de configuración regional de entrada utilizado para traducir el código especificado. Este parámetro puede ser cualquier identificador de configuración regional de entrada devuelto anteriormente por la función LoadKeyboardLayout .

Valor devuelto

Tipo: int

La función devuelve uno de los valores siguientes.

Valor devuelto	Descripción
valor< 0	La clave virtual especificada es un carácter de tecla muerto (énfasis o diacrítico). Este valor se devuelve independientemente del diseño del teclado, incluso si se han escrito varios caracteres y se almacenan en el estado del teclado. Si es posible, incluso con diseños de teclado Unicode, la función ha escrito una versión de espaciado del carácter de tecla inactiva en el búfer especificado por pwszBuff. Por ejemplo, la función escribe el carácter ACUTE ACCENT (U+00B4), en lugar del carácter COMBINING ACUTE ACCENT (U+0301).
0	La tecla virtual especificada no tiene traducción para el estado actual del teclado. No se escribió nada en el búfer especificado por pwszBuff.
valor > 0	Una o varias unidades de código UTF-16 se escribieron en el búfer especificado por pwszBuff. PwszBuff devuelto puede contener más caracteres que los especificados por el valor devuelto. Cuando esto sucede, los caracteres adicionales no son válidos y deben omitirse.

Comentarios

El identificador de configuración regional de entrada es un concepto más amplio que un diseño de teclado, ya que también puede abarcar un convertidor de voz a texto, un método de entrada Editor (IME) o cualquier otra forma de entrada.

Algunos diseños de teclado pueden devolver varios caracteres o caracteres complementarios como pares suplentes en pwszBuff. Si el carácter de tecla muerto (énfasis o diacrítico) almacenado en el diseño del teclado no se pudo combinar con la tecla virtual especificada para formar un solo carácter, el carácter muerto especificado anteriormente se puede combinar con el carácter actual.

Es posible que los parámetros proporcionados a la función ToUnicodeEx no sean suficientes para traducir el código de tecla virtual porque se almacena una tecla muerta anterior en el diseño del teclado.

Normalmente, ToUnicodeEx realiza la traducción en función del código de clave virtual. Sin embargo, en algunos casos, el bit 15 del parámetro wScanCode se puede usar para distinguir entre una tecla presionada y una liberación de teclas (por ejemplo, para la entrada de tecla ALT+numpad).

Como ToUnicodeEx traduce el código de tecla virtual, también cambia el estado del búfer de teclado en modo kernel. Este cambio de estado afecta a las teclas inactivas, ligaduras, entrada de teclado alt+numérico , etc. También podría causar efectos secundarios no deseados si se usa junto con TranslateMessage (que también cambia el estado del búfer de teclado en modo kernel).

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winuser.h (incluya Windows.h)
Library	User32.lib
Archivo DLL	User32.dll