Perangkat Keyboard

Android mendukung berbagai perangkat keyboard termasuk keypad fungsi khusus (kontrol volume dan daya), keyboard QWERTY tertanam yang ringkas, dan keyboard eksternal bergaya PC berfitur lengkap.

Dokumen ini hanya menjelaskan keyboard fisik. Lihat Android SDK untuk informasi tentang keyboard lunak (Editor Metode Input).

Klasifikasi Keyboard

Perangkat input diklasifikasikan sebagai keyboard jika salah satu dari kondisi berikut ini berlaku:

• Perangkat input melaporkan keberadaan kode kunci Linux yang digunakan pada keyboard termasuk 0 hingga 0xff atau KEY_OK hingga KEY_MAX .

• Perangkat input melaporkan keberadaan kode kunci Linux yang digunakan pada joystick dan gamepad termasuk BTN_0 hingga BTN_9 , BTN_TRIGGER hingga BTN_DEAD , atau BTN_A hingga BTN_THUMBR .

Joystick saat ini diklasifikasikan sebagai keyboard karena tombol joystick dan gamepad dilaporkan oleh peristiwa EV_KEY dengan cara yang sama seperti tombol keyboard dilaporkan. Jadi joystick dan gamepad juga menggunakan file peta kunci untuk konfigurasi.

Setelah perangkat input diklasifikasikan sebagai keyboard, sistem akan memuat file konfigurasi perangkat input dan tata letak keyboard untuk keyboard.

Sistem kemudian mencoba untuk menentukan karakteristik tambahan dari perangkat.

• Jika perangkat input memiliki tombol apa pun yang dipetakan ke KEYCODE_Q , maka perangkat tersebut dianggap memiliki keypad alfabet (bukan numerik). Kemampuan keypad alfabet dilaporkan dalam objek Configuration sumber daya sebagai KEYBOARD_QWERTY .

• Jika perangkat input memiliki kunci yang dipetakan ke KEYCODE_DPAD_UP , KEYCODE_DPAD_DOWN , KEYCODE_DPAD_LEFT , KEYCODE_DPAD_RIGHT , dan KEYCODE_DPAD_CENTER (semua harus ada), maka perangkat dianggap memiliki tombol arah. Kemampuan papan tombol arah dilaporkan dalam objek Configuration sumber daya sebagai NAVIGATION_DPAD .

• Jika perangkat input memiliki tombol yang dipetakan ke KEYCODE_BUTTON_A atau tombol terkait gamepad lainnya, maka perangkat tersebut dianggap memiliki gamepad.

Persyaratan Pengemudi Keyboard

1. Driver keyboard hanya boleh mendaftarkan kode kunci untuk tombol yang benar-benar mereka dukung. Mendaftarkan kode kunci berlebih dapat membingungkan algoritme klasifikasi perangkat atau menyebabkan sistem salah mendeteksi kemampuan keyboard perangkat yang didukung.

2. Driver keyboard harus menggunakan EV_KEY untuk melaporkan penekanan tombol, menggunakan nilai 0 untuk menunjukkan bahwa tombol dilepaskan, nilai 1 untuk menunjukkan bahwa tombol ditekan, dan nilai lebih besar dari atau sama dengan 2 untuk menunjukkan bahwa tombol tersebut berulang secara otomatis.

3. Android melakukan pengulangan keyboardnya sendiri. Fungsi pengulangan otomatis harus dinonaktifkan pada driver.

4. Driver keyboard secara opsional dapat menunjukkan penggunaan HID atau kode pindaian tingkat rendah dengan mengirimkan EV_MSC dengan MSC_SCANCODE dan nilai yang menunjukkan penggunaan atau kode pindaian saat tombol ditekan. Informasi ini saat ini tidak digunakan oleh Android.

5. Driver keyboard harus mendukung pengaturan status LED saat EV_LED ditulis ke perangkat. Driver hid-input menangani ini secara otomatis. Pada saat penulisan ini, Android menggunakan LED_CAPSLOCK , LED_SCROLLLOCK , dan LED_NUMLOCK . LED ini hanya perlu didukung ketika keyboard benar-benar memiliki lampu indikator terkait.

6. Driver keyboard untuk keypad tertanam (misalnya, menggunakan matriks GPIO) harus memastikan untuk mengirim peristiwa EV_KEY dengan nilai 0 untuk setiap tombol yang masih ditekan saat perangkat akan tidur. Jika tidak, kunci mungkin macet dan akan otomatis berulang selamanya.

