File tata letak kunci

File tata letak kunci (file .kl ) memetakan kode kunci dan kode sumbu Linux ke kode kunci dan kode sumbu Android serta menentukan tanda kebijakan terkait. File tata letak kunci khusus perangkat adalah:

  • Diperlukan untuk perangkat input internal (bawaan) yang dilengkapi tombol, termasuk tombol khusus seperti tombol volume, daya, dan media headset.
  • Opsional untuk perangkat input lain tetapi direkomendasikan untuk keyboard dan joystick tujuan khusus.

Jika tidak ada file tata letak kunci khusus perangkat yang tersedia, sistem akan memilih default.

Lokasi

File tata letak kunci ditempatkan berdasarkan vendor USB, id produk (dan versi opsional), atau berdasarkan nama perangkat input. Jalur berikut dikonsultasikan secara berurutan:

  • /odm/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl
  • /vendor/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl
  • /system/usr/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl
  • /data/system/devices/keylayout/Vendor_XXXX_Product_XXXX_Version_XXXX.kl
  • /odm/usr/keylayout/Vendor_XXXX_Product_XXXX.kl
  • /vendor/usr/keylayout/Vendor_XXXX_Product_XXXX.kl
  • /system/usr/keylayout/Vendor_XXXX_Product_XXXX.kl
  • /data/system/devices/keylayout/Vendor_XXXX_Product_XXXX.kl
  • /odm/usr/keylayout/DEVICE_NAME.kl
  • /vendor/usr/keylayout/DEVICE_NAME.kl
  • /system/usr/keylayout/DEVICE_NAME.kl
  • /data/system/devices/keylayout/DEVICE_NAME.kl
  • /odm/usr/keylayout/Generic.kl
  • /vendor/usr/keylayout/Generic.kl
  • /system/usr/keylayout/Generic.kl
  • /data/system/devices/keylayout/Generic.kl

Saat membuat jalur file yang berisi nama perangkat, semua karakter dalam nama perangkat selain '0'-'9', 'a'-'z', 'A'-'Z', '-' atau '_' digantikan oleh '_'.

File tata letak kunci generik

Sistem menyediakan file tata letak kunci generik bawaan khusus yang disebut Generic.kl . Tata letak tombol ini dimaksudkan untuk mendukung berbagai keyboard dan joystick eksternal standar. Jangan mengubah tata letak kunci umum!

Sintaksis

File tata letak kunci adalah file teks biasa yang terdiri dari deklarasi dan flag kunci atau sumbu.

Deklarasi kunci

Deklarasi kunci terdiri dari kata kunci key diikuti dengan nomor kode kunci Linux dan nama kode kunci Android, atau penggunaan kata kunci diikuti dengan penggunaan HID dan nama kode kunci Android. Penggunaan HID direpresentasikan sebagai bilangan bulat 32-bit, dengan 16-bit tinggi mewakili halaman penggunaan HID dan 16-bit rendah mewakili ID penggunaan HID. Deklarasi mana pun dapat diikuti dengan serangkaian tanda kebijakan opsional yang dibatasi spasi.

key 1     ESCAPE
key 114   VOLUME_DOWN
key 16    Q                 VIRTUAL
key usage 0x0c006F          BRIGHTNESS_UP

Tanda-tanda kebijakan berikut ini dikenali:

  • FUNCTION : Tombol tersebut harus diartikan seolah-olah tombol FUNCTION juga ditekan.
  • GESTURE : Kunci yang dihasilkan oleh gerakan pengguna, seperti menggerakkan layar sentuh.
  • VIRTUAL : Tombolnya adalah soft key virtual (tombol kapasitif) yang berdekatan dengan layar sentuh utama. Hal ini menyebabkan logika debouncing khusus diaktifkan (lihat di bawah).

Deklarasi sumbu

Deklarasi sumbu masing-masing terdiri dari kata kunci axis diikuti dengan nomor kode sumbu Linux dan qualifier yang mengontrol perilaku sumbu termasuk setidaknya satu nama kode sumbu Android.

Sumbu dasar

Sumbu dasar hanya memetakan kode sumbu Linux ke nama kode sumbu Android. Deklarasi berikut memetakan ABS_X (ditunjukkan dengan 0x00 ) ke AXIS_X (ditunjukkan dengan X ).

axis 0x00 X

Pada contoh di atas, jika nilai ABS_X adalah 5 maka AXIS_X disetel ke 5 .

Pisahkan sumbu

