File peta karakter kunci

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

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

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

Jika tidak ada file tata letak kunci khusus perangkat yang tersedia, maka sistem akan pilih {i>default<i}.

Lokasi

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

Jalur berikut digunakan 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

Ketika membuat jalur file yang berisi nama perangkat, semua karakter pada nama perangkat selain '0'-'9', 'a'-'z', 'A'-'Z', '-' atau '_' akan 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 standar keyboard.

Jangan ubah 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 {i>keyboard<i} virtual.

Perangkat keyboard virtual adalah perangkat input sintetis dengan ID -1 (lihat KeyCharacterMap.VIRTUAL_KEYBOARD). Ada di semua perangkat Android dimulai dengan Android Honeycomb 3.0. Tujuan perangkat keyboard virtual adalah untuk menyediakan perangkat input {i>built-in<i} yang dapat digunakan untuk memasukkan penekanan tombol ke dalam aplikasi oleh IME atau dengan uji instrumentasi, bahkan untuk perangkat yang tidak memiliki {i>keyboard<i} bawaan.

Keyboard virtual diasumsikan memiliki tata letak QWERTY penuh yang hal yang sama di semua perangkat. Hal ini memungkinkan aplikasi untuk menginjeksikan menekan tombol menggunakan perangkat {i>keyboard<i} 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 jenis keyboard dan satu set deklarasi kunci.

Deklarasi jenis keyboard

Deklarasi jenis keyboard menjelaskan perilaku keyboard secara keseluruhan. File peta karakter harus berisi deklarasi jenis keyboard. Agar lebih jelas, seringkali ditempatkan di bagian atas file.

type FULL

Jenis keyboard berikut dikenali:

  • NUMERIC: Keyboard numerik (12 tombol).

    Keyboard numerik mendukung entri teks menggunakan pendekatan multi-ketuk. Anda mungkin perlu mengetuk tombol beberapa kali untuk membuat 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: Keyboard dengan semua huruf, dan mungkin beberapa angka.

    Keyboard alfabet mendukung entri teks secara langsung tetapi mungkin memiliki {i>layout<i} dengan faktor bentuk yang kecil. Berbeda dengan keyboard FULL, beberapa simbol hanya dapat diakses dengan menggunakan pemilih karakter pada layar. Selain itu, untuk meningkatkan kecepatan dan akurasi pengetikan, framework ini menyediakan kemampuan khusus untuk keyboard alfabet seperti kapitalisasi otomatis dan tombol SHIFT dan ALT terkunci.

    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 {i>keyboard<i} tanpa dukungan di layar atau kemampuan seperti sebagai kapitalisasi otomatis.

    Jenis keyboard ini umumnya dirancang untuk mengetik dengan dua tangan secara penuh.

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

    Keyboard fungsi khusus hanya terdiri dari tombol yang tidak dapat dicetak seperti HOME dan POWER yang sebenarnya tidak digunakan untuk mengetik.

Peta karakter tombol Generic.kcm dan Virtual.kcm adalah keyboard FULL.

Deklarasi tombol

Setiap deklarasi kunci terdiri dari kata kunci key diikuti dengan kode kunci Android nama, kurung kurawal terbuka, kumpulan 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 dengan koma.

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

Properti berikut dikenali:

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

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

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

    Beberapa "numerik" standar simbol adalah angka '0' sampai '9', '#', '+', '(', ')', ',', dan '.'.

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

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

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

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

Pengubah berikut dikenali dalam properti pengubah:

  • shift: Berlaku saat pengubah SHIFT KIRI atau SHIFT KANAN ditekan.
  • lshift: Berlaku saat pengubah SHIFT KIRI ditekan.
  • rshift: Berlaku saat pengubah SHIFT KANAN ditekan.
  • alt: Berlaku saat pengubah LEFT ALT atau RIGHT ALT ditekan.
  • lalt: Berlaku saat pengubah LEFT ALT ditekan.
  • ralt: Berlaku saat pengubah ALT RIGHT 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 tombol META LEFT META atau RIGHT META ditekan.
  • lmeta: Berlaku saat pengubah META LEFT ditekan.
  • rmeta: Berlaku saat pengubah META RIGHT ditekan.
  • sym: Berlaku saat pengubah SYMBOL ditekan.
  • fn: Berlaku saat pengubah FUNCTION ditekan.
  • capslock: Berlaku saat pengubah CAPS LOCK terkunci.
  • numlock: Berlaku saat pengubah NUM LOCK terkunci.
  • scrolllock: Berlaku saat pengubah SCROLL LOCK terkunci.

Urutan properti yang dicantumkan bersifat signifikan. Saat memetakan kunci untuk perilaku, sistem memindai semua properti yang relevan secara berurutan dan menampilkan perilaku yang dapat diterapkan yang ditemukannya.

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

Perilaku

Setiap properti dipetakan ke perilaku. Perilaku yang paling umum adalah mengetik karakter, tapi ada yang lain.

