Disclaimer
This short tutorial is based on my own research regarding missing keyboard layout mapping in stock Honeycomb/ICS Android for my Motorola XOOM. It is not intended to be a complete description of the Android input system, please refer to the official documentation for more information. This text should suffice for anyone with a basic knowledge about IT
Anyway, if you break something, 'aint my fault. Won't take any responsibilities for YOUR actions.
Requirements
- rooted Android 3.0+ device (3.0, 3.1, 3.2, 4.0)
- text editor
- external keyboard to play with
Background stuff
(simplified, no bashing)
Keyboard (connected to any device) sends key codes to the target device. Key codes are just plain numbers, eg. if you press the "A" key on the keyboard, the computer reads "30" number. Since "30" is quite difficult to remember as being the "A" button, it is much more handy to describe keycodes as char codes: in the target software we get a KEY_A instead of 30.
Android uses two files for keyboard key-to-output mapping: .kl (key layout) and .kcm (key character map).
*.kl file describes the mapping between real keyboard codes to their virtual values, eg. 30 => KEY_A.
*.kcm file converts char codes to key events (KEY_A pressed? Send character "a". Shift + KEY_A? Send character "A", etc.)
So if you connect an external keyboard (USB, BT, Ir?) to your Android device, you get the following chain:
All devices (well, most of them) can be identified by VID (Vendor ID) and PID (product ID). VID and PID are 4 hex symbols each.
Android by default uses /system/usr/keylayout/Generic.kl and /system/usr/keychars/Generic.kcm for keyboard handling. If you look into /system/usr/keylayout/ and /system/usr/keychars/ you may find some more keymaps, including something like Vendor_xxxx_Product_xxxx.* Those files are used for specific devices, eg. Vendor_045e_Product_028e.kl is used for XBox 360 controller. When you connect the keyboard, Android checks the peripherial device VID and PID and looks for matching kl and/or kcm. If there is no matching file found, Generic.kl/Generic.kcm is used instead (disjoint -> you may have a specific kl and generic kcm, generic kl and specific kcm, etc.).
You may get the PID/VID of your external keyboard under for example Windows (in device manager [devmgmt.msc] find your keyboard and check its details [properties->details], for example HID\VID_046D&PID_C312\6&26DA469B&0&0000 => Vendor_046d_Product_C312). So if you would like to prepare a keymap for my USB Logitech keyboard, you will have to provide me with Vendor_046d_Product_C312.[kl|kcm] files
Both KCM and KL files are encoded in ANSI -> no special (national) characters allowed except for 'classic' set! If you want to include any national or extra character, you need to use their unicode hex values in \uXXXX variant. See http://www.tamasoft.co.jp/en/general-info/unicode.html for a huge list of unicode characters.
Getting hands dirty
- pull Generic.kcm from your device via adb:
- open it with Notepad++
- scroll through the blahblah about not modifying the file to the section with
- this is where your work starts!
In general the map is composed as fillows:
Modifiers can be: ralt, lalt, alt (right/left ALT, any ALT), rshift, lshift, shift (right/left SHIFT, any SHIFT), rctrl, lctrl, ctrl (left/right CTRL, any CTRL), capslock (no right CAPSLOCK on the kb, sorry ), rmeta, lmeta, meta (right/left WIN key, any WIN key). There are probably more, but didn't encounter any...
So, let's make the A key work like on Polish (Programmer) keyboard layout (namely a, A, ą, Ą letters):
Polish letters "ą" and "Ą" have their unicode values of 0x0105 and 0x0104 respectively, thus in order to have them available via right alt + A, we use ralt modifier and shift/capslock ralt modifier. Please note, that it is necessary to have 'shift' modifier for capital A.
is used to map certain key combinations to other commands ("hardware buttons"), such as HOME, SEARCH, MENU, APP_SWITCH, etc. Thus if for example you would like to have lalt+tab for app switching you would have to use the following:
And now a Windows+D for desktop shortcut:
In short
- in most cases the Generic.kl file is ok, there is no need to prepare .kl for a common keyboard
- either edit Generic.kcm or get VID/PID of your keyboard and prepare a key layout for your language and push it to /system/usr/keychars/
Hints
- backup your Generic.kcm file!
- try to be as specific as possible if you do not use a combination, map it into 'none' section; when you map ralt, don't include alt in 'none', include lalt instead. Remember, that some key combinations have special meanings (ctrl+d, ctrl+c, ctrl+v, etc), and it is better not to include them in your map.
- backup your layout - I lost a lot of time re-creating my keymap after ROM upgrade (symbolic link is a better idea!)
- look through the entire Generic.kcm file - there are a lot of fancy key combinations, for example ESCAPE key can !by default! handle MENU, BACK and HOME keys!
- possible fallback keys are listed in .kl file
- use logcat! You can spot information about external input device and a note about applied KCM/KL files
Finally
Hit "thanks" if you find it helpful. If you prepare a good (national) key layout, please share it!
This short tutorial is based on my own research regarding missing keyboard layout mapping in stock Honeycomb/ICS Android for my Motorola XOOM. It is not intended to be a complete description of the Android input system, please refer to the official documentation for more information. This text should suffice for anyone with a basic knowledge about IT
Anyway, if you break something, 'aint my fault. Won't take any responsibilities for YOUR actions.Requirements
- rooted Android 3.0+ device (3.0, 3.1, 3.2, 4.0)
- text editor
- external keyboard to play with
Background stuff
(simplified, no bashing
)Keyboard (connected to any device) sends key codes to the target device. Key codes are just plain numbers, eg. if you press the "A" key on the keyboard, the computer reads "30" number. Since "30" is quite difficult to remember as being the "A" button, it is much more handy to describe keycodes as char codes: in the target software we get a KEY_A instead of 30.
Android uses two files for keyboard key-to-output mapping: .kl (key layout) and .kcm (key character map).
*.kl file describes the mapping between real keyboard codes to their virtual values, eg. 30 => KEY_A.
*.kcm file converts char codes to key events (KEY_A pressed? Send character "a". Shift + KEY_A? Send character "A", etc.)
So if you connect an external keyboard (USB, BT, Ir?) to your Android device, you get the following chain:
Code:
[keyboard] => [kl] => [kcm] => [application]All devices (well, most of them) can be identified by VID (Vendor ID) and PID (product ID). VID and PID are 4 hex symbols each.
Android by default uses /system/usr/keylayout/Generic.kl and /system/usr/keychars/Generic.kcm for keyboard handling. If you look into /system/usr/keylayout/ and /system/usr/keychars/ you may find some more keymaps, including something like Vendor_xxxx_Product_xxxx.* Those files are used for specific devices, eg. Vendor_045e_Product_028e.kl is used for XBox 360 controller. When you connect the keyboard, Android checks the peripherial device VID and PID and looks for matching kl and/or kcm. If there is no matching file found, Generic.kl/Generic.kcm is used instead (disjoint -> you may have a specific kl and generic kcm, generic kl and specific kcm, etc.).
You may get the PID/VID of your external keyboard under for example Windows (in device manager [devmgmt.msc] find your keyboard and check its details [properties->details], for example HID\VID_046D&PID_C312\6&26DA469B&0&0000 => Vendor_046d_Product_C312). So if you would like to prepare a keymap for my USB Logitech keyboard, you will have to provide me with Vendor_046d_Product_C312.[kl|kcm] files
Both KCM and KL files are encoded in ANSI -> no special (national) characters allowed except for 'classic' set! If you want to include any national or extra character, you need to use their unicode hex values in \uXXXX variant. See http://www.tamasoft.co.jp/en/general-info/unicode.html for a huge list of unicode characters.
Getting hands dirty
- pull Generic.kcm from your device via adb:
Code:
adb pull /system/usr/keychars/Generic.kcm- scroll through the blahblah about not modifying the file to the section with
Code:
key A {
label: 'A'- this is where your work starts!
In general the map is composed as fillows:
Code:
# comment starts with a hash
key [keycode] {
label: '[label]'
base: '[key without any modifiers]'
[modifier]: '[key with modifier]'
[modifier]+[modifier]: '[key with both modifiers]'
[modifier],[modifier]: '[key with any of listed modifiers]'
[modifier]: fallback [magic key] # read below
[modifier],[modifier]: none
}Modifiers can be: ralt, lalt, alt (right/left ALT, any ALT), rshift, lshift, shift (right/left SHIFT, any SHIFT), rctrl, lctrl, ctrl (left/right CTRL, any CTRL), capslock (no right CAPSLOCK on the kb, sorry
), rmeta, lmeta, meta (right/left WIN key, any WIN key). There are probably more, but didn't encounter any...So, let's make the A key work like on Polish (Programmer) keyboard layout (namely a, A, ą, Ą letters):
Code:
key A {
label: 'A'
base: 'a'
shift, capslock: 'A'
ralt: '\u0105'
shift+ralt, capslock+ralt: '\u0104'
lalt, meta: none # ctrl omitted - ctrl+a does something...
}Polish letters "ą" and "Ą" have their unicode values of 0x0105 and 0x0104 respectively, thus in order to have them available via right alt + A, we use ralt modifier and shift/capslock ralt modifier. Please note, that it is necessary to have 'shift' modifier for capital A.
Code:
fallback [i]magic key[/i]
Code:
key TAB {
label: '\t'
base: '\t'
lalt: fallback APP_SWITCH # alt + tab :)
ralt, meta: none
}And now a Windows+D for desktop shortcut:
Code:
key D {
label: 'D'
base: 'd'
shift, capslock: 'D'
meta: fallback HOME # show desktop
alt: none
}In short
- in most cases the Generic.kl file is ok, there is no need to prepare .kl for a common keyboard
- either edit Generic.kcm or get VID/PID of your keyboard and prepare a key layout for your language and push it to /system/usr/keychars/
Hints
- backup your Generic.kcm file!
- try to be as specific as possible
if you do not use a combination, map it into 'none' section; when you map ralt, don't include alt in 'none', include lalt instead. Remember, that some key combinations have special meanings (ctrl+d, ctrl+c, ctrl+v, etc), and it is better not to include them in your map.- backup your layout - I lost a lot of time re-creating my keymap after ROM upgrade (symbolic link is a better idea!)
- look through the entire Generic.kcm file - there are a lot of fancy key combinations, for example ESCAPE key can !by default! handle MENU, BACK and HOME keys!
- possible fallback keys are listed in .kl file
- use logcat! You can spot information about external input device and a note about applied KCM/KL files
Finally
Hit "thanks" if you find it helpful. If you prepare a good (national) key layout, please share it!
