Función ToAscii (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 distribución de teclado.

Para especificar un identificador de la distribución del teclado que se va a usar para traducir el código especificado, use la función ToAsciiEx.

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 ToAscii(
  [in]           UINT       uVirtKey,
  [in]           UINT       uScanCode,
  [in, optional] const BYTE *lpKeyState,
  [out]          LPWORD     lpChar,
  [in]           UINT       uFlags
);

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 SCROLL 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 o 0 de lo contrario.

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

Es posible que los parámetros proporcionados a la función ToAscii 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, ToAscii 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 de número ALT+.

Aunque NUM LOCK es una tecla de alternancia que afecta al comportamiento del teclado, ToAscii 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