Compartilhar via

Função ToUnicodeEx (winuser.h)

  • Artigo

Converte o código de chave 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 Virtual-Key Codes.

[in] wScanCode

Tipo: UINT

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

[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á inoperante. O bit baixo, se definido, indica que a chave está ativada. Nessa função, somente o bit de alternância da chave 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, alt+numeric keypad combinações de teclas 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 criação 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.

Valor de retorno

Tipo: int

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

Valor de retorno Descrição
valor < 0
A chave virtual especificada é uma chave morta caractere (acento ou diacrítico). Esse valor é retornado independentemente do layout do teclado, mesmo que vários caracteres tenham sido digitado e armazenados no estado do teclado. Se possível, mesmo com layouts de teclado Unicode, a função escreveu uma versão de espaçamento do caractere de chave morta no buffer especificado por pwszBuff. Por exemplo, a função grava o caractere ÊNFASE AGUDA (U+00B4), em vez do caractere COMBINING ACUTE ACCENT (U+0301).
0
 A chave 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. Retornado pwszBuff 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.

Observações

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.

Alguns layouts de teclado podem retornar vários caracteres e/ou caracteres complementares como pares alternativos em pwszBuff. Se o caractere de chave morta (ênfase ou diacrítico) armazenado no layout do teclado não puder ser combinado com a chave 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 chave virtual porque uma chave 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 e uma versão de tecla (por exemplo, alt+entrada de tecla numpad).

À medida que ToUnicodeEx converte o código de chave virtual, ele também altera o estado do buffer de teclado do modo kernel. Essa alteração de estado afeta chaves mortas, ligaturas, alt+teclado numérico entrada de chave 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
de cliente com suporte mínimo Windows 2000 Professional [somente aplicativos da área de trabalho]
servidor com suporte mínimo Windows 2000 Server [somente aplicativos da área de trabalho]
da Plataforma de Destino Windows
cabeçalho winuser.h (inclua Windows.h)
biblioteca User32.lib
de DLL User32.dll

Consulte também

Conceitual

de entrada do teclado

LoadKeyboardLayout

de referência de

ToAsciiEx

VkKeyScan