Operasi Keyboard

Berikut ini adalah ringkasan singkat tentang pengoperasian keyboard di Android.

1. EventHub membaca kejadian mentah dari driver evdev dan memetakan kode kunci Linux (terkadang disebut sebagai kode pindaian) ke dalam kode kunci Android menggunakan peta tata letak tombol keyboard.

2. InputReader menggunakan kejadian mentah dan memperbarui status kunci meta. Misalnya, jika tombol shift kiri ditekan atau dilepaskan, pembaca akan mengatur atau mereset bit META_SHIFT_LEFT_ON dan META_SHIFT_ON sesuai.

3. InputReader memberi tahu InputDispatcher tentang peristiwa kunci.

4. InputDispatcher menanyakan WindowManagerPolicy apa yang harus dilakukan dengan peristiwa kunci dengan memanggil WindowManagerPolicy.interceptKeyBeforeQueueing . Metode ini merupakan bagian dari jalur kritis yang bertanggung jawab untuk membangunkan perangkat saat tombol tertentu ditekan. EventHub secara efektif menahan penguncian layar saat aktif di sepanjang jalur kritis ini untuk memastikan bahwa itu akan berjalan hingga selesai.

5. Jika InputFilter sedang digunakan, InputDispatcher memberinya kesempatan untuk menggunakan atau mengubah kunci. InputFilter dapat digunakan untuk menerapkan kebijakan aksesibilitas seluruh sistem tingkat rendah.

6. InputDispatcher mengantrekan kunci untuk diproses pada utas pengiriman.

7. Saat InputDispatcher kunci, ini memberi WindowManagerPolicy kesempatan kedua untuk mencegat peristiwa kunci dengan memanggil WindowManagerPolicy.interceptKeyBeforeDispatching . Metode ini menangani pintasan sistem dan fungsi lainnya.

8. InputDispatcher kemudian mengidentifikasi target acara utama (jendela fokus) dan menunggu mereka siap. Kemudian, InputDispatcher mengirimkan acara kunci ke aplikasi.

9. Di dalam aplikasi, peristiwa kunci menyebarkan hierarki tampilan ke tampilan terfokus untuk pengiriman kunci pra-IME.

10. Jika peristiwa kunci tidak ditangani dalam pengiriman pra-IME dan IME sedang digunakan, peristiwa kunci akan dikirimkan ke IME.

11. Jika peristiwa kunci tidak digunakan oleh IME, maka peristiwa utama menyebar ke bawah hierarki tampilan ke tampilan terfokus untuk pengiriman kunci standar.

12. Aplikasi melaporkan kembali ke InputDispatcher apakah peristiwa kunci telah digunakan. Jika acara tidak dikonsumsi, InputDispatcher memanggil WindowManagerPolicy.dispatchUnhandledKey untuk menerapkan perilaku "fallback". Bergantung pada tindakan mundur, siklus pengiriman peristiwa utama dapat dimulai ulang menggunakan kode kunci yang berbeda. Misalnya, jika aplikasi tidak menangani KEYCODE_ESCAPE , sistem dapat mengirim ulang peristiwa kunci sebagai KEYCODE_BACK .

Konfigurasi Keyboard

Perilaku keyboard ditentukan oleh tata letak tombol keyboard, peta karakter tombol, dan konfigurasi perangkat input.

Lihat bagian berikut untuk detail selengkapnya tentang file yang berpartisipasi dalam konfigurasi keyboard:

• File Tata Letak Kunci
• File Peta Karakter Kunci
• File Konfigurasi Perangkat Input

Properti

Properti konfigurasi perangkat input berikut digunakan untuk keyboard.

keyboard.layout

Definisi: keyboard.layout = <nama>

Menentukan nama file tata letak kunci yang terkait dengan perangkat input, tidak termasuk ekstensi .kl . Jika file ini tidak ditemukan, sistem input akan menggunakan tata letak kunci default sebagai gantinya.

Spasi dalam nama diubah menjadi garis bawah selama pencarian.

Lihat dokumentasi file tata letak kunci untuk detail selengkapnya.

keyboard.characterMap

Definisi: keyboard.characterMap = <nama>

Menentukan nama file peta karakter kunci yang terkait dengan perangkat input, tidak termasuk ekstensi .kcm . Jika file ini tidak ditemukan, sistem input akan menggunakan peta karakter kunci default sebagai gantinya.