Sumbu terpisah memetakan kode sumbu Linux ke dua nama kode sumbu Android, sehingga nilai yang kurang dari atau lebih besar dari ambang batas akan dibagi menjadi dua sumbu berbeda saat dipetakan. Pemetaan ini berguna ketika satu sumbu fisik yang dilaporkan oleh perangkat mengkodekan dua sumbu logis berbeda yang saling eksklusif.

Deklarasi berikut memetakan nilai sumbu ABS_Y (ditunjukkan dengan 0x01 ) ke AXIS_GAS bila kurang dari 0x7f atau ke AXIS_BRAKE bila lebih besar dari 0x7f .

axis 0x01 split 0x7f GAS BRAKE

Pada contoh di atas, jika nilai ABS_Y adalah 0x7d maka AXIS_GAS disetel ke 2 ( 0x7f - 0x7d ) dan AXIS_BRAKE disetel ke 0 . Sebaliknya jika nilai ABS_Y adalah 0x83 maka AXIS_GAS disetel ke 0 dan AXIS_BRAKE disetel ke 4 ( 0x83 - 0x7f ). Terakhir, jika nilai ABS_Y sama dengan nilai pemisahan 0x7f maka AXIS_GAS dan AXIS_BRAKE disetel ke 0 .

Sumbu terbalik

Sumbu terbalik membalikkan tanda nilai sumbu. Deklarasi berikut memetakan ABS_RZ (ditunjukkan dengan 0x05 ) ke AXIS_BRAKE (ditunjukkan dengan BRAKE ), dan membalikkan keluaran dengan meniadakannya.

axis 0x05 invert BRAKE

Pada contoh di atas, jika nilai ABS_RZ adalah 2 maka AXIS_BRAKE disetel ke -2 .

Opsi rata tengah

Perangkat joystick dapat melaporkan kejadian input meskipun joystick tidak digunakan karena adanya kebisingan. Kebisingan ini biasanya berasal dari tongkat kiri dan/atau kanan, dan menyebabkan pengemudi melaporkan nilai posisi mendekati 0. Nilai "center flat" menentukan jumlah kebisingan yang diharapkan dari pengontrol saat diam.

Protokol input Linux menyediakan cara bagi driver perangkat input untuk menentukan nilai rata tengah sumbu joystick, namun tidak semua driver melaporkannya dan beberapa di antaranya memberikan nilai yang salah. Untuk mengatasi masalah ini, deklarasi sumbu dapat diikuti dengan opsi flat yang menentukan lebar wilayah di sekitar posisi tengah sumbu yang dianggap terpusat.

Misalnya, jika driver perangkat melaporkan nilai AXIS_X antara 0 dan 100, maka 0 akan dipetakan ke -1 dan 100 akan dipetakan ke 1 oleh sistem input Android. Pusat jangkauannya adalah 50 pada koordinat tak berskala dan 0 pada koordinat berskala. Jika nilai tetap sama dengan 10, maka pengembang harus berasumsi bahwa setiap nilai AXIS_X yang dilaporkan antara -0,1 dan 0,1 (antara 40 dan 60 dalam koordinat yang tidak berskala) adalah noise, dan memperlakukan nilai yang berasal dari joystick sebagai nol.

Catatan : Meskipun file tata letak kunci menentukan nilai untuk ruang koordinat driver, nilai yang dilaporkan oleh android.view.InputDevice.MotionRange#getFlat() berada dalam ruang koordinat Android.

axis 0x03 Z flat 4096

Dalam contoh di atas, nilai rata tengah diatur ke 4096 .

Komentar

Baris komentar dimulai dengan # dan berlanjut hingga akhir baris:

# A comment!

Baris kosong diabaikan.

Contoh

Papan ketik

# This is an example of a key layout file for a keyboard.

key 1     ESCAPE
key 2     1
key 3     2
key 4     3
key 5     4
key 6     5
key 7     6
key 8     7
key 9     8
key 10    9
key 11    0
key 12    MINUS
key 13    EQUALS
key 14    DEL

# etc...

Kontrol sistem

# This is an example of a key layout file for basic system controls,
# such as volume and power keys which are typically implemented as GPIO pins
# the device decodes into key presses.

key 114   VOLUME_DOWN
key 115   VOLUME_UP
key 116   POWER

Tombol kapasitif

# This is an example of a key layout file for a touch device with capacitive buttons.

key 139    MENU           VIRTUAL
key 172    HOME           VIRTUAL
key 158    BACK           VIRTUAL
key 217    SEARCH         VIRTUAL

Kontrol media jack headset

# This is an example of a key layout file for headset mounted media controls.
# A typical headset jack interface might have special control wires or detect known
# resistive loads as corresponding to media functions or volume controls.
# This file assumes that the driver decodes these signals and reports media
# controls as key presses.

