Função ToAsciiEx (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 a linguagem de entrada e o layout de teclado físico identificados pela identificação de localidade de entrada.

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 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

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 chaves NUM LOCK e SCOLL 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, caso contrário, zero.

[in, optional] dwhkl

Tipo: HKL

Identificador de localidade de entrada a ser usado para traduzir o código. Esse parâmetro pode ser qualquer identificador de localidade de entrada retornado anteriormente pela função LoadKeyboardLayout .

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

O identificador de localidade de entrada é um conceito mais amplo do que um layout de teclado, pois também pode abranger um conversor de fala em texto, um IME (Editor de Método de Entrada) ou qualquer outra forma de entrada.

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

Normalmente, ToAsciiEx 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 ALT+number.

Embora NUM LOCK seja uma tecla de alternância que afeta o comportamento do teclado, ToAsciiEx 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