Keycodes are constants that uniquely identify the ASCII values of device keypresses (hard or soft). Android apps made with Enterprise Browser 1.4 and higher permit Android keycode values to be assigned from a file when an Enterprise Browser app starts up. Note: The keycodes for keys with multiple values accessed with the shift or other modifier key (such as upper and lower case) might not be capturable. See the KeyCapture API remarks for more information.
Note: The WorkAbout Pro 4 and Omnii XT15 are among a small group of Zebra devices running Windows Mobile that return proprietary keycode values inconsistent with those of other devices and incompatible with Windows. To address this issue, apps made with Enterprise Browser 1.5 or higher can remap those proprietary keycodes to Microsoft standard codes. See the Mapping Proprietary Function Keycodes section below.
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 this guide apply to all API versions.
The following facts apply generally to Android 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.
For proper key remapping, the
keycodemapping.xml file must not be blank, and must contain valid key codes and the XML and syntax described in this guide.
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, which by default is
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 the name=, from= and to= fields, as required.
Note: The "from=" field refers to the key's current keycode value and "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 "7" (its former value). The "name=" field can hold any value; Zebra recommends using standard Android key names.
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.
Important: For proper key remapping, the
keycodemapping.xmlfile must not be blank, and must contain valid key codes and the XML and syntax described in this guide.
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.
- KeyCapture API - how to include the API and use its methods
- Keys that cannot be captured - including the SHIFT and ALT keys
- Android KeyEvents documentation - the official list of Android key names
The function keys of certain Zebra devices running Windows Mobile, including the WorkAbout Pro 4 and Omnii XT15 (with Windows Embedded Handheld 6.5), return a proprietary set of Unicode values via Windows character messages rather than the values expected from Windows
keydown/keyup messages. For example, pressing the F1 key returns the hexadecimal value E001 (57345 decimal) rather than the hex value 0x70 (112 decimal) as generally expected. This can lead to compatibility issues for Enterprise Browser apps when running on such devices with Windows Mobile.
For such scenarios, Zebra developed and recommends a means of mapping the proprietary Unicode values of function keys used by an Enterprise Browser application to Microsoft virtual keycode values.
Note: This method should be used only for function keys.
Mapping the function keys on a qualifying device requires adding a few lines to the app's
Config.xml file, creating a file to specify the mapping assignments and copying the file to the device.
To map proprietary function keys:
1. Add the three code lines shown below to the app's
Config.xml file as a child of the <Configuration> parent node:
<Configuration> ... // Copy the three lines below: <FunctionKeyMapping> <FunctionKeyMappingToStandardMSValue value="1"/> </FunctionKeyMapping> // and paste them into the "Configuration" node // of the app's Config.xml file </Configuration>
Note: The maximum number of child tags is 65.
2. Create a file called
EBFunctionKeyMapping.xml, and using one of the templates below, specify the function key(s) to be mapped to Microsoft virtual keycode values.
Use this template to map a single function key to a specific Microsoft keycode value. For example, to map the F1 key to a Microsoft virtual keycode, specify the proprietary Unicode value in hexadecimal (0xE001) first, followed by the Microsoft virtual keycode value in hexadecimal (0x70) as shown below:
<FUNCTION_KEY_MAPPING_TO_STANDARD_MS_VALUE> <SET_FUNCTION_KEY_TO_STANDARD_MS_VALUE IF_CHAR_VALUE="0xE001" SEND_KEYDOWN_VALUE="0x70"/> </FUNCTION_KEY_MAPPING_TO_STANDARD_MS_VALUE>
To map multiple function key to Microsoft keycode values, simply repeat the
SET_FUNCTION_KEY_TO_STANDARD_MS_VALUE (child tag) statements above within the
FUNCTION_KEY_MAPPING_TO_STANDARD_MS_VALUE root tag. The example below maps the F1 through F5 function keys:
<FUNCTION_KEY_MAPPING_TO_STANDARD_MS_VALUE> <SET_FUNCTION_KEY_TO_STANDARD_MS_VALUE IF_CHAR_VALUE="0xE001" SEND_KEYDOWN_VALUE="0x70"/> <SET_FUNCTION_KEY_TO_STANDARD_MS_VALUE IF_CHAR_VALUE="0xE002" SEND_KEYDOWN_VALUE="0x71"/> <SET_FUNCTION_KEY_TO_STANDARD_MS_VALUE IF_CHAR_VALUE="0xE003" SEND_KEYDOWN_VALUE="0x72"/> <SET_FUNCTION_KEY_TO_STANDARD_MS_VALUE IF_CHAR_VALUE="0xE004" SEND_KEYDOWN_VALUE="0x73"/> <SET_FUNCTION_KEY_TO_STANDARD_MS_VALUE IF_CHAR_VALUE="0xE005" SEND_KEYDOWN_VALUE="0x74"/> </FUNCTION_KEY_MAPPING_TO_STANDARD_MS_VALUE>
3. Once the
EBFunctionKeyMapping.xml mapping file is complete, copy the file to the
\Program Files\EnterpriseBrowser\ directory on the device.
The function key(s) will be mapped as specified in the mapping file the next time Enterprise Browser is launched and whenever an EB app is in the foreground.
- FUNCTION_KEY_MAPPING_TO_STANDARD_MS_VALUE – the root tag
- SET_FUNCTION_KEY_TO_STANDARD_MS_VALUE - the child tag associated with the root tag
- IF_CHAR_VALUE - sets the proprietary Unicode value
- SEND_KEYDOWN_VALUE - sets the Microsoft virtual keyCode value
- Proprietary function key mapping is supported on Enterprise Browser 1.5 and later.
- Maximum number of child tags is 65.
- Mapped values are used internally by Enterprise Browser apps only.
- Whenver a function key is pressed, if the value of a Windows character message matches any of the IF_CHAR_VALUE attributes mapped in the
EBFunctionKeyMapping.xmlfile, the set value of the associated SEND_KEYDOWN_VALUE attribute is sent to the Windows keydown message as the Microsoft virtual keycode value.
- This function key mapping applies only to certain Zebra devices running Windows Mobile only. These include the WorkAbout Pro 4 and Omnii XT15 (with Windows Embedded Handheld 6.5).
- The format of
EBFunctionKeyMapping.xmlfile should not be altered in any way.
- Use the table below for Proprietary and Microsoft keycode values for function keys F1 to F24.
|Function Keys||Proprietary Unicode Value||Microsoft Virtual Keycode Value|