Keycode Mapping Guide

Enterprise Browser 3.4

Overview

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: EB 2.0 (and higher) also supports page-based actions, which can execute JavaScript code and/or predefined commands based on the contents of a page. See the Page-based Actions guide for more information.

Support Notes

  • These keys CANNOT be remapped to any other action:
    • HOME key
    • RECENT APPS key
    • Brightness key(s)
    • Backlight on/off key
  • 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.

Android Keycode Handling

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:

  • Enterprise Keyboard might be required for key mapping on devices that include a hardware keyboard.
  • Keycode mapping requires Enterprise Browser 1.4 or later.
  • Mapping requires a KeyCapture API. Read more.
  • Keycode mappings are contained in the keycodemapping.xml file.
  • The keycodemapping.xml file 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 sdcard0/Android/data/com.zebra.mdna.enterprisebrowser.
  • Keycodes not mapped (or left blank in the mapping file) retain their default values.
  • Additional restrictions apply to keycapture and keycode mapping.
  • The keycodemapping.xml file must not be empty nor contain data not formatted according to the guidelines described in this guide.

File Location

The location of the keycodemapping.xml file on the device can be specified in the <keycodemappingxmlfile> tag of the app's Config.xml file using a fully qualified path (or substitution variable) and file name. This allows separate folders to be created for storing key mappings for different apps. If no path is specified, EB's default installation folder is used as the path:

  • file://%INSTALLDIR%/keycodemapping.xml

See the Config.xml reference for more information.

Mapping Android Keycodes

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 sdcard0/Android/data/com.zebra.mdna.enterprisebrowser directory.

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.

For example: 

    
    <?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.

Mapping Hardware Keys

The hardware keys of Zebra devices can be remapped to perform predefined actions or execute JavaScript code blocks residing on the device or on a server. This feature can be useful for these and many other scenarios:

  • Zoom in and out of app page(s)
  • Show/hide custom buttons or keyboard layouts
  • Show/hide the address bar
  • Quit the EB app and return to the OS
  • Quit the app and return to a login page
  • Reboot the device
  • Enter special character(s) not available on the selected keyboard
  • Enter foreign-language characters not available on the selected keyboard
  • Activate DataWedge and/or the scanner beam
  • Clear cookies and/or the application cache
  • Enable voice input

NOTE: Key mapping failures sometimes occur on Android devices that include a hardware keyboard. In some cases it might be necessary to disable the standard Android keyboard as the default SIP and install (and/or activate, if already installed) the Zebra Enterprise Keyboard as the default. See the Enterprise Keyboard user guide for more information.

Predefined Commands

The remapping feature for hardware keys supports only the predefined actions and mapping commands shown below.

Action Commands

  • back - Navigates to the previous page in the EB app's history.
  • forward - Navigates forward one page in the EB app's history.
  • quit - Exits the EB app, executing any exit commands or actions defined in the Config.xml file.
  • refresh - Reloads the current page.

Mapping Commands

  • key-[KeyEvent] - Sends the Android KeyEvent corresponding to the constant that follows (-) to the field in focus in the underlying app. For example, "key-11" sends a KeyEvent value of "11" (KEYCODE_4). See the full list of Android KeyEvents, constants and keycode values.
  • runscript-[ScriptIdentifier] - Executes the specified JavaScript code block as defined in the CustomScript.xml file. For example: "runscript-clearcookiescript" executes the user-defined JavaScript code block in the “cleaarcookiescript” section of the CustomScript.xml file. Learn more about the CustomScript file.
  • uc-[UnicodeValue] - Sends the unicode character corresponding to the code that follows (-) to the field in focus in the underlying app. This is useful for injecting foreign-language or scientific characters or other special symbols. For example, "uc-03C0" sends the Greek character Pi. See all Unicode characters.

All commands are case-sensitive.

Remapping Hardware Keys

Hardware keys are remapped in the KeyActions section of the KeyCodeMapping .xml file (EB 2.0 and higher only). Use the instructions in the Mapping Android Keycodes section above to modify the file and push it to the device.

Example


<KeyCodeConfiguration>
    <KeyCodes>
      ...
    </KeyCodes>

    <KeyActions> 
        <KEYACTION  keyvalue="133" action="runscript-clearcookiescript"/>
        <KEYACTION  keyvalue="132" action="quit" />
        <KEYACTION  keyvalue="9" action="key-11" />
        <KEYACTION  keyvalue="135" action="uc-03C0"/>
        <KEYACTION  keyvalue="136" action="back"/>
        <KEYACTION  keyvalue="137" action="forward"/>
        <KEYACTION  keyvalue="139" action="refresh" />
    </KeyActions> 
</KeyCodeConfiguration>

Handling Incorrect Keycodes

If it is determined that correct keypresses are generating incorrect keycodes, the incorrect keycode value must be determined before the correct one can be substituted. This process uses JavaScript to expose the keycodes that appear when pressing one or more keys.

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: 

    
    // KeyCapture API 4.x: 
    EB.KeyCapture.captureKey(false,'all',function(obj){alert(obj.keyValue)
    });

    // KeyCapture API 2.x: 
    <META HTTP-Equiv="KeyCapture" Content="KeyValue:All; Dispatch:False; KeyEvent:url('JavaScript:alert('Key Pressed: %s');')">

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.

Mapping Proprietary Function Keycodes

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.

Enable and specify mapping

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.

Template 1- Map a Single Function Key

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>


Template 2- Map Multiple Function Keys

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.

Contents of the Function Key Mapping File

  • 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

Rules

  • 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.xml file, 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.xml file 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
F1 0xE0010x70
F20xE0020x71
F30xE0030x72
F40xE0040x73
F50xE0050x74
F60xE006 0x75
F70xE0070x76
F80xE0080x77
F90xE0090x78
F100xE00A0x79
F110xE00B0x7A
F120xE00C0x7B
F130xE00D0x7C
F140xE00E0x7D
F150xE00F0x7E
F160xE0100x7F
F170xE0110x80
F180xE0120x81
F190xE0130x82
F200xE0140x83
F210xE0150x84
F220xE0160x85
F230xE0170x86
F240xE0180x87

Also See