File peta karakter utama

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

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

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

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

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

Lokasi

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

Jalur berikut akan 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 '_' 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 keyboard eksternal standar.

Jangan ubah peta karakter kunci umum.

File peta karakter tombol 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 ID-nya adalah -1 (lihat KeyCharacterMap.VIRTUAL_KEYBOARD). Perangkat ini ada di semua perangkat Android mulai dari Android Honeycomb 3.0. Tujuan perangkat keyboard virtual adalah menyediakan perangkat input bawaan yang diketahui dan dapat digunakan untuk memasukkan ketukan tombol ke aplikasi oleh IME atau oleh instrumentasi pengujian, bahkan untuk perangkat yang tidak memiliki keyboard bawaan.

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

Jangan ubah peta karakter tombol virtual.

Sintaksis

File peta karakter tombol adalah file teks biasa yang terdiri dari deklarasi jenis keyboard dan kumpulan deklarasi tombol.

Deklarasi jenis keyboard

Deklarasi jenis keyboard menjelaskan perilaku keyboard secara keseluruhan. File peta karakter harus berisi deklarasi jenis keyboard. Untuk kejelasan, file ini sering 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 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: Keyboard dengan semua huruf, dan mungkin beberapa angka.

  Keyboard alfabet mendukung entri teks secara langsung, tetapi mungkin memiliki tata letak yang ringkas dengan faktor bentuk kecil. Berbeda dengan keyboard FULL, beberapa simbol mungkin hanya dapat diakses menggunakan pemilih karakter virtual khusus. Selain itu, untuk meningkatkan kecepatan dan akurasi pengetikan, framework ini menyediakan fitur khusus untuk keyboard alfabet seperti kapitalisasi otomatis dan tombol SHIFT dan ALT yang diaktifkan / dikunci.

  Jenis keyboard ini umumnya dirancang untuk mengetik dengan ibu jari.

• FULL: Keyboard gaya PC lengkap.

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

  Jenis keyboard ini umumnya dirancang untuk mengetik dengan dua tangan.

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

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

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

Pernyataan kunci

Setiap deklarasi kunci terdiri dari kata kunci key, diikuti dengan nama kode kunci Android, kurung kurawal buka, 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. Agar 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 secara bersamaan ditetapkan perilaku none.

Properti berikut dikenali:

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

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

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

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

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

• <modifier> 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 pengubah LEFT SHIFT atau RIGHT SHIFT ditekan.

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

Pengubah berikut dikenali dalam properti pengubah:

• shift: Berlaku saat pengubah LEFT SHIFT atau RIGHT SHIFT 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 ALT KIRI 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 KANAN KONTROL ditekan.
• meta: Berlaku saat pengubah META KIRI atau META KANAN ditekan.
• lmeta: Berlaku saat pengubah META KIRI ditekan.
• rmeta: Berlaku saat pengubah META KANAN 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 dikunci.
• scrolllock: Berlaku saat pengubah SCROLL LOCK terkunci.

Urutan properti yang tercantum bersifat signifikan. Saat memetakan kunci ke perilaku, sistem akan memindai semua properti yang relevan secara berurutan dan menampilkan perilaku terakhir yang berlaku yang ditemukan.

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

Perilaku

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

Perilaku berikut dikenali:

• none: Jangan mengetik karakter.

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

• 'X': Mengetik literal karakter yang ditentukan.

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

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

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

  Perilaku ini menyebabkan sistem menyimulasikan penekanan tombol yang berbeda saat aplikasi tidak menangani kunci yang ditentukan secara native. Fungsi ini digunakan untuk mendukung perilaku default untuk tombol baru yang tidak diketahui cara penanganannya oleh semua aplikasi, seperti tombol ESCAPE atau keypad numerik (saat numlock tidak ditekan).

  Saat perilaku penggantian dilakukan, aplikasi akan menerima dua penekanan tombol: satu untuk tombol asli dan satu lagi untuk tombol penggantian yang dipilih. Jika aplikasi menangani kunci asli selama tombol ditekan, peristiwa kunci penggantian akan dibatalkan (KeyEvent.isCanceled akan menampilkan true).

Sistem ini mencadangkan dua karakter Unicode untuk menjalankan fungsi khusus:

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

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

Sistem mengenali karakter Unicode berikut sebagai menggabungkan karakter tombol mati diakritik:

• '\u0300': Aksen nontirus.
• '\u0301': Aksen akut.
• '\u0302': Aksen sirkumfleks.
• '\u0303': Aksen tanda petik.
• '\u0308': Aksen umlaut.

Saat tombol mati diketik, diikuti dengan karakter lain, tombol mati dan karakter berikutnya akan digabungkan. Misalnya, saat pengguna mengetik tombol mati aksen grave diikuti dengan huruf 'a', hasilnya adalah 'à'.

Lihat KeyCharacterMap.getDeadChar untuk mengetahui informasi selengkapnya tentang penanganan tombol mati.

Komentar

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

# A comment!

Baris kosong akan diabaikan.

Cara kombinasi tombol dipetakan ke perilaku

Saat pengguna menekan tombol, sistem akan 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 akan 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 yang pertama hingga terakhir dan dari kiri ke kanan, mengabaikan properti label dan number, yang bersifat khusus.

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

Sistem kemudian akan terus memindai properti berikutnya jika ada properti yang lebih spesifik daripada base dan menggantinya. Fungsi ini menemukan shift yang juga berlaku untuk penekanan 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, aplikasi akan terus memindai tabel, tetapi tidak ada properti lain yang berlaku untuk penekanan tombol ini (CAPS LOCK tidak terkunci, tombol CONTROL tidak ditekan, tombol ALT tidak ditekan, dan tombol META tidak ditekan).

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

CONTROL + A

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

Seperti sebelumnya, sistem akan memindai tabel properti. Fungsi ini 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 menggantikan perilaku base.

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

ESCAPE

Sekarang, anggap 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, sistem akan mengirimkan KEYCODE_ESCAPE terlebih dahulu ke aplikasi. Jika aplikasi tidak menanganinya, sistem akan mencoba lagi, tetapi kali ini akan mengirimkan KEYCODE_BACK ke aplikasi seperti yang diminta oleh perilaku penggantian.

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

NUMPAD_0 dengan atau tanpa NUM LOCK

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

Deklarasi kunci berikut memastikan bahwa KEYCODE_NUMPAD_0 mengetik 0 saat NUM LOCK ditekan. Jika NUM LOCK tidak ditekan, kunci akan dikirim ke aplikasi seperti biasa, dan jika tidak ditangani, kunci penggantian KEYCODE_INSERT akan dikirim.

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 dengan aplikasi lama yang tidak mengenali atau mendukung langsung semua tombol yang ada di keyboard gaya PC lengkap.

Contoh

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

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

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

Mulai Android Honeycomb 3.0, semua file peta karakter kunci Android harus menggunakan sintaksis 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

Android saat ini tidak mendukung keyboard multibahasa. Selain itu, peta karakter tombol generik bawaan mengasumsikan tata letak keyboard bahasa Inggris Amerika Serikat.

OEM dianjurkan untuk menyediakan peta karakter tombol kustom untuk keyboard mereka jika dirancang untuk bahasa lain.

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

Validasi

Pastikan untuk memvalidasi file peta karakter kunci menggunakan alat Validate Keymaps.