Fonction ToUnicodeEx (winuser.h)

Article
03/04/2024

Traduit le code de touche virtuelle et l’état du clavier spécifiés en caractères Unicode correspondants.

Syntaxe

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

Paramètres

[in] wVirtKey

Type : UINT

Code de clé virtuelle à traduire. Consultez Codes de touche virtuelle.

[in] wScanCode

Type : UINT

Code d’analyse matérielle de la clé à traduire. Le bit d’ordre élevé de cette valeur est défini si la clé est en place.

[in] lpKeyState

Type : const BYTE*

Pointeur vers un tableau de 256 octets qui contient l’état actuel du clavier. Chaque élément (octet) du tableau contient l’état d’une clé.

Si le bit d’ordre élevé d’un octet est défini, la clé est arrêtée. Le bit faible, s’il est défini, indique que la clé est activée. Dans cette fonction, seul le bit bascule de la clé CAPS LOCK est pertinent. L’état bascule des touches NUM LOCK et SCROLL LOCK est ignoré. Pour plus d’informations, consultez GetKeyboardState .

[out] pwszBuff

Type : LPWSTR

Mémoire tampon qui reçoit le ou les caractères traduits en tant que tableau d’unités de code UTF-16. Cette mémoire tampon peut être retournée sans fin null, même si le nom de la variable suggère qu’elle est terminée par null. Vous pouvez utiliser la valeur de retour de cette méthode pour déterminer le nombre de caractères écrits.

[in] cchBuff

Type : int

Taille, en caractères, de la mémoire tampon vers laquelle pointe le paramètre pwszBuff .

[in] wFlags

Type : UINT

Comportement de la fonction.

Si le bit 0 est défini, un menu est actif. Dans ce mode, les combinaisons de touches Alt+Pavé numérique ne sont pas gérées.

Si bit 1 est défini, ToUnicodeEx traduit les scancodes marqués comme événements de saut de clé en plus de son traitement habituel des événements de création de clé.

Si le bit 2 est défini, l’état du clavier n’est pas modifié (Windows 10, version 1607 et ultérieure)

Tous les autres bits (jusqu’à 31) sont réservés.

[in, optional] dwhkl

Type : HKL

Identificateur de paramètres régionaux d’entrée utilisé pour traduire le code spécifié. Ce paramètre peut être n’importe quel identificateur de paramètres régionaux d’entrée précédemment retourné par la fonction LoadKeyboardLayout .

Valeur retournée

Type : int

La fonction retourne l’une des valeurs suivantes.

Valeur retournée	Description
valeur< 0	La clé virtuelle spécifiée est un caractère de clé morte (accentuation ou diacritique). Cette valeur est retournée quelle que soit la disposition du clavier, même si plusieurs caractères ont été tapés et sont stockés dans l’état du clavier. Si possible, même avec des dispositions de clavier Unicode, la fonction a écrit une version d’espacement du caractère de touche morte dans la mémoire tampon spécifiée par pwszBuff. Par exemple, la fonction écrit le caractère ACCENT AIGU (U+00B4), plutôt que le caractère COMBINING AIGU ACCENT (U+0301).
0	La touche virtuelle spécifiée n’a pas de traduction pour l’état actuel du clavier. Rien n’a été écrit dans la mémoire tampon spécifiée par pwszBuff.
valeur > 0	Une ou plusieurs unités de code UTF-16 ont été écrites dans la mémoire tampon spécifiée par pwszBuff. PwszBuff retourné peut contenir plus de caractères que la valeur de retour spécifiée. Dans ce cas, tous les caractères supplémentaires ne sont pas valides et doivent être ignorés.

Remarques

L’identificateur de paramètres régionaux d’entrée est un concept plus large qu’une disposition de clavier, car il peut également englober un convertisseur de reconnaissance vocale, un Rédacteur de méthode d’entrée (IME) ou toute autre forme d’entrée.

Certaines dispositions de clavier peuvent renvoyer plusieurs caractères et/ou caractères supplémentaires en tant que paires de substitution dans pwszBuff. Si le caractère de touche mort (accentuation ou diacritique) stocké dans la disposition du clavier n’a pas pu être combiné avec la touche virtuelle spécifiée pour former un caractère unique, le caractère mort entré précédemment peut être combiné avec le caractère actuel.

Les paramètres fournis à la fonction ToUnicodeEx peuvent ne pas être suffisants pour traduire le code de la clé virtuelle, car une clé morte précédente est stockée dans la disposition du clavier.

En règle générale, ToUnicodeEx effectue la traduction en fonction du code de clé virtuelle. Dans certains cas, toutefois, le bit 15 du paramètre wScanCode peut être utilisé pour faire la distinction entre une pression sur la touche et une libération de touche (par exemple pour l’entrée de touche ALT+numpad).

À mesure que ToUnicodeEx traduit le code de clé virtuelle, il modifie également l’état de la mémoire tampon du clavier en mode noyau. Ce changement d’état affecte les touches mortes, les ligatures, l’entrée de touche Alt+Numeric keypad , etc. Il peut également provoquer des effets secondaires indésirables s’il est utilisé conjointement avec TranslateMessage (qui change également l’état de la mémoire tampon du clavier en mode noyau).

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winuser.h (inclure Windows.h)
Bibliothèque	User32.lib
DLL	User32.dll