Spasi dalam nama diubah menjadi garis bawah selama pencarian.

Lihat dokumentasi file peta karakter kunci untuk lebih jelasnya.

keyboard.orientationAware

Definisi: keyboard.orientationAware = 0 | 1

Menentukan apakah keyboard harus bereaksi terhadap perubahan orientasi tampilan.

• Jika nilainya 1 , tombol papan tombol arah akan diputar saat orientasi tampilan terkait berubah.

• Jika nilainya 0 , keyboard kebal terhadap perubahan orientasi tampilan.

Nilai defaultnya adalah 0 .

Orientation awareness digunakan untuk mendukung rotasi tombol directional keypad, seperti pada Motorola Droid. Misalnya, ketika perangkat diputar searah jarum jam 90 derajat dari orientasi alaminya, KEYCODE_DPAD_UP dipetakan ulang untuk menghasilkan KEYCODE_DPAD_RIGHT karena tombol 'atas' berakhir menunjuk 'kanan' saat perangkat dipegang dalam orientasi tersebut.

keyboard.builtIn

Definisi: keyboard.builtIn = 0 | 1

Menentukan apakah keyboard adalah keyboard bawaan (terpasang secara fisik).

Nilai defaultnya adalah 1 jika nama perangkat diakhiri dengan -keypad , 0 jika tidak.

Keyboard internal selalu diberi id perangkat 0 . Papan ketik lain yang tidak terpasang diberi id perangkat unik bukan nol.

Menggunakan id 0 untuk keyboard internal penting untuk menjaga kompatibilitas dengan bidang KeyCharacterMap.BUILT_IN_KEYBOARD , yang menentukan id keyboard internal dan memiliki nilai 0 . Bidang ini tidak digunakan lagi di API tetapi aplikasi lama mungkin masih menggunakannya.

Keyboard fungsi khusus (keyboard yang peta karakter kuncinya menentukan tipe SPECIAL_FUNCTION ) tidak akan pernah didaftarkan sebagai keyboard bawaan, terlepas dari pengaturan properti ini. Ini karena keyboard fungsi khusus menurut definisi tidak dimaksudkan untuk digunakan untuk pengetikan tujuan umum.

Contoh Konfigurasi

# This is an example input device configuration file for a built-in
# keyboard that has a DPad.

# The keyboard is internal because it is part of the device.
device.internal = 1

# The keyboard is the default built-in keyboard so it should be assigned
# an id of 0.
keyboard.builtIn = 1

# The keyboard includes a DPad which is mounted on the device.  As the device
# is rotated the orientation of the DPad rotates along with it, so the DPad must
# be aware of the display orientation.  This ensures that pressing 'up' on the
# DPad always means 'up' from the perspective of the user, even when the entire
# device has been rotated.
keyboard.orientationAware = 1

Catatan Kompatibilitas

Sebelum Honeycomb, input mapper keyboard tidak menggunakan properti konfigurasi apa pun. Semua keyboard diasumsikan terpasang secara fisik dan sadar orientasi. Tata letak kunci default dan peta karakter kunci diberi nama qwerty bukan Generic . Format peta karakter kunci juga sangat berbeda dan kerangka tidak mendukung keyboard penuh gaya PC atau keyboard eksternal.

Saat memutakhirkan perangkat ke Honeycomb, pastikan untuk membuat atau memperbarui konfigurasi yang diperlukan dan file peta kunci.

Penggunaan HID, Kode Kunci Linux dan Kode Kunci Android

Sistem mengacu pada kunci menggunakan beberapa pengidentifikasi berbeda, tergantung pada lapisan abstraksi.

Untuk perangkat HID, setiap kunci memiliki penggunaan HID terkait. Driver hid-input Linux dan vendor terkait serta driver HID khusus perangkat bertanggung jawab untuk menguraikan laporan HID dan memetakan penggunaan HID ke kode kunci Linux.

Saat Android membaca peristiwa EV_KEY dari kernel Linux, ia menerjemahkan setiap kode kunci Linux ke dalam kode kunci Android yang sesuai sesuai dengan file tata letak kunci perangkat.

Saat kejadian kunci dikirim ke aplikasi, instance android.view.KeyEvent melaporkan kode kunci Linux sebagai nilai getScanCode() dan kode kunci Android sebagai nilai getKeyCode() . Untuk tujuan kerangka kerja, hanya nilai getKeyCode() yang penting.

