File Peta Karakter Kunci

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

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

File tata letak kunci khusus perangkat bersifat opsional untuk keyboard eksternal, dan seringkali tidak diperlukan sama sekali. Sistem menyediakan peta karakter kunci generik 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 oleh vendor USB, id produk (dan versi opsional) atau dengan 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 '_' diganti dengan '_'.

File Peta Karakter Kunci Umum

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

Jangan ubah peta karakter kunci generik!

File Peta Karakter Kunci Virtual

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

Perangkat keyboard virtual adalah perangkat input sintetis yang id-nya -1 (lihat KeyCharacterMap.VIRTUAL_KEYBOARD ). Ini hadir di semua perangkat Android yang dimulai dengan Android Honeycomb 3.0. Tujuan dari perangkat keyboard virtual adalah untuk menyediakan perangkat input built-in yang dikenal yang dapat digunakan untuk memasukkan penekanan tombol ke dalam aplikasi oleh IME atau dengan instrumentasi uji, bahkan untuk perangkat yang tidak memiliki keyboard built-in.

Keyboard virtual diasumsikan memiliki layout QWERTY lengkap yang sama di semua perangkat. Ini memungkinkan aplikasi untuk memasukkan penekanan tombol menggunakan perangkat keyboard virtual dan selalu mendapatkan hasil yang sama.

Jangan ubah peta karakter kunci virtual!

Sintaksis

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

Deklarasi Jenis Keyboard

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

type FULL

Jenis keyboard berikut dikenali:

  • NUMERIC : Papan ketik numerik (12 tombol).

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

    Jenis keyboard ini umumnya dirancang untuk mengetik dengan ibu jari.

    Sesuai dengan KeyCharacterMap.NUMERIC .

  • PREDICTIVE : Keyboard dengan semua huruf, tetapi dengan lebih dari satu huruf per tombol.

    Jenis keyboard 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 yang ringkas dengan faktor bentuk yang 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 dialihkan / dikunci.

    Jenis keyboard ini umumnya dirancang untuk mengetik dengan ibu jari.

  • FULL : Keyboard bergaya PC lengkap.

    Keyboard lengkap berperilaku 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 mengetik dengan dua tangan penuh.

  • SPECIAL_FUNCTION : Keyboard yang hanya digunakan untuk melakukan fungsi kontrol sistem daripada 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 adalah keyboard FULL .

Deklarasi Kunci

Deklarasi kunci masing-masing terdiri dari kunci kata key diikuti dengan nama kode kunci Android, kurung kurawal terbuka, sekumpulan properti dan perilaku, dan 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 kompak, beberapa properti dapat dipetakan ke perilaku yang sama dengan memisahkannya dengan koma.

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

Properti berikut diakui:

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

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

    Papan ketik ringkas sering menggabungkan beberapa simbol menjadi 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" tipikal adalah angka '0' hingga '9' , '#' , '+' , '(' , ')' , ',' , dan '.' .

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

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

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

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

Pengubah berikut dikenali di properti pengubah:

  • shift : Berlaku saat pengubah SHIFT KIRI atau SHIFT KANAN ditekan.
  • lshift : Berlaku saat pengubah SHIFT KIRI ditekan.
  • rshift : Berlaku saat pengubah RIGHT SHIFT ditekan.
  • alt : Berlaku saat pengubah LEFT ALT atau RIGHT ALT ditekan.
  • lalt : Berlaku saat pengubah LEFT ALT ditekan.
  • ralt : Berlaku saat pengubah ALT KANAN ditekan.
  • ctrl : Berlaku saat pengubah LEFT CONTROL atau RIGHT CONTROL ditekan.
  • lctrl : Berlaku saat pengubah LEFT CONTROL ditekan.
  • rctrl : Berlaku saat pengubah RIGHT CONTROL ditekan.
  • meta : Berlaku saat pengubah LEFT META atau RIGHT META ditekan.
  • lmeta : Berlaku saat pengubah LEFT META ditekan.
  • rmeta : Berlaku saat pengubah RIGHT META ditekan.
  • sym : Berlaku saat pengubah SYMBOL ditekan.
  • fn : Berlaku saat 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 properti yang terdaftar sangat penting. Saat memetakan kunci ke suatu perilaku, sistem memindai semua properti yang relevan secara berurutan dan mengembalikan perilaku terakhir yang dapat diterapkan yang ditemukannya.

Akibatnya, properti yang ditentukan kemudian menimpa properti yang ditentukan sebelumnya untuk kunci yang diberikan.

Perilaku

Setiap properti memetakan ke suatu perilaku. Perilaku yang paling umum adalah mengetik karakter tetapi ada yang lain.

Perilaku berikut dikenali:

  • none : Jangan mengetik karakter.

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

  • 'X' : Ketik literal karakter 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 urutan escape berikut:

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

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

    Perilaku ini menyebabkan sistem mensimulasikan penekanan tombol yang berbeda saat 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 mundur dilakukan, aplikasi akan menerima dua penekanan tombol: satu untuk kunci asli dan satu lagi untuk tombol mundur 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 melakukan fungsi khusus:

  • '\uef00' : Ketika perilaku ini dilakukan, tampilan teks menggunakan dan menghapus empat karakter sebelum kursor, menafsirkannya sebagai digit heksagonal, 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 tajam.
  • '\u0302' : Aksen melingkar.
  • '\u0303' : Aksen tilde.
  • '\u0308' : Aksen Umlaut.

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

Lihat KeyCharacterMap.getDeadChar untuk informasi lebih lanjut tentang penanganan kunci mati.

Komentar

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

# A comment!

Garis kosong diabaikan.

Bagaimana Kombinasi Kunci Dipetakan ke Perilaku

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

SHIFT + A

Misalkan pengguna menekan A dan SHIFT bersamaan. Sistem pertama-tama menempatkan 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 label dan properti number , yang khusus.

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

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

Kemudian terus memindai 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 bersamaan.

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

Jadi perilaku yang dihasilkan untuk kombinasi tombol CONTROL + A 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 , perilaku mundur. 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 tetapi kali ini akan mengirimkan KEYCODE_BACK ke aplikasi seperti yang diminta oleh perilaku mundur.

Jadi aplikasi yang mengenali dan mendukung KEYCODE_ESCAPE memiliki kesempatan untuk menanganinya apa adanya, tetapi aplikasi lain yang tidak dapat melakukan tindakan mundur dengan memperlakukan kunci seolah-olah KEYCODE_BACK .

NUMPAD_0 dengan atau tanpa NUM LOCK

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

Deklarasi kunci berikut memastikan bahwa KEYCODE_NUMPAD_0 mengetik 0 saat 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 dapat kita lihat, deklarasi tombol fallback 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 ditetapkan menggunakan sintaks yang sangat berbeda dan dikompilasi ke dalam format file biner ( .kcm.bin ) pada waktu pembuatan.

Meskipun format baru menggunakan ekstensi yang sama .kcm , sintaksnya sangat berbeda (dan jauh lebih kuat).

Mulai Android Honeycomb 3.0, semua file peta karakter kunci Android harus menggunakan sintaks baru dan format file teks biasa 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 bahasa Inggris AS.

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

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

Validasi

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