Funzione ToAsciiEx (winuser.h)

Articolo
07/21/2023

Converte il codice del tasto virtuale e lo stato della tastiera specificati nel carattere o nei caratteri corrispondenti. La funzione converte il codice usando la lingua di input e il layout della tastiera fisica identificati dall'identificatore delle impostazioni locali di input.

Nota

Questo metodo potrebbe non funzionare correttamente con alcuni layout di tastiera che possono produrre più caratteri (ad esempio legature) e/o caratteri Unicode supplementari su un singolo tasto. È consigliabile usare i metodi ToUnicode o ToUnicodeEx che gestiscono correttamente tali casi.

Sintassi

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

Parametri

[in] uVirtKey

Tipo: UINT

Codice della chiave virtuale da convertire. Vedere Codici di chiave virtuale.

[in] uScanCode

Tipo: UINT

Codice di analisi hardware della chiave da convertire. Il bit di ordine elevato di questo valore viene impostato se il tasto è su (non premuto).

[in, optional] lpKeyState

Tipo: const BYTE*

Puntatore a una matrice di 256 byte che contiene lo stato corrente della tastiera. Ogni elemento (byte) nella matrice contiene lo stato di una chiave. Se viene impostato il bit di ordine elevato di un byte, il tasto è inattivo (premuto).

Il bit basso, se impostato, indica che la chiave è attivata o disattivata. In questa funzione è rilevante solo il bit di attivazione/disattivazione del tasto BLOC MAIUSC. Lo stato di attivazione/disattivazione delle chiavi NUM LOCK e SCOLL LOCK viene ignorato.

[out] lpChar

Tipo: LPWORD

Puntatore al buffer che riceve il carattere tradotto (o due caratteri compressi in un singolo valore WORD , in cui il byte di ordine basso contiene il primo carattere e il byte di ordine elevato contiene il secondo carattere).

[in] uFlags

Tipo: UINT

Questo parametro deve essere 1 se un menu è attivo, zero in caso contrario.

[in, optional] dwhkl

Tipo: HKL

Identificatore delle impostazioni locali di input da usare per tradurre il codice. Questo parametro può essere qualsiasi identificatore delle impostazioni locali di input restituito in precedenza dalla funzione LoadKeyboardLayout .

Valore restituito

Tipo: int

Il valore restituito è uno dei valori seguenti.

Valore restituito	Descrizione
0	Il tasto virtuale specificato non ha una traduzione per lo stato corrente della tastiera.
1	Un carattere è stato copiato nel buffer.
2	Due caratteri sono stati copiati nel buffer. Ciò si verifica in genere quando un carattere di tasto non recapitabile (accento o diacritico) archiviato nel layout della tastiera non può essere composto con il tasto virtuale specificato per formare un singolo carattere.

Commenti

L'identificatore delle impostazioni locali di input è un concetto più ampio rispetto a un layout della tastiera, poiché può includere anche un convertitore di riconoscimento vocale, un IME (Input Method Editor) o qualsiasi altra forma di input.

I parametri forniti alla funzione ToAsciiEx potrebbero non essere sufficienti per convertire il codice della chiave virtuale, perché nel layout della tastiera viene archiviato un tasto non recapitabile precedente.

In genere, ToAsciiEx esegue la traduzione in base al codice della chiave virtuale. In alcuni casi, tuttavia, è possibile usare il bit 15 del parametro uScanCode per distinguere tra una pressione del tasto e una versione del tasto. Il codice di analisi viene usato per la conversione di combinazioni di tasti ALT+numero.

Anche se NUM LOCK è un tasto di attivazione/disattivazione che influisce sul comportamento della tastiera, ToAsciiEx ignora l'impostazione dell'interruttore (bit basso) di lpKeyState (VK_NUMLOCK) perché il parametro uVirtKey da solo è sufficiente per distinguere i tasti di spostamento del cursore (VK_HOME, VK_INSERT e così via) dai tasti numerici (VK_DECIMAL, VK_NUMPAD0 VK_NUMPAD9 - ).

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winuser.h (include Windows.h)
Libreria	User32.lib
DLL	User32.dll