Funzione ToUnicodeEx (winuser.h)

Articolo
07/16/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 Virtual-Key.

[in] wScanCode

Tipo: UINT

L'hardware analizzare il codice della chiave da convertire. Il bit di ordine elevato di questo valore viene impostato se la chiave è impostata su.

[in] lpKeyState

Tipo: BYTE* const

Puntatore a una matrice a 256 byte che contiene lo stato corrente della tastiera. Ogni elemento (byte) nella matrice contiene lo stato di una chiave.

Se il bit di ordine elevato di un byte è impostato, 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 NUM LOCK e SCROLL LOCK 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, un menu è attivo. In questa modalità le combinazioni di tasti alt+numerico tasti 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 generazione delle chiavi.

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 usato 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 chiave non morta carattere (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 COMBINANDO ACCENTO ACUTO (U+0301).
0	Il tasto virtuale specificato non ha alcuna traslazione 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. Restituito pwszBuff può contenere più caratteri rispetto al valore restituito specificato. In questo caso, eventuali caratteri aggiuntivi non sono validi e devono essere ignorati.

Osservazioni

L'identificatore delle impostazioni locali di input è un concetto più ampio rispetto a un layout di tastiera, poiché può includere anche un convertitore di riconoscimento vocale, un IME (Input Method Editor) 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 attivo (accento o diacritico) memorizzato nel layout della tastiera con il tasto virtuale specificato per formare un singolo carattere, il carattere non attivo immesso 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é un precedente tasto non recapitabile viene archiviato nel layout della tastiera.

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

Come ToUnicodeEx converte il codice della chiave virtuale, cambia anche lo stato del buffer della tastiera in modalità kernel. Questa modifica dello stato influisce su tasti non recapitabili, legature, alt+tastierino numerico voce di tasto e così via. Potrebbe anche causare effetti collaterali indesiderati se usati in combinazione con TranslateMessage (che modifica anche lo stato del buffer della tastiera in modalità kernel).

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 2000 Professional [solo app desktop]
server minimo supportato	Windows 2000 Server [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	winuser.h (include Windows.h)
libreria	User32.lib
dll	User32.dll