KeyCapture Module

The KeyCapture Module is used to intercept or override keyboard input.

• Syntax
• Parameters
• Events
• Multi Instance
• Remarks
• Requirements
• HTML/JavaScript Examples

Syntax

Parameters

Items listed in this section indicate parameters, or attributes which can be set.

Events

Values are returned to the caller in RhoElements via Events. Most modules contain events and those returned from this module are given below along with the event parameters. Events can cause a navigation to a new URL or a JavaScript function on the page to be invoked. Each event will in most cases have a number of parameters associated with it which will either be strings or JavaScript arrays. Event parameters can be accessed either directly or via JSON objects.

keyEvent

After a KeyValue parameter has been used to specify which key to capture and whether or not to dispatch it, setting a KeyEvent will associate that key with the event to call when that key is pressed. The KeyEvent must be set after the KeyValue parameter and optionally the Dispatch parameter and to capture multiple keys you should repeat this process. The same event handler can be used to process multiple keys. Note that this event is not compatible with the Remap parameter as the two are mutually exclusive. To unregister for key events use the syntax url(‘’), an example is provided below.

triggerEvent

The TriggerEvent is invoked whenever a device hardware trigger is pressed or released. Note the registration for TriggerEvent will fail if the trigger is currently in use.

Multi Instance

When multiple RhoElememts applications are running the following considerations should be made: Only the application with Focus will have the ability to intercept or override keys.

Remarks

Keys which can not be captured

It is not possible to capture the following types of keys, although on some device configurations pressing the SHIFT key twice generates CAPS LOCK which can be captured with a key value of 16:

*  Keyboard modifiers such as SHIFT, ALT, ORANGE button, BLUE button etc.
*  Device Keys such as the screen backlight or keyboard backlight
*  Hot keys such as phone keys or 'soft' buttons, those whose 
   function changes based on the running application.
*  The Home key on the ET1 device.

Device Lockdown on ET1

Because the Home key cannot be captured on the ET1 it is possible for users to return to the system home page by pressing it. If you need to prevent this then please consult the Enterprise Tablet documentation for other device lockdown options.

Capturing Function

If you have enabled the function key in the configuration settings and that function key has some special behaviour in the Operating system the key will not be capturable unless you also set the ‘InterceptAllKeys’ option. An example of special behaviour is the F6 and F7 keys on the MC75a (non QWERTY) which control the volume up and volume down. Although ‘InterceptAllKeys’ will allow you to capture Function keys it will also disable the special Function key behaviour. Which buttons map to which function keys will differ from device to device, some devices such as the MC9500 have dedicated, labelled function keys whereas other devices such as the MC75a do not label the fact that their volume / red phone / green phone keys all behave as function keys internally.

VC70 Hardware Keys

The VC70 has a hardware keys (P1, P2, P3 and P4 as well as a brightness button) which are not capturable by the KeyCapture module. Additionally the the default Operating system behaviour (like volumeup/down) of hardware keys can not be blocked when RhoElements is running in fullscreen mode.

ES400 Application Keys

The ES400 has a hardware messaging key with an envelope icon on it that does not function like a standard Applicaiton Key. To disable this key go to ‘Settings’ on the device, then ‘Personal’, then ‘KeyRemap’ and remap it to a key not in use. Also note that the ‘Sym’ key on the ES400 is not capturable.

F5 Key

In Internet Explorer the F5 key is used to refresh the current page. It is not recommended to rely on this functionality on Windows Mobile and it is not supported

Accelerator Keys

The following keys will be affected by the ‘AccelerateKeys’ tag, see the Key Capture Overview for a more detailed explanation of Accelerator Keys. Accelerator Keys are only applicable when RhoElements is run with the Internet Explorer engine on a Windows CE device.

Key           Code    Usual Behaviour               Special behaviour in Internet Explorer

