GetKeyNameTextA-Funktion (winuser.h)

Artikel
06/27/2024

Ruft eine Zeichenfolge ab, die den Namen eines Schlüssels darstellt.

Syntax

int GetKeyNameTextA(
  [in]  LONG  lParam,
  [out] LPSTR lpString,
  [in]  int   cchSize
);

Parameter

[in] lParam

Typ: LONG

Der zweite Parameter der zu verarbeitenden Tastaturmeldung (z. B. WM_KEYDOWN). Die Funktion interpretiert die folgenden Bitpositionen in der lParam.

Bits	Bedeutung
16-23	Der Scancode. Der Wert hängt vom OEM ab.
24	Gibt an, ob die Taste eine erweiterte Taste ist, z. B. die rechte ALT- und STRG-TASTE, die auf einer erweiterten 101- oder 102-Tastentastaturen angezeigt werden. Der Wert ist 1, wenn es sich um einen erweiterten Schlüssel handelt. andernfalls ist es 0.
25	"Keine Sorge" Bit. Die Anwendung, die diese Funktion aufruft, legt dieses Bit fest, um anzugeben, dass die Funktion z. B. nicht zwischen LINKS- und RECHTS-STRG- und UMSCHALTTASTEn unterscheiden soll.

Weitere Informationen finden Sie unter Tastaturbefehlskennzeichnungen.

[out] lpString

Typ: LPTSTR-

Der Puffer, der den Schlüsselnamen erhält.

[in] cchSize

Typ: int

Die maximale Länge des Schlüsselnamens in Zeichen, einschließlich des endenden NULL-Zeichens. (Dieser Parameter sollte der Größe des Puffers entsprechen, auf den der lpString-Parameter verweist.)

Rückgabewert

Typ: int

Wenn die Funktion erfolgreich ist, wird eine mit Null beendete Zeichenfolge in den angegebenen Puffer kopiert, und der Rückgabewert ist die Länge der Zeichenfolge in Zeichen, ohne das endende NULL-Zeichen zu zählen.

Wenn die Funktion fehlschlägt, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

Das Format der Tastennamenzeichenfolge hängt vom aktuellen Tastaturlayout ab.

Das Tastaturlayout verwaltet eine Liste von Namen in Form von Zeichenzeichenfolgen für Tasten mit Namen, die länger als ein einzelnes Zeichen sind. Der Schlüsselname wird entsprechend dem derzeit aktiven Tastaturlayoutübersetzt. Daher gibt die Funktion möglicherweise unterschiedliche Ergebnisse für unterschiedliche Tastaturlayoutszurück.

Der Name eines Zeichenschlüssels ist das Zeichen selbst. Die Namen von inaktiven Schlüsseln werden vollständig geschrieben.

Zeichentasten, die dem "A" zugeordnet sind. Z' virtuelle Schlüsselcodes werden in den <U+0041 LATEINISCHER GROßBUCHSTABE A>übersetzt.<U+005A LATIN CAPITAL LETTER Z> Zeichen unabhängig vom aktuellen Tastaturlayout. Verwenden Sie in diesem Fall die methoden ToUnicode oder ToUnicodeEx, um das Zeichen für das entsprechende Drücken der Taste abzurufen.

Diese Methode funktioniert möglicherweise nicht ordnungsgemäß mit einigen Tastaturlayouts, die mehrere Zeichen (z. B. Ligaturen) oder ergänzende Unicode-Zeichen auf einer einzelnen Taste erzeugen.

Der winuser.h-Header definiert GetKeyNameText als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

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