KeyCapture Meta Tag

PocketBrowser 3.x API

The KeyCapture Meta Tag is an action tag is used to intercept or override hardware keys, and is typically used to assign certain application functions to physical keys or other hardware buttons.

KeyCapture (META Tag) Syntax
<META HTTP-Equiv="KeyCapture" content="[parameter>
<META HTTP-Equiv="KeyCapture" content="KeyEvent:url('[jsFunction | url]')">

<META HTTP-Equiv="KeyCapture" content="TriggerEvent:url('[jsFunction | url]')">


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

Name Possible Values Description
Default Value
Dispatch:[Value] 'True' or 'False' After a key has been intercepted this parameter will determine whether or not it will still be received by the visual components. For example if you have focus in a text box and are intercepting keys set this to 'False' to avoid having the keys appear in the box. False
KeyValue:[Value] Hex virtual key value, or 'All' Specifies the key to be captured, e.g. 0x09 is Tab, 0x0D is return. Set this parameter to 'All' to capture all keys. The value of the received key is passed as a return value to the KeyEvent, this can be used to find the value of a specific key. See the remarks section for a list of keys which can not be captured. N/A
Remap:[Value] Hex virtual key value After a key has been captured it will be remapped and the new key and sent to PocketBrowser. This parameter must be set after the KeyValue parameter specifiying which key is being remapped. Note this parameter is incompatible with KeyValue:all or Dispatch:True, otherwise this would result in two keys being recevied. Also note thie parameter is incompatible with the KeyEvent as the two are mutually exclusive. N/A
AccelerateKey:[Value] 'None', 'All' and 'Norm' 'All' enables all accelerator keys for the browser to handle. 'None' disables all the accelerator keys and 'Norm' uses the default PocketBrowser settings for Accelerator Keys. See Remarks Norm
HomeKeyValue:[Value] Hex virtual key value, or 'Disabled' Specifies a key which, when pressed, will navigate to the start page as defined in the PocketBrowser configuration. Set to 'Disabled' to prevent this behaviour. Disabled
Copy parameters template to clipboard: Copy META Tag template to clipboard META Tags Copy Javascript template to clipboard Javascript

Modules return information back to their web pages via retrieval tags, for example the scanner has a retrieval tag called 'DecodeEvent' which is called whenever it decodes a barcode. To register to receive a retrieval tag call the module as follows:

<META HTTP-Equiv="[Module]" content="[RetrievalTag]:url('[URI]')">
So to register to retrieve the Scanner's DecodeEvent the following syntax would be used:
<META HTTP-Equiv="Scanner" content="DecodeEvent:url('Javascript:doScan('%6', '%s', %3, '%2');')">

Retrieval tags return information by replacing the text in place holders, defined as '%s' or '%<number>'. Each place holder represents 1 return value with '%s' being populated sequentially or '%<number>' providing direct acces to the desired value.

If the content for the Scanner's DecodeEvent is:

"url('Javascript:doScan('%6', '%s', %3, '%2');')"

The function would be called as follows:
"Javascript:doScan('Decode', '5449000053879', 0x35, 'SCN:EAN13');"


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.

ID Name Description
1 Key Value The internal representation of the key expressed in decimal, e.g. 13 is the return key
Copy this return value template to clipboard: Copy META Tag template to clipboard META Tags Copy Javascript template to clipboard Javascript


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.

ID Name Description
1 Trigger Flag The combination of the triggers pressed and the state of the triggers
Copy this return value template to clipboard: Copy META Tag template to clipboard META Tags Copy Javascript template to clipboard Javascript



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');')">
Copy example to clipboard Copy example to clipboard

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');')">
Copy example to clipboard Copy example to clipboard

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

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

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');')">
Copy example to clipboard Copy example to clipboard

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.');')">
Copy example to clipboard Copy example to clipboard

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.
var Generic = new ActiveXObject("PocketBrowser.Generic");
Generic.InvokeMetaFunction("KeyCapture", "KeyValue:0x0D; KeyEvent:url('')");
}
</script>
Copy example to clipboard Copy example to clipboard

The following example disables all Accelerator Keys:

<META HTTP-Equiv="KeyCapture" Content="AccelerateKey:None">
Copy example to clipboard Copy example to clipboard

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

<META HTTP-Equiv="KeyCapture" Content="HomeKeyValue:0x0D">
Copy example to clipboard Copy example to clipboard

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');')">
Copy example to clipboard Copy example to clipboard
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.
Capturing Function Keys
Function keys can only be captured if they are enabled in the Configuration Settings and if they are not intercepted by the operating system prior to reaching PocketBrowser. One such example of OS interception is the F6 and F7 keys on the MC75 (non QWERTY) which are interpreted as volume up & volume down.

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 not applicable to Windows Mobile.
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 PocketBrowser 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.

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 14. In order to capture those two keys it is necessary to enable F12 and F14 in the Configuration Settings.


Supported Platforms Windows CE, Windows Mobile
Persistence AccelerateKey and HomeKeyValue are persistent, all other parameters only persist on the current page.
Min. Requirements None