Fungsi ToAsciiEx (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 pengidentifikasi lokal input.

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 ToAsciiEx(
  [in]           UINT       uVirtKey,
  [in]           UINT       uScanCode,
  [in, optional] const BYTE *lpKeyState,
  [out]          LPWORD     lpChar,
  [in]           UINT       uFlags,
  [in, optional] HKL        dwhkl
);

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 SCOLL 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, nol jika tidak.

[in, optional] dwhkl

Jenis: HKL

Masukkan pengidentifikasi lokal untuk digunakan untuk menerjemahkan kode. Parameter ini dapat menjadi pengidentifikasi lokal input yang sebelumnya dikembalikan oleh fungsi LoadKeyboardLayout .

Menampilkan 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

Pengidentifikasi lokal input adalah konsep yang lebih luas daripada tata letak keyboard, karena juga dapat mencakup pengonversi ucapan ke teks, Editor Metode Input (IME), atau bentuk input lainnya.

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

Biasanya, ToAsciiEx 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 ALT+number.

Meskipun NUM LOCK adalah tombol pengalih yang memengaruhi perilaku keyboard, ToAsciiEx 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