File peta karakter kunci

File peta karakter kunci (file .kcm ) bertanggung jawab untuk memetakan kombinasi kode kunci Android dengan pengubah karakter Unicode.

File tata letak kunci khusus perangkat diperlukan untuk semua perangkat masukan internal (bawaan) yang memiliki kunci, jika hanya untuk memberi tahu sistem bahwa perangkat tersebut hanya untuk keperluan khusus (bukan keyboard lengkap).

File tata letak tombol khusus perangkat bersifat opsional untuk keyboard eksternal, dan sering kali tidak diperlukan sama sekali. Sistem menyediakan peta karakter kunci umum yang cocok untuk banyak keyboard eksternal.

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

Lokasi

File peta karakter kunci ditempatkan berdasarkan vendor USB, id produk (dan versi opsional), atau berdasarkan nama perangkat input.

Jalur berikut dikonsultasikan secara berurutan.

  • /odm/usr/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm
  • /vendor/usr/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm
  • /system/usr/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm
  • /data/system/devices/keychars/Vendor_XXXX_Product_XXXX_Version_XXXX.kcm
  • /odm/usr/keychars/Vendor_XXXX_Product_XXXX.kcm
  • /vendor/usr/keychars/Vendor_XXXX_Product_XXXX.kcm
  • /system/usr/keychars/Vendor_XXXX_Product_XXXX.kcm
  • /data/system/devices/keychars/Vendor_XXXX_Product_XXXX.kcm
  • /odm/usr/keychars/DEVICE_NAME.kcm
  • /vendor/usr/keychars/DEVICE_NAME.kcm
  • /system/usr/keychars/DEVICE_NAME.kcm
  • /data/system/devices/keychars/DEVICE_NAME.kcm
  • /odm/usr/keychars/Generic.kcm
  • /vendor/usr/keychars/Generic.kcm
  • /system/usr/keychars/Generic.kcm
  • /data/system/devices/keychars/Generic.kcm
  • /odm/usr/keychars/Virtual.kcm
  • /vendor/usr/keychars/Virtual.kcm
  • /system/usr/keychars/Virtual.kcm
  • /data/system/devices/keychars/Virtual.kcm

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

File peta karakter kunci generik

Sistem menyediakan file peta karakter kunci bawaan khusus yang disebut Generic.kcm . Peta karakter kunci ini dimaksudkan untuk mendukung berbagai keyboard eksternal standar.

Jangan mengubah peta karakter kunci generik!

File peta karakter kunci virtual

Sistem menyediakan file peta karakter kunci bawaan khusus yang disebut Virtual.kcm yang digunakan oleh perangkat keyboard virtual.

Perangkat keyboard virtual adalah perangkat input sintetis yang idnya -1 (lihat KeyCharacterMap.VIRTUAL_KEYBOARD ). Itu hadir di semua perangkat Android yang dimulai dengan Android Honeycomb 3.0. Tujuan dari perangkat keyboard virtual adalah untuk menyediakan perangkat input internal yang diketahui yang dapat digunakan untuk memasukkan penekanan tombol ke dalam aplikasi melalui IME atau instrumentasi pengujian, bahkan untuk perangkat yang tidak memiliki keyboard internal.

Keyboard virtual diasumsikan memiliki tata letak QWERTY lengkap yang sama di semua perangkat. Hal ini memungkinkan aplikasi memasukkan penekanan tombol menggunakan perangkat keyboard virtual dan selalu mendapatkan hasil yang sama.

Jangan mengubah peta karakter kunci virtual!

Sintaksis

File peta karakter kunci adalah file teks biasa yang terdiri dari deklarasi tipe keyboard dan serangkaian deklarasi kunci.

Deklarasi jenis keyboard

Deklarasi jenis keyboard menjelaskan perilaku keyboard secara keseluruhan. File peta karakter harus berisi deklarasi tipe keyboard. Untuk lebih jelasnya, ini sering ditempatkan di bagian atas file.

type FULL

