Função ToAscii (winuser.h)

Artigo
07/21/2023

Converte o código de tecla virtual e o estado do teclado especificados para o caractere ou caracteres correspondentes. A função converte o código usando o idioma de entrada e o layout de teclado físico identificados pelo identificador de layout do teclado.

Para especificar um identificador para o layout do teclado a ser usado para traduzir o código especificado, use a função ToAsciiEx.

Observação

Esse método pode não funcionar corretamente com alguns layouts de teclado que podem produzir vários caracteres (ou seja, ligaturas) e/ou caracteres Unicode suplementares em uma única tecla. É altamente recomendável usar os métodos ToUnicode ou ToUnicodeEx que manipulam esses casos corretamente.

Sintaxe

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

O código de chave virtual a ser traduzido. Consulte Códigos de tecla virtual.

[in] uScanCode

Tipo: UINT

O código de verificação de hardware da chave a ser convertida. O bit de alta ordem desse valor será definido se a tecla estiver pressionada (não pressionada).

[in, optional] lpKeyState

Tipo: const BYTE*

Um ponteiro para uma matriz de 256 bytes que contém o estado atual do teclado. Cada elemento (byte) na matriz contém o estado de uma chave. Se o bit de ordem alta de um byte estiver definido, a tecla será pressionada (pressionada).

O bit baixo, se definido, indica que a chave está ativada. Nessa função, somente o bit de alternância da tecla CAPS LOCK é relevante. O estado de alternância das teclas NUM LOCK e SCROLL LOCK é ignorado.

[out] lpChar

Tipo: LPWORD

Um ponteiro para o buffer que recebe o caractere traduzido (ou dois caracteres empacotados em um único valor WORD , em que o byte de baixa ordem contém o primeiro caractere e o byte de alta ordem contém o segundo caractere).

[in] uFlags

Tipo: UINT

Esse parâmetro deve ser 1 se um menu estiver ativo ou 0 caso contrário.

Valor retornado

Tipo: int

O valor retornado é um dos valores a seguir.

Valor retornado	Descrição
0	A tecla virtual especificada não tem tradução para o estado atual do teclado.
1	Um caractere foi copiado para o buffer.
2	Dois caracteres foram copiados para o buffer. Isso geralmente acontece quando um caractere de tecla morta (ênfase ou diacrítico) armazenado no layout do teclado não pode ser composto com a tecla virtual especificada para formar um único caractere.

Comentários

Os parâmetros fornecidos para a função ToAscii podem não ser suficientes para traduzir o código de tecla virtual, pois uma tecla morta anterior é armazenada no layout do teclado.

Normalmente, o ToAscii executa a tradução com base no código de chave virtual. Em alguns casos, no entanto, o bit 15 do parâmetro uScanCode pode ser usado para distinguir entre uma tecla press e uma versão de tecla. O código de verificação é usado para traduzir combinações de teclas numéricas ALT+.

Embora NUM LOCK seja uma tecla de alternância que afeta o comportamento do teclado, ToAscii ignora a configuração de alternância (o bit baixo) de lpKeyState (VK_NUMLOCK) porque o parâmetro uVirtKey sozinho é suficiente para distinguir as teclas de movimento do cursor (VK_HOME, VK_INSERT e assim por diante) das teclas numéricas (VK_DECIMAL, VK_NUMPAD0 - VK_NUMPAD9).

Requisitos


Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	winuser.h (inclua Windows.h)
Biblioteca	User32.lib
DLL	User32.dll