ToUnicodeEx-Funktion (winuser.h)

Artikel
07/16/2024

Übersetzt den angegebenen Code und den Tastaturzustand der virtuellen Taste in das entsprechende Unicode-Zeichen oder Zeichen.

Syntax

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

Parameter

[in] wVirtKey

Typ: UINT-

Der zu übersetzende virtuelle Schlüsselcode. Siehe Virtual-Key Codes.

[in] wScanCode

Typ: UINT-

Der Hardware-Scancode des zu übersetzenden Schlüssels. Das Bit mit hoher Reihenfolge dieses Werts wird festgelegt, wenn der Schlüssel hoch ist.

[in] lpKeyState

Typ: const BYTE*

Ein Zeiger auf ein 256-Byte-Array, das den aktuellen Tastaturzustand enthält. Jedes Element (Byte) im Array enthält den Status eines Schlüssels.

Wenn das Bit mit hoher Reihenfolge eines Bytes festgelegt ist, ist der Schlüssel unten. Wenn festgelegt, gibt das niedrige Bit an, dass der Schlüssel aktiviert ist. In dieser Funktion ist nur das Umschaltbit der FESTSTELLTASTE relevant. Der Umschaltzustand der TASTEN NUM und SCROLL-TASTE wird ignoriert. Weitere Informationen finden Sie unter GetKeyboardState-.

[out] pwszBuff

Typ: LPWSTR-

Der Puffer, der das übersetzte Zeichen oder Zeichen als Array von UTF-16-Codeeinheiten empfängt. Dieser Puffer kann zurückgegeben werden, ohne null beendet zu werden, obwohl der Variablenname vermuten lässt, dass er null-terminated ist. Sie können den Rückgabewert dieser Methode verwenden, um zu bestimmen, wie viele Zeichen geschrieben wurden.

[in] cchBuff

Typ: int

Die Größe des Puffers in Zeichen, auf den der pwszBuff Parameter verweist.

[in] wFlags

Typ: UINT-

Das Verhalten der Funktion.

Wenn Bit 0 festgelegt ist, ist ein Menü aktiv. In diesem Modus werden ALT+Zehnertastatur Tastenkombinationen nicht behandelt.

Wenn Bit 1 festgelegt ist, übersetzt ToUnicodeEx- Scancodes, die als Schlüsselunterbrechungsereignisse gekennzeichnet sind, zusätzlich zur üblichen Behandlung von Key Make-Ereignissen.

Wenn Bit 2 festgelegt ist, wird der Tastaturzustand nicht geändert (Windows 10, Version 1607 und höher)

Alle anderen Bits (bis 31) sind reserviert.

[in, optional] dwhkl

Typ: HKL-

Der Eingabegebietsschemabezeichner, der zum Übersetzen des angegebenen Codes verwendet wird. Dieser Parameter kann ein beliebiger Eingabegebietsschemabezeichner sein, der zuvor von der LoadKeyboardLayout-Funktion zurückgegeben wurde.

Rückgabewert

Typ: int

Die Funktion gibt einen der folgenden Werte zurück.

Rückgabewert	Beschreibung
Wert < 0	Der angegebene virtuelle Schlüssel ist ein inaktiven Schlüssel Zeichen (Akzent oder diakritische Zeichen). Dieser Wert wird unabhängig vom Tastaturlayout zurückgegeben, auch wenn mehrere Zeichen eingegeben wurden und im Tastaturzustand gespeichert sind. Wenn möglich, auch mit Unicode-Tastaturlayouts, hat die Funktion eine Abstandsversion des Inaktivtastenzeichens in den puffer geschrieben, der durch pwszBuffangegeben wird. Die Funktion schreibt z. B. das Zeichen ACUTE ACCENT (U+00B4) anstelle des Zeichens AKUTEN AKZENT (U+0301).
0	Die angegebene virtuelle Taste hat keine Übersetzung für den aktuellen Zustand der Tastatur. Es wurde nichts in den durch pwszBuffangegebenen Puffer geschrieben.
Wert > 0	Mindestens eine UTF-16-Codeeinheit wurde in den durch pwszBuffangegebenen Puffer geschrieben. Gibt pwszBuff- möglicherweise mehr Zeichen als der Rückgabewert angibt. In diesem Fall sind alle zusätzlichen Zeichen ungültig und sollten ignoriert werden.

Bemerkungen

Der Eingabegebietsschemabezeichner ist ein breiteres Konzept als ein Tastaturlayout, da es auch einen Sprach-zu-Text-Konverter, einen Eingabemethoden-Editor (INPUT Method Editor, IME) oder eine andere Art von Eingabe umfassen kann.

Einige Tastaturlayouts geben möglicherweise mehrere Zeichen und/oder Zusatzzeichen als Ersatzpaare zurück, die in pwszBuff-. Wenn das im Tastaturlayout gespeicherte Inaktive Taste (Akzent oder diakritische Zeichen) nicht mit der angegebenen virtuellen Taste kombiniert werden konnte, um ein einzelnes Zeichen zu bilden, kann das vorherige eingegebene inaktive Zeichen mit dem aktuellen Zeichen kombiniert werden.

Die parameter, die für die ToUnicodeEx--Funktion bereitgestellt werden, reichen möglicherweise nicht aus, um den Code für virtuelle Tasten zu übersetzen, da eine vorherige inaktiven Taste im Tastaturlayout gespeichert ist.

In der Regel führt ToUnicodeEx die Übersetzung basierend auf dem virtuellen Schlüsselcode aus. In einigen Fällen kann jedoch Bit 15 des wScanCode--Parameters verwendet werden, um zwischen einem Tastendruck und einer Tastenfreigabe zu unterscheiden (z. B. bei ALT+Numpad-Tasteneingabe).

Da ToUnicodeEx den virtuellen Schlüsselcode übersetzt, ändert er auch den Zustand des Kernelmodus-Tastaturpuffers. Diese Zustandsänderung wirkt sich auf tote Tasten, Ligaturen ALT+Zehnertastatur Tasteneingabe usw. aus. Es kann auch unerwünschte Nebenwirkungen verursachen, wenn sie in Verbindung mit TranslateMessage- verwendet werden (wodurch auch der Zustand des Kernelmodus-Tastaturpuffers geändert wird).

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows 2000 Professional [nur Desktop-Apps]
mindestens unterstützte Server-	Windows 2000 Server [nur Desktop-Apps]
Zielplattform-	Fenster
Header-	winuser.h (enthalten Windows.h)
Library	User32.lib
DLL-	User32.dll