Jenis keyboard berikut ini dikenali:

  • NUMERIC : Keyboard numerik (12 tombol).

    Papan ketik numerik mendukung entri teks menggunakan pendekatan multi-ketuk. Mungkin perlu mengetuk tombol beberapa kali untuk menghasilkan huruf atau simbol yang diinginkan.

    Keyboard jenis ini umumnya dirancang untuk mengetik dengan ibu jari.

    Sesuai dengan KeyCharacterMap.NUMERIC .

  • PREDICTIVE : Papan ketik dengan semua huruf, namun lebih dari satu huruf per tombol.

    Keyboard jenis ini umumnya dirancang untuk mengetik dengan ibu jari.

    Sesuai dengan KeyCharacterMap.PREDICTIVE .

  • ALPHA : Papan ketik dengan semua huruf, dan mungkin beberapa angka.

    Papan ketik alfabet mendukung entri teks secara langsung tetapi mungkin memiliki tata letak ringkas dengan faktor bentuk kecil. Berbeda dengan keyboard FULL , beberapa simbol hanya dapat diakses menggunakan pemilih karakter khusus di layar. Selain itu, untuk meningkatkan kecepatan dan akurasi pengetikan, kerangka kerja ini menyediakan kemampuan khusus untuk keyboard alfabet seperti kapitalisasi otomatis dan tombol SHIFT dan ALT yang dapat diubah/dikunci.

    Keyboard jenis ini umumnya dirancang untuk mengetik dengan ibu jari.

  • FULL : Keyboard bergaya PC lengkap.

    Keyboard lengkap berfungsi seperti keyboard PC. Semua simbol diakses secara langsung dengan menekan tombol pada keyboard tanpa dukungan di layar atau kemampuan seperti kapitalisasi otomatis.

    Jenis keyboard ini umumnya dirancang untuk pengetikan dua tangan penuh.

  • SPECIAL_FUNCTION : Keyboard yang hanya digunakan untuk menjalankan fungsi kontrol sistem dan bukan untuk mengetik.

    Keyboard fungsi khusus hanya terdiri dari tombol non-cetak seperti HOME dan POWER yang sebenarnya tidak digunakan untuk mengetik.

Peta karakter kunci Generic.kcm dan Virtual.kcm keduanya merupakan keyboard FULL .

Deklarasi kunci

Deklarasi kunci masing-masing terdiri dari kata kunci key diikuti dengan nama kode kunci Android, kurung kurawal terbuka, sekumpulan properti dan perilaku, serta kurung kurawal tutup.

key A {
    label:                              'A'
    base:                               'a'
    shift, capslock:                    'A'
    ctrl, alt, meta:                    none
}

Properti

Setiap properti kunci menetapkan pemetaan dari kunci ke perilaku. Untuk membuat file peta karakter kunci lebih ringkas, beberapa properti dapat dipetakan ke perilaku yang sama dengan memisahkannya menggunakan koma.

Dalam contoh di atas, properti label diberi perilaku 'A' . Demikian pula, properti ctrl , alt dan meta semuanya secara bersamaan diberi perilaku none .

Properti berikut ini dikenali:

  • label : Menentukan label yang dicetak secara fisik pada kunci, jika terdiri dari satu karakter. Ini adalah nilai yang dikembalikan oleh metode KeyCharacterMap.getDisplayLabel .

  • number : Menentukan perilaku (karakter yang harus diketik) ketika tampilan teks numerik memiliki fokus, seperti ketika pengguna mengetik nomor telepon.

    Keyboard ringkas sering kali menggabungkan beberapa simbol ke dalam satu tombol, sehingga tombol yang sama dapat digunakan untuk mengetik '1' dan 'a' atau '#' dan 'q' , mungkin. Untuk kunci ini, properti number harus diatur untuk menunjukkan simbol mana yang harus diketik dalam konteks numerik, jika ada.

    Beberapa simbol "numerik" yang umum adalah angka '0' hingga '9' , '#' , '+' , '(' , ')' , ',' , dan '.' .

  • base : Menentukan perilaku (karakter yang harus diketik) ketika tidak ada pengubah yang ditekan.

  • <modifier> atau <modifier1> + <modifier2> + ...: Menentukan perilaku (karakter yang harus diketik) ketika tombol ditekan dan semua pengubah yang ditentukan aktif.

    Misalnya, properti pengubah shift menentukan perilaku yang berlaku ketika pengubah SHIFT KIRI atau SHIFT KANAN ditekan.

    Demikian pula, properti pengubah rshift+ralt menentukan perilaku yang berlaku ketika pengubah RIGHT SHIFT dan RIGHT ALT ditekan bersamaan.