Left Arrow    0x25    Cursor left                   Scroll window left
Right Arrow   0x27    Cursor right                  Scroll window right
Up Arrow      0x26    Cursor up                     Scroll window up
Down Arrow    0x28    Cursor down                   Scroll window down
Backspace     0x08    Delete previous character.    Navigate to previous page
Enter         0x0D    Cursor line feed              Submit form
Tab           0x09    Advance to next control       Advance to next control             
                

Remapping a key to itself

If a key is remapped to itself then RhoElements will appear to hang because if that key is pressed it will generate another press of the same key, and so on forever. The same will happen if for instance key 1 is remapped to key 2, which in turn is remapped to key 1.

Special characters

On some devices certain keys containing special characters trigger two separate key events. This happens because such characters are translated by the platform into the combination of a Shift and a Base Key. Characters behaving in such way are $, %, &, “, (, ), !, :, ?, #, _, @.

Different keyboard layouts on Windows and Android

Due to the different SIP layout on Windows and Android, the following keys will return different codes: #, *, @, =, _ and .

Device Specific Exceptions

Certain devices may map their function keys to apparently normal keys, for example the VC6090 maps the ‘{’ key to F12 and the ‘}’ key to F14. In order to capture those two keys it is necessary to enable F12 and F14 in the Configuration Settings. You may also find on some devices special keys like ‘OK’ return the same code as a function key, depending on your keyboard layout.

Use of Key Capture module on Localized Operating Systems

Users of the key capture module with Chinese, Korean and Japanese operating systems should bear the following in mind: Internally the KeyCapture module stores key representations as VK codes, therefore the key event will always return VK_PROCESSKEY (229) and keys can not be individually specified. The JavaScript standard document.onkeyup can be used as an indication of which key has been pressed.

Requirements

HTML/JavaScript Examples

The following example displays an alert when any key is pressed:

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

The following example intercepts the return key and displays an alert:

<META HTTP-Equiv="KeyCapture" Content="KeyValue:0x0D; Dispatch:False; KeyEvent:url('JavaScript:alert('Return Key Pressed');')">

The following example intercepts the tab key and replaces it by the return key:

<META HTTP-Equiv="KeyCapture" Content="KeyValue:0x09; Remap:0x0D">

The following example displays an alert when any key is pressed but still allows that key to received by the browser component:

<META HTTP-Equiv="KeyCapture" Content="KeyValue:All; Dispatch:True; KeyEvent:url('JavaScript:alert('Key Pressed: %s');')">

The following example will not allow the return key to reach the browser but any other key will do so and display an alert:

<META HTTP-Equiv="KeyCapture" Content="KeyValue:0x0D; Dispatch:False; KeyEvent:url('JavaScript://ignore this');')">
<META HTTP-Equiv="KeyCapture" Content="KeyValue:All; Dispatch:True; KeyEvent:url('JavaScript:alert('Key Pressed: %s, key will be received by Browser.');')">

The following example shows how a previously mapped key (in this case the return key) can be unmapped using JavaScript. Note that specifying KeyValue:All and later unmapping a specific key will not unmap the key, follow the example above to achieve that effect:

<META HTTP-Equiv="KeyCapture" Content="KeyValue:0x0D; Dispatch:False; KeyEvent:url('JavaScript:alert('return pressed');')">
<script language=javascript>
function fnUnregisterReturnKey()
{
   //  Call this function to unmap the return key and allow it to reach the browser.
   keyCapture.keyValue = 0x0D;
   keyCapture.keyEvent = url('');
}
</script>

The following example disables all Accelerator Keys:

<META HTTP-Equiv="KeyCapture" Content="AccelerateKey:None">

The following example will navigate to the RhoElements start page when return is pressed:

<META HTTP-Equiv="KeyCapture" Content="HomeKeyValue:0x0D">

The following example will call a JavaScript function when the trigger is pressed or released:

<META HTTP-Equiv="KeyCapture" Content="TriggerEvent:url('JavaScript:alert('Trigger Event: %s');')">