Perilaku berikut dikenali:

  • none: Tidak mengetik karakter.

    Perilaku ini merupakan setelan default saat tidak ada karakter yang ditentukan. Menentukan none bersifat opsional tetapi dapat meningkatkan kejelasan.

  • 'X': Mengetik literal karakter yang ditentukan.

    Perilaku ini menyebabkan karakter tertentu dimasukkan ke dalam fungsi tampilan teks. Literal karakter dapat berupa karakter ASCII, atau salah satu urutan escape berikut:

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

  • fallback <Android key code name>: Melakukan tindakan default jika tombolnya tidak ditangani oleh aplikasi.

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

    Saat perilaku fallback dilakukan, aplikasi akan menerima dua penekanan tombol: satu untuk kunci asli dan satu lagi untuk kunci penggantian yang dipilih. Jika aplikasi menangani kunci asli saat kunci naik, maka kunci fallback acara akan dibatalkan (KeyEvent.isCanceled akan mengembalikan true).

Sistem mencadangkan dua karakter Unicode untuk melakukan fungsi khusus:

  • '\uef00': Jika perilaku ini dilakukan, tampilan teks akan menggunakan dan menghapus empat karakter sebelum kursor, menafsirkannya sebagai digit heksadesimal, dan memasukkan titik kode Unicode yang sesuai.

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

Sistem mengenali karakter Unicode berikut sebagai kombinasi karakter diakritik karakter utama:

  • '\u0300': Aksen nontirus.
  • '\u0301': Aksen tirus.
  • '\u0302': Aksen sirkumfleks.
  • '\u0303': Aksen tanda gelombang.
  • '\u0308': Aksen Umlaut.

Saat {i>dead key<i} diketik diikuti oleh karakter lain, {i>dead key<i} dan yang berikutnya karakter. Misalnya, saat pengguna mengetik aksen nontirus yang mati diikuti dengan huruf 'a', hasilnya adalah 'à'.

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

Komentar

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

# A comment!

Baris kosong akan diabaikan.

Cara kombinasi tombol dipetakan ke perilaku

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

SHIFT + A

Misalkan pengguna menekan A dan SHIFT secara bersamaan. Sistem mula-mula mencari 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 ditemukan adalah base. Properti base selalu berlaku untuk tombol, tidak peduli pengubah apa yang ditekan. Pada dasarnya alat ini menentukan {i>default <i} perilaku kunci kecuali jika digantikan oleh properti berikut. Karena properti base berlaku untuk penekanan tombol ini, sistem akan membuat catatan fakta bahwa perilakunya adalah 'a' (ketik karakter a).

Sistem kemudian terus memindai properti berikutnya jika ada properti lebih spesifik dari base dan menggantinya. Error 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, tabel akan terus memindai tabel, namun tidak ada properti lain yang diterapkan pada tabel ini penekanan tombol (CAPS LOCK tidak terkunci, tidak ada tombol CONTROL yang ditekan, juga tombol ALT 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. Asisten Google akan memperhatikan bahwa properti base diterapkan, tetapi juga akan terus memindai hingga akhirnya mencapai properti control. Saat dijalankan, control properti muncul setelah base sehingga perilakunya mengganti perilaku base.

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

ESCAPE

Sekarang, anggaplah pengguna menekan ESCAPE.

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

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

Saat memproses kunci tersebut, sistem akan mengirimkan KEYCODE_ESCAPE terlebih dahulu ke aplikasi. Jika aplikasi tidak menanganinya, maka sistem akan mencoba sekali lagi, tetapi kali ini, perintah tersebut akan mengirimkan KEYCODE_BACK ke aplikasi sebagai yang diminta oleh perilaku penggantian.

Jadi, aplikasi yang mengenali dan mendukung KEYCODE_ESCAPE memiliki peluang untuk menanganinya apa adanya, tetapi aplikasi lain yang tidak dapat melakukan tindakan penggantian memperlakukan kunci seolah-olah kunci tersebut adalah KEYCODE_BACK.

NUMPAD_0 dengan atau tanpa NUM LOCK

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

Deklarasi kunci berikut memastikan bahwa KEYCODE_NUMPAD_0 mengetik 0 saat NUM LOCK ditekan. Ketika NUM LOCK tidak ditekan, tombol terkirim ke aplikasi seperti biasa, dan jika tidak ditangani, maka penggantian tombol KEYCODE_INSERT akan dikirim sebagai gantinya.

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

Seperti yang dapat kita lihat, deklarasi kunci penggantian sangat meningkatkan kompatibilitas pada aplikasi lama yang tidak mengenali atau mendukung langsung semua kunci yang ada pada {i> keyboard<i} bergaya {i>full PC<i}.

Contoh

Keyboard penuh

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

Keyboard 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'
}

Game pad

# 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 telah ditentukan menggunakan sintaks yang sangat berbeda dan dikompilasi ke dalam format {i>file<i} biner (.kcm.bin) pada waktu build.

Meskipun format barunya menggunakan ekstensi yang sama .kcm, sintaksisnya cukup berbeda (dan jauh lebih ampuh).

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. Sintaksis lama tidak didukung dan file .kcm.bin lama tidak dikenali oleh sistem.

Catatan bahasa

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

OEM didorong untuk menyediakan peta karakter tombol kustom untuk keyboard mereka jika didesain untuk bahasa lain.

Versi Android mendatang mungkin menyediakan dukungan yang lebih baik untuk keyboard multibahasa atau tata letak {i>keyboard<i} yang dapat dipilih pengguna.

Validasi

Pastikan untuk memvalidasi file peta karakter kunci Anda menggunakan Alat Validasi Keymap.