Keycodes are constants that uniquely identify the ASCII values of device keypresses (hard or soft). The keycodes for keys with multiple values (such as upper and lower case) are accessed with the shift or other modifier key and in some cases cannot be captured. Enterprise Browser 1.4 permits Android keycode values to be assigned from a file when an Enterprise Browser app starts up.
Note: This guide applies only to Android.
On Android devices, the keycode values of certain keys are sometimes not returned as expected or desired. To ensure control and accuracy of key presses, the desired keycode value(s) can be assigned through the current KeyCapture 4.x API as well as legacy 2.x versions. The steps in thie guide apply to all API versions.
The following facts apply generally to keycode mapping for Enterprise Browser:
- Keycode mapping requires Enterprise Browser 1.4 or higher.
- Mapping requires a KeyCapture API. Read more.
- Keycode mappings are contained in the
keycodemapping.xmlfile is the same for all versions of the KeyCapture API.
- The mapping file is read each time Enterprise Browser is launched.
- Upon app install, a mapping-file template is placed in the EB installation directory, usually
- Keycodes not mapped (or left blank in the mapping file) retain their default values.
- Additional restrictions apply to keycapture and keycode mapping.
To assign custom keycodes to Android hard or soft keys, follow these simple steps:
1. Deploy Enterprise Browser to the device.
2. Navigate to the installation directory on the device.
This is usually the
3. Copy the
keycodemapping.xml template to a PC and open it for editing.
The template should look similar to the image below:
<?xml version = "1.0"?> <!-- .....KeyCode Mapping File.... --> <KeyCodeConfiguration> <KeyCodes> <!-- Example --> <!-- <KEYCODE name="KEYCODE_0" from="7" to="0x30" /> --> </KeyCodes> </KeyCodeConfiguration>
4. Copy and paste the example KEYCODE tag (omitting the comment tags) as shown:
... <KeyCodes> <!-- Example --> <!-- <KEYCODE name="KEYCODE_0" from="7" to="0x30" /> --> <KEYCODE name="KEYCODE_0" from="7" to="0x30" /> </KeyCodes> ...
5. Replace the values (within the quotes) for 'name,' 'from' and 'to' fields, as required.
Note: The 'from' field refers to the key's current keycode value; the 'to' will hold the value that replaces it. In the example above, pressing the '0' key (after mapping) will generate a keycode value of '0x30' instead of its former value of '7.' The 'name' field can hold any value; standard Android key names are recommended.
For help exposing the keycodes, see the Handling Incorrect Keycodes section below.
6. Repeat steps 4 and 5 until all required keycodes are mapped.
<?xml version = "1.0"?> <!-- .....KeyCode Mapping File.... --> <KeyCodeConfiguration> <KeyCodes> <!-- Example --> <!-- <KEYCODE name="KEYCODE_0" from="7" to="0x30" /> --> <KEYCODE name="KEYCODE_F1" from="131" to="20" /> <KEYCODE name="KEYCODE_ENTER" from="46" to="76" /> <KEYCODE name="KEYCODE_E" from="33" to="7" /> <KEYCODE name="KEYCODE_BACK" from="4" to="32" /> <KEYCODE name="KEYCODE_VOLUME_DOWN" from="25" to="175" /> </KeyCodes> </KeyCodeConfiguration>
7. Copy the modified
keycodemapping.xml file to its original location on the device, replacing the template.
8. Relaunch the Enterprise Browser app and check that its keycodes are mapped as specified.
The first step is to confirm that Windows keycodes are not being forced as a result of the <isWindowsKey> tag:
1. In the app's Config.xml file, confirm that the <isWindowsKey> tag has a value of 0.
2. Using one of the KeyCapture APIs, reveal the keycodes generated by keypresses to identify incorrect keycode value(s). The test code might look something like this:
3. Map the incorrect keycode values to the correct ones using the same syntax described in the earlier section:
<KEYCODE name="[KEYCODE_X]" from="[incorrect_keycode]" to="[correct_keycode]" />
For example, if Step 2 determined that the keycode value being generated is 0x05 and the desired value is 0x06, then the correct mapping statement would be:
<KEYCODE name="KEYCODE_X" from="0x05" to="0x06" />
where "KEYCODE_X" = the name of the keycode. Standard Android key names are recommended.
4. Relaunch Enterprise Browser and repeat Step 2 to confirm that correct code(s) are generated.