Compartir a través de

Función ToUnicodeEx (winuser.h)

  • Artículo

Convierte el código de tecla virtual y el estado de teclado especificados en el 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 Virtual-Key Códigos.

[in] wScanCode

Tipo: UINT

El hardware código de examen 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 clave está activada. En esta función, solo es relevante el bit de alternancia de la tecla LOCK CAPS. El estado de alternancia de las teclas NUM LOCK y SCROLL LOCK se omite. Consulta GetKeyboardState para obtener más información.

[out] pwszBuff

Tipo: LPWSTR

Búfer que recibe el carácter traducido o los 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 han escrito.

[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+Numeric teclas.

Si se establece el bit 1, toUnicodeEx traducirá los códigos de examen marcados como eventos de interrupción 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 posteriores)

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

[in, optional] dwhkl

Tipo: HKL de

Identificador de configuración regional de entrada que se usa 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 siguientes valores.

Valor devuelto Descripción
valor < 0
La clave virtual especificada es un clave muerta carácter (é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. Se devuelve pwszBuff puede contener más caracteres que los especificados en el valor devuelto. Cuando esto sucede, los caracteres adicionales no son válidos y deben omitirse.

Observaciones

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 Editor de métodos de entrada (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 muerta (é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 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 un anterior de teclas inactivas se almacena 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 versión de tecla (por ejemplo, para la entrada de tecla ALT+numpad).

Como ToUnicodeEx traduce el código de clave virtual, también cambia el estado del búfer de teclado en modo kernel. Este cambio de estado afecta a las teclas inactivas, ligaduras, alt+teclado numérico entrada de clave, 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 Valor
cliente mínimo admitido Windows 2000 Professional [solo aplicaciones de escritorio]
servidor mínimo admitido Windows 2000 Server [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

Consulte también

conceptual de

entrada de teclado

LoadKeyboardLayout

de referencia de

ToAsciiEx

VkKeyScan de