Função ToUnicode (winuser.h)

Artigo
03/04/2024

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

Sintaxe

int ToUnicode(
  [in]           UINT       wVirtKey,
  [in]           UINT       wScanCode,
  [in, optional] const BYTE *lpKeyState,
  [out]          LPWSTR     pwszBuff,
  [in]           int        cchBuff,
  [in]           UINT       wFlags
);

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

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

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

Alguns layouts de teclado podem retornar vários caracteres e/ou caracteres suplementares como pares alternativos em pwszBuff. Se um caractere de tecla inativo (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, o ToUnicode 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 o ToUnicode 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