key 163   MEDIA_NEXT
key 165   MEDIA_PREVIOUS
key 226   HEADSETHOOK

tuas kendali

# This is an example of a key layout file for a joystick.

# These are the buttons that the joystick supports, represented as keys.
key 304   BUTTON_A
key 305   BUTTON_B
key 307   BUTTON_X
key 308   BUTTON_Y
key 310   BUTTON_L1
key 311   BUTTON_R1
key 314   BUTTON_SELECT
key 315   BUTTON_START
key 316   BUTTON_MODE
key 317   BUTTON_THUMBL
key 318   BUTTON_THUMBR

# Left and right stick.
# The reported value for flat is 128 in a range of -32767 to 32768, which is absurd.
# This confuses applications that rely on the flat value because the joystick
# actually settles in a flat range of +/- 4096 or so. We override it here.
axis 0x00 X flat 4096
axis 0x01 Y flat 4096
axis 0x03 Z flat 4096
axis 0x04 RZ flat 4096

# Triggers.
axis 0x02 LTRIGGER
axis 0x05 RTRIGGER

# Hat.
axis 0x10 HAT_X
axis 0x11 HAT_Y

Tombol lunak virtual

Sistem masukan menyediakan fitur khusus untuk mengimplementasikan tombol lunak virtual dalam kasus penggunaan berikut:

  1. Jika tombol lunak virtual ditampilkan secara grafis di layar (seperti pada Galaxy Nexus), tombol tersebut diimplementasikan oleh komponen Bilah Navigasi dalam paket UI Sistem. Karena tombol lunak virtual grafis diimplementasikan pada lapisan tinggi dalam sistem, file tata letak kunci tidak terlibat dan informasi berikut tidak berlaku.
  2. Jika tombol lunak virtual diterapkan sebagai wilayah sentuh yang diperluas yang merupakan bagian dari layar sentuh utama (seperti pada Nexus One), sistem masukan menggunakan file peta kunci virtual untuk menerjemahkan koordinat sentuh X/Y ke dalam kode kunci Linux, kemudian menggunakan file tata letak kunci untuk menerjemahkan kode kunci Linux menjadi kode kunci Android (untuk detail tentang file peta kunci virtual, lihat Perangkat sentuh ). File tata letak kunci untuk perangkat input layar sentuh harus menentukan pemetaan kunci yang sesuai dan menyertakan tanda VIRTUAL untuk setiap tombol.
  3. Jika tombol lunak virtual diimplementasikan sebagai tombol kapasitif yang terpisah dari layar sentuh utama (seperti pada Nexus S), driver perangkat atau firmware kernel bertanggung jawab untuk menerjemahkan sentuhan ke dalam kode kunci Linux yang kemudian diterjemahkan oleh sistem input menjadi kode kunci Android. menggunakan file tata letak kunci. File tata letak kunci untuk perangkat input tombol kapasitif harus menentukan pemetaan kunci yang sesuai dan menyertakan tanda VIRTUAL untuk setiap kunci.

Bila tombol lunak virtual terletak di dalam atau dekat secara fisik dengan layar sentuh, pengguna akan mudah menekan tombol secara tidak sengaja saat menyentuh di dekat bagian bawah layar atau saat menggeser jari dari atas ke bawah atau dari bawah ke bawah. teratas di layar. Untuk mencegah hal ini, sistem input menerapkan sedikit debouncing sehingga penekanan tombol lunak virtual diabaikan selama jangka waktu singkat setelah sentuhan terakhir pada layar sentuh (penundaan ini disebut waktu tenang tombol virtual ).

Untuk mengaktifkan debouncing tombol lunak virtual:

  1. Menyediakan file tata letak kunci untuk layar sentuh atau perangkat input tombol kapasitif dengan tanda VIRTUAL yang disetel untuk setiap tombol.
    key 139    MENU           VIRTUAL
key 172    HOME           VIRTUAL
key 158    BACK           VIRTUAL
key 217    SEARCH         VIRTUAL
  2. Tetapkan nilai waktu tenang kunci virtual dalam hamparan sumber daya untuk sumber daya kerangka config.xml .
    <!-- Specifies the amount of time to disable virtual keys after the screen
is touched to filter out accidental virtual key presses due to swiping gestures
or taps near the edge of the display. May be 0 to disable the feature.
It is recommended that this value be no more than 250 ms.
This feature should be disabled for most devices. -->

<integer name="config_virtualKeyQuietTimeMillis">250</integer>

Validasi

Anda harus memvalidasi file tata letak kunci Anda menggunakan alat Validasi Peta Kunci .