Fungsi ToUnicode (winuser.h)

Artikel
03/04/2024

Menerjemahkan kode kunci virtual dan status keyboard yang ditentukan ke karakter atau karakter Unicode yang sesuai.

Sintaks

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

Parameter

[in] wVirtKey

Jenis: UINT

Kode kunci virtual yang akan diterjemahkan. Lihat Kode Kunci Virtual.

[in] wScanCode

Jenis: UINT

Kode pemindaian perangkat keras kunci yang akan diterjemahkan. Bit berurutan tinggi dari nilai ini diatur jika kunci sudah siap.

[in, optional] lpKeyState

Jenis: const BYTE*

Penunjuk ke array 256-byte yang berisi status keyboard saat ini. Setiap elemen (byte) dalam array berisi status satu kunci.

Jika bit byte berurutan tinggi diatur, kuncinya tidak berfungsi. Bit rendah, jika diatur, menunjukkan bahwa kunci diaktifkan. Dalam fungsi ini, hanya bit tombol tombol CAPS LOCK yang relevan. Status pengalih tombol NUM LOCK dan SCROLL LOCK diabaikan. Lihat GetKeyboardState untuk informasi selengkapnya.

[out] pwszBuff

Jenis: LPWSTR

Buffer yang menerima karakter atau karakter yang diterjemahkan sebagai array unit kode UTF-16. Buffer ini dapat dikembalikan tanpa dihentikan null meskipun nama variabel menunjukkan bahwa itu dihentikan null. Anda dapat menggunakan nilai pengembalian metode ini untuk menentukan berapa banyak karakter yang ditulis.

[in] cchBuff

Jenis: int

Ukuran, dalam karakter, dari buffer yang diarahkan oleh parameter pwszBuff .

[in] wFlags

Jenis: UINT

Perilaku fungsi.

Jika bit 0 diatur, menu aktif. Dalam mode ini, kombinasi tombol keypad Alt+Numerik tidak ditangani.

Jika bit 2 diatur, status keyboard tidak diubah (Windows 10, versi 1607 dan yang lebih baru)

Semua bit lainnya (hingga 31) dicadangkan.

Nilai kembali

Jenis: int

Fungsi mengembalikan salah satu nilai berikut.

Mengembalikan nilai	Deskripsi
nilai< 0	Kunci virtual yang ditentukan adalah karakter kunci mati (aksen atau diakritik). Nilai ini dikembalikan terlepas dari tata letak keyboard, bahkan jika beberapa karakter telah ditik dan disimpan dalam status keyboard. Jika memungkinkan, bahkan dengan tata letak keyboard Unicode, fungsi telah menulis versi penspasian dari karakter dead-key ke buffer yang ditentukan oleh pwszBuff. Misalnya, fungsi menulis karakter ACUTE ACCENT (U+00B4), daripada karakter COMBINING ACUTE ACCENT (U+0301).
0	Kunci virtual yang ditentukan tidak memiliki terjemahan untuk status keyboard saat ini. Tidak ada yang ditulis ke buffer yang ditentukan oleh pwszBuff.
nilai > 0	Satu atau beberapa unit kode UTF-16 ditulis ke buffer yang ditentukan oleh pwszBuff. PwszBuff yang dikembalikan mungkin berisi lebih banyak karakter daripada nilai yang ditentukan. Ketika ini terjadi, karakter tambahan apa pun tidak valid dan harus diabaikan.

Keterangan

Untuk menentukan handel ke tata letak keyboard yang akan digunakan untuk menerjemahkan kode yang ditentukan, gunakan fungsi ToUnicodeEx .

Beberapa tata letak keyboard dapat mengembalikan beberapa karakter dan/atau karakter tambahan sebagai pasangan pengganti dalam pwszBuff. Jika karakter tombol mati (aksen atau diakritik) yang disimpan dalam tata letak keyboard tidak dapat dikombinasikan dengan tombol virtual yang ditentukan untuk membentuk satu karakter maka karakter mati yang dimasukkan sebelumnya dapat dikombinasikan dengan karakter saat ini.

Parameter yang disediakan ke fungsi ToUnicodeEx mungkin tidak cukup untuk menerjemahkan kode kunci virtual karena tombol mati sebelumnya disimpan dalam tata letak keyboard.

Biasanya, ToUnicode melakukan terjemahan berdasarkan kode kunci virtual. Namun, dalam beberapa kasus, bit 15 dari parameter wScanCode dapat digunakan untuk membedakan antara penekanan tombol dan rilis kunci (misalnya untuk entri kunci ALT+numpad).

Saat ToUnicode menerjemahkan kode kunci virtual, toUnicode juga mengubah status buffer keyboard mode kernel. Perubahan status ini memengaruhi tombol mati, ligatur, entri kunci keypad Alt+Numerik , dan sebagainya. Ini juga dapat menyebabkan efek samping yang tidak diinginkan jika digunakan bersama dengan TranslateMessage (yang juga mengubah status buffer keyboard mode kernel).

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	winuser.h (sertakan Windows.h)
Pustaka	User32.lib
DLL	User32.dll