Pengubah berikut dikenali di properti pengubah:

  • shift : Berlaku ketika pengubah LEFT SHIFT atau RIGHT SHIFT ditekan.
  • lshift : Berlaku ketika pengubah LEFT SHIFT ditekan.
  • rshift : Berlaku ketika pengubah RIGHT SHIFT ditekan.
  • alt : Berlaku ketika pengubah ALT KIRI atau ALT KANAN ditekan.
  • lalt : Berlaku ketika pengubah ALT KIRI ditekan.
  • ralt : Berlaku ketika pengubah ALT KANAN ditekan.
  • ctrl : Berlaku ketika pengubah LEFT CONTROL atau RIGHT CONTROL ditekan.
  • lctrl : Berlaku ketika pengubah LEFT CONTROL ditekan.
  • rctrl : Berlaku ketika pengubah RIGHT CONTROL ditekan.
  • meta : Berlaku ketika pengubah META KIRI atau META KANAN ditekan.
  • lmeta : Berlaku ketika pengubah META KIRI ditekan.
  • rmeta : Berlaku ketika pengubah META KANAN ditekan.
  • sym : Berlaku ketika pengubah SYMBOL ditekan.
  • fn : Berlaku ketika pengubah FUNCTION ditekan.
  • capslock : Berlaku ketika pengubah CAPS LOCK terkunci.
  • numlock : Berlaku ketika pengubah NUM LOCK terkunci.
  • scrolllock : Berlaku ketika pengubah SCROLL LOCK terkunci.

Urutan pencatatan properti sangatlah penting. Saat memetakan kunci ke suatu perilaku, sistem memindai semua properti yang relevan secara berurutan dan mengembalikan perilaku terakhir yang dapat diterapkan yang ditemukan.

Akibatnya, properti yang ditentukan kemudian akan menggantikan properti yang ditentukan sebelumnya untuk kunci tertentu.

Perilaku

Setiap properti dipetakan ke suatu perilaku. Perilaku yang paling umum adalah mengetik karakter tetapi ada juga yang lainnya.

Perilaku berikut ini dikenali:

  • none : Jangan mengetikkan karakter.

    Perilaku ini adalah default ketika tidak ada karakter yang ditentukan. Menentukan none yang bersifat opsional tetapi akan meningkatkan kejelasan.

  • 'X' : Ketikkan karakter literal yang ditentukan.

    Perilaku ini menyebabkan karakter tertentu dimasukkan ke dalam tampilan teks terfokus. Karakter literal dapat berupa karakter ASCII apa pun, atau salah satu dari rangkaian escape berikut:

    • '\\' : Ketikkan karakter garis miring terbalik.
    • '\n' : Ketikkan karakter baris baru (gunakan ini untuk ENTER / RETURN).
    • '\t' : Ketikkan karakter TAB.
    • '\'' : Ketikkan karakter apostrof.
    • '\"' : Ketikkan karakter kutipan.
    • '\uXXXX' : Ketikkan karakter Unicode yang titik kodenya diberikan dalam hex sebanyak XXXX.

  • fallback <nama kode kunci Android>: Melakukan tindakan default jika kunci tidak ditangani oleh aplikasi.

    Perilaku ini menyebabkan sistem mensimulasikan penekanan tombol yang berbeda ketika aplikasi tidak menangani kunci yang ditentukan secara asli. Ini digunakan untuk mendukung perilaku default untuk tombol baru yang tidak semua aplikasi tahu cara menanganinya, seperti ESCAPE atau tombol keypad numerik (saat numlock tidak ditekan).

    Ketika perilaku fallback dilakukan, aplikasi akan menerima dua penekanan tombol: satu untuk kunci asli dan satu lagi untuk kunci fallback yang dipilih. Jika aplikasi menangani kunci asli selama key up, maka event kunci fallback akan dibatalkan ( KeyEvent.isCanceled akan mengembalikan true ).

Sistem mencadangkan dua karakter Unicode untuk menjalankan fungsi khusus:

  • '\uef00' : Saat perilaku ini dilakukan, tampilan teks menggunakan dan menghapus empat karakter sebelum kursor, menafsirkannya sebagai digit hex, dan menyisipkan titik kode Unicode yang sesuai.

  • '\uef01' : Saat perilaku ini dilakukan, tampilan teks menampilkan dialog pemilih karakter yang berisi simbol lain-lain.

