Mulai 27 Maret 2025, sebaiknya gunakan android-latest-release, bukan aosp-main, untuk mem-build dan berkontribusi pada AOSP. Untuk mengetahui informasi selengkapnya, lihat Perubahan pada AOSP.

Halaman ini diterjemahkan oleh Cloud Translation API.

File tata letak kunci

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

Wajib untuk perangkat input internal (bawaan) dengan tombol, termasuk tombol khusus seperti tombol volume, daya, dan media headset.
Opsional untuk perangkat input lainnya, tetapi direkomendasikan untuk keyboard dan joystick khusus.

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

Lokasi

File tata letak tombol terletak berdasarkan vendor USB, ID produk (dan versi opsional), atau berdasarkan nama perangkat input. Jalur berikut akan 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 '_' akan diganti dengan '_'.

File tata letak kunci umum

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

Sintaksis

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

Pernyataan 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. Setiap pernyataan dapat diikuti dengan kumpulan flag kebijakan opsional yang dipisahkan spasi kosong.

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

Flag kebijakan berikut dikenali:

FUNCTION: Tombol harus ditafsirkan seolah-olah tombol FUNCTION juga ditekan.
GESTURE: Kunci yang dihasilkan oleh gestur pengguna, seperti menggeser layar sentuh dengan telapak tangan.
VIRTUAL: Tombol adalah tombol virtual (tombol kapasitif) yang berdekatan dengan layar sentuh utama. Hal ini menyebabkan logika debouncing khusus diaktifkan (lihat di bawah).

Deklarasi sumbu

Setiap deklarasi sumbu terdiri dari kata kunci axis, diikuti dengan nomor kode sumbu Linux dan penentu yang mengontrol perilaku sumbu termasuk minimal 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 oleh 0x00) ke AXIS_X (ditunjukkan oleh X).

axis 0x00 X

Pada contoh di atas, jika nilai ABS_X adalah 5, AXIS_X akan ditetapkan ke 5.

Sumbu terpisah

Sumbu pemisahan memetakan kode sumbu Linux ke dua nama kode sumbu Android, sehingga nilai yang kurang dari atau lebih besar dari nilai minimum akan dibagi di dua sumbu yang berbeda saat dipetakan. Pemetaan ini berguna saat satu sumbu fisik yang dilaporkan oleh perangkat mengenkode dua sumbu logis yang berbeda dan saling eksklusif.

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

axis 0x01 split 0x7f GAS BRAKE

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

Sumbu terbalik

Sumbu terbalik akan membalikkan tanda nilai sumbu. Deklarasi berikut memetakan ABS_RZ (ditunjukkan oleh 0x05) ke AXIS_BRAKE (ditunjukkan oleh BRAKE), dan membalik output dengan mennegatifkannya.

axis 0x05 invert BRAKE

Pada contoh di atas, jika nilai ABS_RZ adalah 2, AXIS_BRAKE akan ditetapkan ke -2.

Opsi rata tengah

Perangkat joystick dapat melaporkan peristiwa input meskipun joystick tidak digunakan, karena derau. Derau ini biasanya berasal dari tongkat kiri dan/atau kanan, dan menyebabkan driver melaporkan nilai posisi mendekati 0. Nilai "center flat" menentukan jumlah derau yang diharapkan dari pengontrol saat tidak ada aktivitas.

Protokol input Linux menyediakan cara bagi driver perangkat input untuk menentukan nilai datar tengah sumbu joystick, tetapi 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 harus dianggap sebagai berpusat.

Misalnya, jika driver perangkat melaporkan nilai untuk AXIS_X antara 0 dan 100, maka 0 akan dipetakan ke -1 dan 100 akan dipetakan ke 1 oleh sistem input Android. Pusat rentang akan menjadi 50 dalam koordinat yang tidak diskalakan dan 0 dalam koordinat yang diskalakan. Jika nilai datar sama dengan 10, developer harus mengasumsikan bahwa nilai AXIS_X apa pun yang dilaporkan antara -0,1 dan 0,1 (antara 40 dan 60 dalam koordinat yang tidak diskalakan) adalah derau, dan memperlakukan nilai tersebut 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

Pada contoh di atas, nilai datar tengah ditetapkan ke 4096.

Komentar

Baris komentar dimulai dengan # dan berlanjut ke akhir baris:

# A comment!

Baris kosong akan diabaikan.

Contoh

Keyboard

# 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 colokan 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

Joystick

# 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 virtual

Sistem input menyediakan fitur khusus untuk menerapkan tombol virtual dalam kasus penggunaan berikut:

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

Jika tombol virtual berada dalam atau di dekat jarak fisik dekat layar sentuh, pengguna dapat dengan 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 atas di layar. Untuk mencegah hal ini, sistem input menerapkan sedikit debouncing sehingga penekanan tombol virtual diabaikan selama jangka waktu singkat setelah sentuhan terbaru pada layar sentuh (penundaan ini disebut waktu tenang tombol virtual).

Untuk mengaktifkan debouncing tombol virtual:

Berikan file tata letak tombol untuk perangkat input layar sentuh atau tombol kapasitif dengan flag VIRTUAL yang ditetapkan untuk setiap tombol.
```
key 139    MENU           VIRTUAL
key 172    HOME           VIRTUAL
key 158    BACK           VIRTUAL
key 217    SEARCH         VIRTUAL
```

Tetapkan nilai waktu tenang kunci virtual dalam overlay resource untuk resource config.xml framework.

<!-- 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 tombol menggunakan alat Validate Keymaps.