ToUnicodeEx-Funktion (winuser.h)

Artikel
03/04/2024

Übersetzt den angegebenen virtuellen Tastencode und den Tastaturzustand in die entsprechenden Unicode-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 Code des virtuellen Schlüssels. Weitere Informationen finden Sie unter Virtuelle Tastencodes.

[in] wScanCode

Typ: UINT

Der Hardwarescancode des zu übersetzenden Schlüssels. Das Bit mit hoher Reihenfolge dieses Werts wird festgelegt, wenn der Schlüssel aktiv 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 Zustand eines Schlüssels.

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

[out] pwszBuff

Typ: LPWSTR

Der Puffer, der das übersetzte Zeichen oder die übersetzten Zeichen als Array von UTF-16-Codeeinheiten empfängt. Dieser Puffer kann zurückgegeben werden, ohne null-terminiert zu sein, obwohl der Variablenname darauf hindeutet, 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 parameter pwszBuff verweist.

[in] wFlags

Typ: UINT

Das Verhalten der Funktion.

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

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

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 unzustellbares Schlüsselzeichen (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, hat die Funktion auch bei Unicode-Tastaturlayouts einen Abstand des Unzustellbaren Zeichens in den von pwszBuff angegebenen Puffer geschrieben. Beispielsweise schreibt die Funktion das Zeichen ACUTE ACCENT (U+00B4) und nicht das Zeichen COMBINING ACUTE ACCENT (U+0301).
0	Die angegebene virtuelle Taste verfügt über keine Übersetzung für den aktuellen Zustand der Tastatur. Es wurde nichts in den von pwszBuff angegebenen Puffer geschrieben.
Wert > 0	Mindestens eine UTF-16-Codeeinheit wurde in den von pwszBuff angegebenen Puffer geschrieben. Zurückgegebenes pwszBuff kann mehr Zeichen enthalten, als der Rückgabewert angibt. In diesem Fall sind alle zusätzlichen Zeichen ungültig und sollten ignoriert werden.

Hinweise

Der Eingabegebietsschemabezeichner ist ein umfassenderes Konzept als ein Tastaturlayout, da er auch einen Spracherkennungskonverter, eine Eingabemethode Editor (IME) oder jede andere Form der Eingabe umfassen kann.

Einige Tastaturlayouts geben möglicherweise mehrere Zeichen und/oder ergänzende Zeichen als Ersatzpaare in pwszBuff zurück. Wenn das im Tastaturlayout gespeicherte Unzustellbare Taste (Akzent oder diakritische Zeichen) nicht mit der angegebenen virtuellen Taste kombiniert werden konnte, um ein einzelnes Zeichen zu bilden, kann das zuvor eingegebene unzustellbare 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 Schlüssel zu übersetzen, da eine vorherige unzustellbare Taste im Tastaturlayout gespeichert ist.

In der Regel führt ToUnicodeEx die Übersetzung basierend auf dem Code des virtuellen Schlüssels durch. In einigen Fällen kann jedoch Bit 15 des wScanCode-Parameters verwendet werden, um zwischen einem Tastendruck und einem Tastenauslöser zu unterscheiden (z. B. für ALT+Numpad-Tasteneingabe).

Da ToUnicodeEx den Code für virtuelle Schlüssel übersetzt, ändert es auch den Zustand des Tastaturpuffers im Kernelmodus. Diese Zustandsänderung wirkt sich auf tote Tasten, Ligaturen, ALT+Numerische Tastaturtasteneingabe usw. aus. Es kann auch unerwünschte Nebenwirkungen verursachen, wenn es in Verbindung mit TranslateMessage verwendet wird (was auch den Zustand des Kernelmodus-Tastaturpuffers ändert).

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winuser.h (windows.h einschließen)
Bibliothek	User32.lib
DLL	User32.dll