Sistem mengenali karakter Unicode berikut sebagai kombinasi karakter kunci mati diakritik:

  • '\u0300' : Aksen serius.
  • '\u0301' : Aksen lancip.
  • '\u0302' : Aksen sirkumfleks.
  • '\u0303' : Aksen tilde.
  • '\u0308' : Aksen Umlaut.

Ketika kunci mati diketik diikuti oleh karakter lain, kunci mati dan karakter berikut akan dibuat. Misalnya, ketika pengguna mengetik kunci mati dengan aksen berat diikuti huruf 'a', hasilnya adalah 'à'.

Lihat KeyCharacterMap.getDeadChar untuk informasi selengkapnya tentang penanganan kunci mati.

Komentar

Baris komentar dimulai dengan '#' dan berlanjut hingga akhir baris. Seperti ini:

# A comment!

Baris kosong diabaikan.

Bagaimana kombinasi kunci dipetakan ke perilaku

Saat pengguna menekan sebuah tombol, sistem mencari perilaku yang terkait dengan kombinasi penekanan tombol tersebut dan pengubah yang saat ini ditekan.

SHIFT + A

Misalkan pengguna menekan A dan SHIFT secara bersamaan. Sistem pertama-tama menemukan kumpulan properti dan perilaku yang terkait dengan KEYCODE_A .

key A {
    label:                              'A'
    base:                               'a'
    shift, capslock:                    'A'
    ctrl, alt, meta:                    none
}

Sistem memindai properti dari pertama hingga terakhir dan kiri ke kanan, mengabaikan properti label dan number , yang bersifat khusus.

Properti pertama yang ditemui adalah base . Properti base selalu berlaku untuk sebuah kunci, tidak peduli pengubah apa yang ditekan. Ini pada dasarnya menentukan perilaku default untuk kunci kecuali jika ditimpa oleh properti berikut. Karena properti base berlaku untuk penekanan tombol ini, sistem mencatat fakta bahwa perilakunya adalah 'a' (ketik karakter a ).

Sistem kemudian melanjutkan memindai properti berikutnya jika ada properti yang lebih spesifik daripada base dan menimpanya. Ia menemui shift yang juga berlaku untuk menekan tombol SHIFT + A. Jadi sistem memutuskan untuk mengabaikan perilaku properti base dan memilih perilaku yang terkait dengan properti shift , yaitu 'A' (ketik karakter A ).

Kemudian melanjutkan pemindaian tabel, namun tidak ada properti lain yang berlaku untuk penekanan tombol ini (CAPS LOCK tidak dikunci, tidak ada tombol CONTROL yang ditekan, tidak ada tombol ALT yang ditekan, dan tidak ada tombol META yang ditekan).

Jadi perilaku yang dihasilkan untuk kombinasi tombol SHIFT + A adalah 'A' .

KONTROL + A

Sekarang pertimbangkan apa yang akan terjadi jika pengguna menekan A dan CONTROL secara bersamaan.

Seperti sebelumnya, sistem akan memindai tabel properti. Ia akan melihat bahwa properti base diterapkan tetapi juga akan terus memindai hingga akhirnya mencapai properti control . Kebetulan, properti control muncul setelah base sehingga perilakunya mengesampingkan perilaku base .

Jadi perilaku yang dihasilkan untuk kombinasi tombol CONTROL + A adalah none .

MELARIKAN DIRI

Sekarang anggaplah pengguna menekan ESCAPE.

key ESCAPE {
    base:                               fallback BACK
    alt, meta:                          fallback HOME
    ctrl:                               fallback MENU
}

Kali ini sistem memperoleh perilaku fallback BACK , sebuah perilaku fallback. Karena tidak ada karakter literal yang muncul, tidak ada karakter yang akan diketik.

Saat memproses kunci, sistem akan mengirimkan KEYCODE_ESCAPE terlebih dahulu ke aplikasi. Jika aplikasi tidak menanganinya, maka sistem akan mencoba lagi namun kali ini akan mengirimkan KEYCODE_BACK ke aplikasi seperti yang diminta oleh perilaku fallback.

Jadi aplikasi yang mengenali dan mendukung KEYCODE_ESCAPE mempunyai kesempatan untuk menanganinya sebagaimana adanya, namun aplikasi lain yang tidak dapat melakukan tindakan fallback dengan memperlakukan kunci seolah-olah itu adalah KEYCODE_BACK .

