ToAsciiEx-Funktion (winuser.h)

Artikel
07/21/2023

Übersetzt den angegebenen virtuellen Tastencode und den Tastaturzustand in die entsprechenden Zeichen. Die Funktion übersetzt den Code mithilfe der Eingabesprache und des physischen Tastaturlayouts, das durch den Eingabe-Gebietsschemabezeichner identifiziert wird.

Hinweis

Diese Methode funktioniert möglicherweise nicht ordnungsgemäß mit einigen Tastaturlayouts , die bei nur einem Tastendruck mehrere Zeichen (z. B. Ligaturen) und/oder zusätzliche Unicode-Zeichen erzeugen. Es wird dringend empfohlen, die Methoden ToUnicode oder ToUnicodeEx zu verwenden, die solche Fälle ordnungsgemäß behandeln.

Syntax

int ToAsciiEx(
  [in]           UINT       uVirtKey,
  [in]           UINT       uScanCode,
  [in, optional] const BYTE *lpKeyState,
  [out]          LPWORD     lpChar,
  [in]           UINT       uFlags,
  [in, optional] HKL        dwhkl
);

Parameter

[in] uVirtKey

Typ: UINT

Der zu übersetzende Code des virtuellen Schlüssels. Weitere Informationen finden Sie unter Virtuelle Tastencodes.

[in] uScanCode

Typ: UINT

Der Hardwarescancode des zu übersetzenden Schlüssels. Das Hochreihenfolgenbit dieses Werts wird festgelegt, wenn die Taste aktiv ist (nicht gedrückt).

[in, optional] 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 die Taste nach unten (gedrückt).

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 LOCK und SCOLL LOCK wird ignoriert.

[out] lpChar

Typ: LPWORD

Ein Zeiger auf den Puffer, der das übersetzte Zeichen empfängt (oder zwei Zeichen, die in einen einzelnen WORD-Wert gepackt sind, wobei das Byte mit niedriger Ordnung das erste Zeichen und das Byte mit hoher Ordnung das zweite Zeichen enthält).

[in] uFlags

Typ: UINT

Dieser Parameter muss 1 sein, wenn ein Menü aktiv ist, andernfalls null.

[in, optional] dwhkl

Typ: HKL

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

Rückgabewert

Typ: int

Der Rückgabewert ist einer der folgenden Werte.

Rückgabewert	BESCHREIBUNG
0	Die angegebene virtuelle Taste verfügt über keine Übersetzung für den aktuellen Zustand der Tastatur.
1	Ein Zeichen wurde in den Puffer kopiert.
2	Zwei Zeichen wurden in den Puffer kopiert. Dies geschieht in der Regel, wenn ein im Tastaturlayout gespeichertes Unzustellbares Zeichen (Akzent oder diakritische Zeichen) nicht mit der angegebenen virtuellen Taste zu einem einzelnen Zeichen zusammengesetzt werden kann.

Bemerkungen

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

Die Parameter, die für die ToAsciiEx-Funktion bereitgestellt werden, reichen möglicherweise nicht aus, um den Code für virtuelle Schlüssel zu übersetzen, da im Tastaturlayout eine vorherige unzustellbare Taste gespeichert ist.

In der Regel führt ToAsciiEx die Übersetzung basierend auf dem Code des virtuellen Schlüssels durch. In einigen Fällen kann jedoch Bit 15 des uScanCode-Parameters verwendet werden, um zwischen einem Tastendruck und einer Tastenfreigabe zu unterscheiden. Der Scancode wird für die Übersetzung von Tastenkombinationen von ALT+Zahlen verwendet.

Obwohl NUM LOCK eine Umschalttaste ist, die sich auf das Tastaturverhalten auswirkt, ignoriert ToAsciiEx die Umschalteinstellung (das niedrige Bit) von lpKeyState (VK_NUMLOCK), da der uVirtKey-Parameter allein ausreicht, um die Cursorbewegungstasten (VK_HOME, VK_INSERT usw.) von den numerischen Tasten (VK_DECIMAL, VK_NUMPAD0 - VK_NUMPAD9) zu unterscheiden.

Anforderungen


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