Função ToUnicodeEx (winuser.h)

Artigo
04/14/2023

Converte o código de tecla virtual especificado e o estado do teclado para o caractere unicode ou caracteres correspondentes.

Sintaxe

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

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

[in] wScanCode

Tipo: UINT

O código de verificação de hardware da chave a ser traduzida. O bit de alta ordem desse valor será definido se a chave estiver em alta.

[in] 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 alta ordem de um byte estiver definido, a chave estará inativa. 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. Consulte GetKeyboardState para obter mais informações.

[out] pwszBuff

Tipo: LPWSTR

O buffer que recebe o caractere traduzido ou caracteres como matriz de unidades de código UTF-16. Esse buffer pode ser retornado sem ser encerrado em nulo, embora o nome da variável sugira que ele seja encerrado em nulo. Você pode usar o valor retornado desse método para determinar quantos caracteres foram gravados.

[in] cchBuff

Tipo: int

O tamanho, em caracteres, do buffer apontado pelo parâmetro pwszBuff .

[in] wFlags

Tipo: UINT

O comportamento da função.

Se o bit 0 estiver definido, um menu estará ativo. Nesse modo, as combinações de teclas alt+numéricas do teclado não são tratadas.

Se o bit 1 estiver definido, ToUnicodeEx traduzirá os códigos de verificação marcados como eventos de interrupção de chave, além de seu tratamento habitual de eventos de marca de chave.

Se o bit 2 estiver definido, o estado do teclado não será alterado (Windows 10, versão 1607 e mais recente)

Todos os outros bits (até 31) são reservados.

[in, optional] dwhkl

Tipo: HKL

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

Retornar valor

Tipo: int

A função retorna um dos valores a seguir.

Valor retornado	Descrição
valor< 0	A chave virtual especificada é um caractere chave morto (acento ou diacrítico). Esse valor é retornado independentemente do layout do teclado, mesmo que vários caracteres tenham sido digitado e estejam armazenados no estado do teclado. Se possível, mesmo com layouts de teclado Unicode, a função gravou uma versão de espaçamento do caractere de tecla morta no buffer especificado por pwszBuff. Por exemplo, a função grava o caractere ÊNFASE AGUDA (U+00B4), em vez do caractere COMBINANDO ÊNFASE AGUDA (U+0301).
0	A tecla virtual especificada não tem tradução para o estado atual do teclado. Nada foi gravado no buffer especificado por pwszBuff.
valor > 0	Uma ou mais unidades de código UTF-16 foram gravadas no buffer especificado por pwszBuff. PwszBuff retornado pode conter mais caracteres do que o valor retornado especifica. Quando isso acontece, todos os caracteres extras são inválidos e devem ser ignorados.

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 método de entrada Editor (IME) ou qualquer outra forma de entrada.

Alguns layouts de teclado podem retornar vários caracteres e/ou caracteres suplementares como pares alternativos em pwszBuff. Se o caractere de tecla morta (acento ou diacrítico) armazenado no layout do teclado não puder ser combinado com a tecla virtual especificada para formar um único caractere, o caractere morto inserido anteriormente poderá ser combinado com o caractere atual.

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

Normalmente, ToUnicodeEx executa a tradução com base no código de chave virtual. Em alguns casos, no entanto, o bit 15 do parâmetro wScanCode pode ser usado para distinguir entre uma tecla press e uma liberação de tecla (por exemplo, para entrada de tecla ALT+numpad).

À medida que ToUnicodeEx converte o código de tecla virtual, ele também altera o estado do buffer de teclado no modo kernel. Essa alteração de estado afeta teclas mortas, ligaturas, entrada de tecla do teclado Alt+Numérico e assim por diante. Também pode causar efeitos colaterais indesejados se usado em conjunto com TranslateMessage (que também altera o estado do buffer de teclado no modo kernel).

Requisitos

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