Funzione ToUnicodeEx (winuser.h)

Articolo
03/13/2024

Converte il codice di tasto virtuale e lo stato della tastiera specificati nel carattere o nei caratteri Unicode corrispondenti.

Sintassi

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

Parametri

[in] wVirtKey

Tipo: UINT

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

[in] wScanCode

Tipo: UINT

Codice di analisi hardware della chiave da convertire. Il bit di ordine elevato di questo valore viene impostato se la chiave è impostata.

[in] 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, la chiave è inattiva. 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 dei tasti BLOC NUM e BLOC SCORRIMENTO viene ignorato. Per altre informazioni, vedi GetKeyboardState .

[out] pwszBuff

Tipo: LPWSTR

Buffer che riceve il carattere o i caratteri tradotti come matrice di unità di codice UTF-16. Questo buffer può essere restituito senza terminazione Null anche se il nome della variabile suggerisce che è con terminazione Null. È possibile utilizzare il valore restituito di questo metodo per determinare il numero di caratteri scritti.

[in] cchBuff

Tipo: int

Dimensione, in caratteri, del buffer a cui punta il parametro pwszBuff .

[in] wFlags

Tipo: UINT

Comportamento della funzione.

Se è impostato il bit 0, è attivo un menu. In questa modalità le combinazioni di tasti alt+tastierino numerico non vengono gestite.

Se è impostato il bit 1, ToUnicodeEx tradurrà i codici di analisi contrassegnati come eventi di interruzione chiave oltre al trattamento consueto di eventi di key make events.

Se è impostato il bit 2, lo stato della tastiera non viene modificato (Windows 10, versione 1607 e successive)

Tutti gli altri bit (da a 31) sono riservati.

[in, optional] dwhkl

Tipo: HKL

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

Valore restituito

Tipo: int

La funzione restituisce uno dei valori seguenti.

Valore restituito	Descrizione
valore< 0	La chiave virtuale specificata è un carattere di chiave non recapitata (accento o diacritico). Questo valore viene restituito indipendentemente dal layout della tastiera, anche se sono stati digitati diversi caratteri e vengono archiviati nello stato della tastiera. Se possibile, anche con layout di tastiera Unicode, la funzione ha scritto una versione di spaziatura del carattere di tasti non recapitabili nel buffer specificato da pwszBuff. Ad esempio, la funzione scrive il carattere ACCENTO ACUTO (U+00B4), anziché il carattere COMBINAZIONE ACCENTO ACUTO (U+0301).
0	Il tasto virtuale specificato non ha una traduzione per lo stato corrente della tastiera. Nulla è stato scritto nel buffer specificato da pwszBuff.
valore > 0	Una o più unità di codice UTF-16 sono state scritte nel buffer specificato da pwszBuff. PwszBuff restituito può contenere più caratteri rispetto agli identificatori del valore restituito. In questo caso, eventuali caratteri aggiuntivi non sono validi e devono essere ignorati.

Commenti

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

Alcuni layout di tastiera possono restituire diversi caratteri e/o caratteri supplementari come coppie di surrogati in pwszBuff. Se non è stato possibile combinare il carattere di tasto non recapitabile (accento o diacritico) memorizzato nel layout della tastiera con il tasto virtuale specificato per formare un singolo carattere, il carattere non recapitabile precedente può essere combinato con il carattere corrente.

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

In genere, ToUnicodeEx esegue la conversione in base al codice della chiave virtuale. In alcuni casi, tuttavia, è possibile usare bit 15 del parametro wScanCode per distinguere tra una pressione del tasto e una versione del tasto (ad esempio, per la voce del tasto ALT+numpad).

Poiché ToUnicodeEx converte il codice virtual-key, modifica anche lo stato del buffer della tastiera in modalità kernel. Questa modifica dello stato influisce su tasti non recapitabili, legature, alt+tasto tastierino numerico e così via. Può anche causare effetti collaterali indesiderati se usato in combinazione con TranslateMessage (che modifica anche lo stato del buffer della tastiera in modalità kernel).

Requisiti

Requisito	Valore
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