NUMPAD_0 dengan atau tanpa NUM LOCK

Tombol keypad numerik memiliki interpretasi yang sangat berbeda tergantung pada apakah tombol NUM LOCK terkunci atau tidak.

Deklarasi kunci berikut memastikan bahwa KEYCODE_NUMPAD_0 mengetik 0 ketika NUM LOCK ditekan. Ketika NUM LOCK tidak ditekan, kunci dikirimkan ke aplikasi seperti biasa, dan jika tidak ditangani, maka kunci cadangan KEYCODE_INSERT dikirimkan sebagai gantinya.

key NUMPAD_0 {
    label, number:                      '0'
    base:                               fallback INSERT
    numlock:                            '0'
    ctrl, alt, meta:                    none
}

Seperti yang bisa kita lihat, deklarasi kunci cadangan sangat meningkatkan kompatibilitas dengan aplikasi lama yang tidak mengenali atau secara langsung mendukung semua tombol yang ada pada keyboard gaya PC lengkap.

Contoh

Papan ketik lengkap

# This is an example of part of a key character map file for a full keyboard
# include a few fallback behaviors for special keys that few applications
# handle themselves.

type FULL

key C {
    label:                              'C'
    base:                               'c'
    shift, capslock:                    'C'
    alt:                                '\u00e7'
    shift+alt:                          '\u00c7'
    ctrl, meta:                         none
}

key SPACE {
    label:                              ' '
    base:                               ' '
    ctrl:                               none
    alt, meta:                          fallback SEARCH
}

key NUMPAD_9 {
    label, number:                      '9'
    base:                               fallback PAGE_UP
    numlock:                            '9'
    ctrl, alt, meta:                    none
}

Papan ketik alfanumerik

# This is an example of part of a key character map file for an alphanumeric
# thumb keyboard.  Some keys are combined, such as `A` and `2`.  Here we
# specify `number` labels to tell the system what to do when the user is
# typing a number into a dial pad.
#
# Also note the special character '\uef01' mapped to ALT+SPACE.
# Pressing this combination of keys invokes an on-screen character picker.

type ALPHA

key A {
    label:                              'A'
    number:                             '2'
    base:                               'a'
    shift, capslock:                    'A'
    alt:                                '#'
    shift+alt, capslock+alt:            none
}

key SPACE {
    label:                              ' '
    number:                             ' '
    base:                               ' '
    shift:                              ' '
    alt:                                '\uef01'
    shift+alt:                          '\uef01'
}

Papan permainan

# This is an example of part of a key character map file for a game pad.
# It defines fallback actions that enable the user to navigate the user interface
# by pressing buttons.

type SPECIAL_FUNCTION

key BUTTON_A {
    base:                               fallback BACK
}

key BUTTON_X {
    base:                               fallback DPAD_CENTER
}

key BUTTON_START {
    base:                               fallback HOME
}

key BUTTON_SELECT {
    base:                               fallback MENU
}

Catatan kompatibilitas

Sebelum Android Honeycomb 3.0, peta karakter kunci Android ditentukan menggunakan sintaksis yang sangat berbeda dan dikompilasi ke dalam format file biner ( .kcm.bin ) pada waktu pembuatan.

Meskipun format baru ini menggunakan ekstensi yang sama .kcm , sintaksisnya sangat berbeda (dan jauh lebih canggih).

Mulai Android Honeycomb 3.0, semua file peta karakter kunci Android harus menggunakan format file teks biasa dan sintaksis baru seperti yang dijelaskan dalam dokumen ini. Sintaks lama tidak didukung dan file .kcm.bin lama tidak dikenali oleh sistem.

Catatan bahasa

Android saat ini tidak mendukung keyboard multibahasa. Selain itu, peta karakter kunci generik bawaan mengasumsikan tata letak keyboard Inggris AS.

OEM didorong untuk menyediakan peta karakter kunci khusus untuk keyboard mereka jika dirancang untuk bahasa lain.

Versi Android mendatang mungkin memberikan dukungan yang lebih baik untuk papan ketik multibahasa atau tata letak papan ketik yang dapat dipilih pengguna.

Validasi

Pastikan untuk memvalidasi file peta karakter kunci Anda menggunakan alat Validasi Peta Kunci .