Perhatikan bahwa informasi penggunaan HID tidak digunakan oleh Android itu sendiri atau diteruskan ke aplikasi.

Tabel Kode

Tabel berikut menunjukkan bagaimana penggunaan HID, kode kunci Linux, dan kode kunci Android terkait satu sama lain.

Kolom LKC menentukan kode kunci Linux dalam heksadesimal.

Kolom AKC menentukan kode kunci Android dalam heksadesimal.

Kolom Catatan mengacu pada catatan yang diposting setelah tabel.

Kolom Versi menentukan versi pertama platform Android yang menyertakan kunci ini dalam peta kunci defaultnya. Beberapa baris ditampilkan dalam kasus di mana peta kunci default telah berubah di antara versi. Versi tertua yang ditunjukkan adalah 1.6.

• Di Gingerbread (2.3) dan rilis sebelumnya, peta kunci default adalah qwerty.kl . Peta kunci ini hanya dimaksudkan untuk digunakan dengan Android Emulator dan tidak dimaksudkan untuk digunakan untuk mendukung keyboard eksternal arbitrer. Namun demikian, beberapa OEM menambahkan dukungan keyboard Bluetooth ke platform dan mengandalkan qwerty.kl untuk menyediakan pemetaan keyboard yang diperlukan. Akibatnya pemetaan yang lebih tua ini mungkin menarik bagi OEM yang sedang membangun periferal untuk perangkat khusus ini. Perhatikan bahwa pemetaan secara substansial berbeda dari yang saat ini, terutama sehubungan dengan perlakuan kunci HOME . Disarankan agar semua periferal baru dikembangkan sesuai dengan Honeycomb atau peta kunci yang lebih baru (mis. HID standar).

• Pada Honeycomb (3.0), peta kunci default adalah Generic.kl . Peta kunci ini dirancang untuk mendukung keyboard gaya PC lengkap. Sebagian besar fungsionalitas keyboard HID standar seharusnya berfungsi dengan baik.

Pemetaan kode kunci dapat bervariasi di seluruh versi kernel Linux dan Android. Ketika perubahan diketahui telah terjadi di peta kunci default Android, perubahan tersebut ditunjukkan di kolom versi.

Driver HID khusus perangkat dan peta kunci mungkin menerapkan pemetaan yang berbeda dari yang ditunjukkan di sini.

Halaman Keyboard dan Keypad HID (0x07)

Halaman Desktop Umum HID (0x01)

Halaman Konsumen HID (0x0c)

Additional non-HID Mappings

These mappings describe functions that do not appear in HID but for which Linux key codes exist.

Legacy Unsupported Keys

These mappings appeared in previous versions of Android but were inconsistent with HID or used non-standard Linux key codes. They are no longer supported.

Catatan

1. The Android key code associated with common alphanumeric and symbolic keys may vary based on the keyboard layout and language. For historical reasons, the physical scan codes and HID usages associated with keys on a keyboard are often defined positionally even though the labels printed on those keys may vary from one language to another.

   On a US English (QWERTY) keyboard, the top-left alphabetic key is labeled Q. On a French (AZERTY) keyboard, the key in the same position is labeled A. Despite the label, on both keyboards the top-left alphabetic key is referred to using the HID usage 0x07 0x0014 which is mapped to the Linux key code KEY_Q.

   When Android is configured with a US English keyboard layout, then the Linux key code KEY_Q will be mapped to the Android key code KEYCODE_Q and will produce the characters 'Q' and 'q'. However, when Android is configured with a French keyboard layout, then the Linux key code KEY_Q will be mapped to the Android key code KEYCODE_A and will produce the characters 'A' and 'a'.

   The Android key code typically reflects the language-specific interpretation of the key, so a different Android key code may be used for different languages.

2. 0x0c 0x022f AC Zoom is defined in the HID as a linear control but the kernel maps it as a key, which is probably incorrect.

3. The Linux function keys KEY_FN_* are mapped to simpler key codes but are dispatched with the META_FUNCTION meta state bit set to true.

4. Prior to Android Ice Cream Sandwich 4.0, the default key layout contained mappings for some extra key codes that were not defined in the mainline Linux kernel headers. These mappings have since been removed because these previously undefined key codes have since been assigned different meanings in more recent versions of the Linux kernel.

Sources

1. USB HID Usage Tables v1.12
2. Linux 2.6.39 kernel: include/linux/input.h, drivers/hid/hid-input.c
3. Android ICS: qwerty.kl, Generic.kl, KeyEvent.java