Fungsi ToAscii (winuser.h)

Artikel
07/21/2023

Menerjemahkan kode kunci virtual dan status keyboard yang ditentukan ke karakter atau karakter yang sesuai. Fungsi ini menerjemahkan kode menggunakan bahasa input dan tata letak keyboard fisik yang diidentifikasi oleh handel tata letak keyboard.

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

Catatan

Metode ini mungkin tidak berfungsi dengan baik dengan beberapa tata letak keyboard yang dapat menghasilkan beberapa karakter (yaitu ligatur) dan/atau karakter Unicode tambahan pada satu penekanan tombol. Sangat disarankan untuk menggunakan metode ToUnicode atau ToUnicodeEx yang menangani kasus tersebut dengan benar.

Sintaks

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

Parameter

[in] uVirtKey

Jenis: UINT

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

[in] uScanCode

Jenis: UINT

Kode pemindaian perangkat keras kunci yang akan diterjemahkan. Bit berurutan tinggi dari nilai ini diatur jika tombol naik (tidak ditekan).

[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, tombol tidak berfungsi (ditekan).

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.

[out] lpChar

Jenis: LPWORD

Penunjuk ke buffer yang menerima karakter yang diterjemahkan (atau dua karakter yang dikemas ke dalam satu nilai WORD , di mana byte urutan rendah berisi karakter pertama dan byte urutan tinggi berisi karakter kedua).

[in] uFlags

Jenis: UINT

Parameter ini harus 1 jika menu aktif, atau 0 jika tidak.

Mengembalikan nilai

Jenis: int

Nilai yang dikembalikan adalah salah satu nilai berikut.

Mengembalikan nilai	Deskripsi
0	Kunci virtual yang ditentukan tidak memiliki terjemahan untuk status keyboard saat ini.
1	Satu karakter disalin ke buffer.
2	Dua karakter disalin ke buffer. Ini biasanya terjadi ketika karakter tombol mati (aksen atau diakritik) yang disimpan dalam tata letak keyboard tidak dapat disusun dengan kunci virtual yang ditentukan untuk membentuk satu karakter.

Keterangan

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

Biasanya, ToAscii melakukan terjemahan berdasarkan kode kunci virtual. Namun, dalam beberapa kasus, bit 15 dari parameter uScanCode dapat digunakan untuk membedakan antara penekanan tombol dan rilis kunci. Kode pemindaian digunakan untuk menerjemahkan kombinasi tombol angka ALT+.

Meskipun NUM LOCK adalah tombol pengalih yang memengaruhi perilaku keyboard, ToAscii mengabaikan pengaturan pengalih (bit rendah) lpKeyState (VK_NUMLOCK) karena parameter uVirtKey saja cukup untuk membedakan tombol gerakan kursor (VK_HOME, VK_INSERT, dan sebagainya) dari tombol numerik (VK_DECIMAL, VK_NUMPAD0 - VK_NUMPAD9).

Persyaratan


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