Función ToAsciiEx (winuser.h)

Artículo
07/21/2023

Traduce el código de tecla virtual y el estado de teclado especificados al carácter o caracteres correspondientes. La función traduce el código usando el idioma de entrada y la distribución física del teclado identificado por el identificador de la configuración regional de entrada.

Nota:

Es posible que este método no funcione correctamente con algunos diseños de teclado que pueden producir varios caracteres (es decir, ligaduras) o caracteres Unicode adicionales en una sola pulsación de tecla. Se recomienda encarecidamente usar los métodos ToUnicode o ToUnicodeEx que controlan estos casos correctamente.

Sintaxis

int ToAsciiEx(
  [in]           UINT       uVirtKey,
  [in]           UINT       uScanCode,
  [in, optional] const BYTE *lpKeyState,
  [out]          LPWORD     lpChar,
  [in]           UINT       uFlags,
  [in, optional] HKL        dwhkl
);

Parámetros

[in] uVirtKey

Tipo: UINT

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

[in] uScanCode

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 tecla está arriba (no se presiona).

[in, optional] 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 tecla está presionada (presionada).

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 LOCK CAPS. Se omite el estado de alternancia de las teclas NUM LOCK y SCOLL LOCK.

[out] lpChar

Tipo: LPWORD

Puntero al búfer que recibe el carácter traducido (o dos caracteres empaquetados en un solo valor WORD , donde el byte de orden bajo contiene el primer carácter y el byte de orden superior contiene el segundo carácter).

[in] uFlags

Tipo: UINT

Este parámetro debe ser 1 si un menú está activo; de lo contrario, cero.

[in, optional] dwhkl

Tipo: HKL

Identificador de configuración regional de entrada que se va a usar para traducir el código. Este parámetro puede ser cualquier identificador de configuración regional de entrada devuelto anteriormente por la función LoadKeyboardLayout .

Valor devuelto

Tipo: int

El valor devuelto es uno de los siguientes valores.

Valor devuelto	Descripción
0	La tecla virtual especificada no tiene traducción para el estado actual del teclado.
1	Se copió un carácter en el búfer.
2	Se copiaron dos caracteres en el búfer. Esto suele ocurrir cuando un carácter de tecla inactiva (énfasis o diacrítico) almacenado en el diseño del teclado no se puede componer con la tecla virtual especificada para formar un solo carácter.

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.

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

Normalmente, ToAsciiEx realiza la traducción en función del código de clave virtual. Sin embargo, en algunos casos, se puede usar el bit 15 del parámetro uScanCode para distinguir entre una tecla presionada y una liberación de tecla. El código de examen se usa para traducir combinaciones de teclas ALT+número.

Aunque NUM LOCK es una tecla de alternancia que afecta al comportamiento del teclado, ToAsciiEx omite la configuración de alternancia (el bit bajo) de lpKeyState (VK_NUMLOCK) porque el parámetro uVirtKey solo es suficiente para distinguir las teclas de movimiento del cursor (VK_HOME, VK_INSERT, etc.) de las teclas numéricas (VK_DECIMAL, VK_NUMPAD0 VK_NUMPAD9 - ).

Requisitos


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 (incluir Windows.h)
Library	User32.lib
Archivo DLL	User32.dll