Keycode Mapping Guide

Enterprise Browser 1.4

Overview

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.

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 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.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.symbol.enterprisebrowser.
  • Keycodes not mapped (or left blank in the mapping file) retain their default values.
  • Additional restrictions apply to keycapture and keycode mapping.

Mapping 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.symbol.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.

Handling Incorrect Keycodes

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

More Information