Funzione ToUnicode (winuser.h)

Articolo
08/28/2023

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

Sintassi

int ToUnicode(
  [in]           UINT       wVirtKey,
  [in]           UINT       wScanCode,
  [in, optional] const BYTE *lpKeyState,
  [out]          LPWSTR     pwszBuff,
  [in]           int        cchBuff,
  [in]           UINT       wFlags
);

Parametri

[in] wVirtKey

Tipo: UINT

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

[in] wScanCode

Tipo: UINT

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

[in, optional] lpKeyState

Tipo: const BYTE*

Puntatore a una matrice a 256 byte che contiene lo stato della tastiera corrente. 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. In questa funzione è rilevante solo l'interruttore del tasto CAPS LOCK. Lo stato di disattivazione delle chiavi NUM LOCK e SCROLL LOCK viene ignorato. Per altre informazioni, vedere 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 terminare null anche se il nome della variabile suggerisce che è terminato null. È possibile usare il valore restituito di questo metodo per determinare il numero di caratteri scritti.

[in] cchBuff

Tipo: int

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

[in] wFlags

Tipo: UINT

Comportamento della funzione.

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

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

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

Valore restituito

Tipo: int

La funzione restituisce uno dei valori seguenti.

Valore restituito	Descrizione
valore< 0	La chiave virtuale specificata è un carattere chiave non valido (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 dead-key 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	La chiave virtuale specificata non ha alcuna traduzione per lo stato corrente della tastiera. Niente è 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 al valore restituito specificato. In questo caso, eventuali caratteri aggiuntivi non sono validi e devono essere ignorati.

Commenti

Per specificare un handle per il layout della tastiera da usare per tradurre il codice specificato, usare la funzione ToUnicodeEx .

Alcuni layout della tastiera possono restituire diversi caratteri e/o caratteri supplementari come coppie surrogate in pwszBuff. Se non è stato possibile combinare un carattere chiave non valido (accento o diacritico) archiviato nel layout della tastiera con la chiave virtuale specificata per formare un singolo carattere, il carattere precedente immesso può essere combinato con il carattere corrente.

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

In genere, ToUnicode esegue la traduzione 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 ALT+numpad key entry).

Come ToUnicode converte il codice della chiave virtuale, cambia anche lo stato del buffer della tastiera in modalità kernel. Questa modifica dello stato influisce sui tasti non recapitabili, le legature, la voce di tasti alt+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