Gesture Meta Tag

PocketBrowser 3.x API

The Gesture Meta Tag is used to define and capture gestures drawn on a touch-sensitive screen. Multiple gestures can be defined for capture on a single page. Zebra recommends defining no more than five gestures per page to avoid performance issues. Note: Not supported on Windows CE if debug buttons are enabled in the Config.xml file of an Enterprise Browser app.

There are three types of screen gestures:

Linear – straight-line movements on the screen Circle – full or partially circular movements on the screen Hold – when the screen is touched and held

Gesture (META Tag) Syntax
<META HTTP-Equiv="Gesture" content="[method / parameter>
<META HTTP-Equiv="Gesture" contents="Detected:url('[jsFunction | url]')">


Items listed in this section indicate methods or, in some cases, indicate parameters which will be retrieved.

Name Description
Default Value
Create Creates the previously defined gesture. Must be the last tag when creating a gesture. N/A
Copy methods template to clipboard: Copy META Tag template to clipboard META Tags Copy Javascript template to clipboard Javascript

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

Name Possible Values Description
Default Value
Type:[Value] Linear, Circle, Hold Specifies the type of gesture being created. Must be the first tag when creating a gesture. None
ID:[Value] Any string ID used to identify gesture when detected. Depends on gesture type and preset used, if any. See remarks.
Preset:[Value] Depends on gesture type. See remarks. Name of predefined set of parameter values. Depends on gesture type. See remarks.
Diagnostics:[Value] TRUE, FALSE Enables drawing of diagnostic information to provide guidance showing whether or not the gesture will be detected. Note that by their very nature Diagnostics are not designed to be seen by the user. FALSE
LINEAR GESTURE PARAMETERS
Start-X, Start-Y:[Value] 0 to 10000 Starting point of gesture. 10% of screen width, 50% of screen height.
End-X, End-Y:[Value] 0 to 10000 End point of gesture. 90% of screen width, 50% of screen height.
Tolerance:[Value] 0 to 10000 How far (in pixels) the mouse track can vary from the gesture path. 25% of screen height.
Sensitivity:[Value] 0 to 100 Percentage of gesture path which mouse track must cover. Rounds down if this results in a non-whole number of regions. 50
Skew:[Value] 0 to 90 Maximum angle which straight line through mouse track can make to the gesture path. 20
Deviation:[Value] 0 to 100 Maximum deviation of mouse track from a straight line. 20
Region-Width:[Value] 0 to 10000 Width of regions into which gesture path is divided. Setting very small (e.g. 1) or large (e.g. equal to the gesture line length) values is allowed but may lead to unexpected results. 10% of screen width.
CIRCLE GESTURE PARAMETERS
Center-X, Center-Y:[Value] -10000 to 10000 Center of gesture. Center of screen.
Radius:[Value] 1 to 10000 Radius (in pixels) of gesture. 33% of screen width or height, whichever is smaller.
Start:[Value] 0 to 10000 Starting angle of gesture in degrees. Angles are measured clockwise from 3 o'clock position. 0
End:[Value] 0 to 10000 Ending angle of gesture in degrees. Angles are measured clockwise from 3 o'clock position. 180
Tolerance:[Value] 0 to 10000 How far (in pixels) the mouse track can vary from the gesture path. 16% of screen width.
Sensitivity:[Value] 0 to 100 Percentage of gesture path which mouse track must cover. Rounds down if this results in a non-whole number of regions. 50
HOLD GESTURE PARAMETERS
Center-X, Center-Y:[Value] -10000 to 10000 Center of gesture. Center of screen.
Radius:[Value] 1 to 10000 Radius (in pixels) of gesture. 25% of screen width or height, whichever is smaller.
Delay:[Value] >=0 Time (in milliseconds) that screen must be touched within gesture before first detected. 1000
Interval:[Value] >=0 Time (in milliseconds) between subsequent detections while screen continues to be touched. Zero means no further detections. This parameter is ignored if the detection event is not set to a Javascript function. 0
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');"


Detected

ID Name Description
1 ID The ID string of the detected gesture.
2 Count The number of times a hold gesture has been detected for a single press of the screen. Returns zero when the screen touch stops. Only applies to hold gestures.
Copy this return value template to clipboard: Copy META Tag template to clipboard META Tags Copy Javascript template to clipboard Javascript



Create two gestures: a default left to right gesture with ID 'swipe', and a hold gesture at the top left of the screen which will fire one time after 500 milliseconds with ID 'press'. The Javascript function onGesture() is called when either gesture is detected.

<META HTTP-Equiv="gesture" Content="type:linear">
<META HTTP-Equiv="gesture" Content="id:swipe">
<META HTTP-Equiv="gesture" Content="create">
<META HTTP-Equiv="gesture" Content="type:hold">
<META HTTP-Equiv="gesture" Content="center-x:60">
<META HTTP-Equiv="gesture" Content="center-y:60">
<META HTTP-Equiv="gesture" Content="radius:60">
<META HTTP-Equiv="gesture" Content="delay:500">
<META HTTP-Equiv="gesture" Content="interval:0">
<META HTTP-Equiv="gesture" Content="id:press">
<META HTTP-Equiv="gesture" Content="create">
<META HTTP-Equiv="gesture-detected" Content="url('Javascript:onGesture('%s','%s');')">
Copy example to clipboard Copy example to clipboard
Presets and IDs
The 'preset' tag is used to specify one of the preset values below. When a gesture definition is started using the 'type' tag its parameters are initially set to the preset shown as default. When a preset is specified for a gesture, including when it is first created, its ID is set to [gesture name]-[default preset name]. E.g. a new linear gesture will have the ID 'linear-left-right'. This can be replaced (as can any preset value) by a subsequent parameter tag.
GESTURE          POSSIBLE VALUES                                         DEFAULT
Linear           left-right, right-left, top-bottom, bottom-top          left-right
Circle           happy*, sad*                                            happy
Hold             center                                                  center
* Meanings of Presets
"Happy" means a 180 degree semi-circle, clockwise from the 3 o'clock position. "Sad" means a 180 degree semi-circle, clockwise from the 9 o'clock position.

Maximum Gesture Size
There is no formal maximum size for a gesture, for example a circle gesture could require the user to move several times round the circle. However if the user draws such a gesture very slowly it's possible that too many stylus move points could be generated, and the gesture wouldn't be detected. The plugin has been tested with a circle gesture from 0 to 720 degrees and taking approximately 6 seconds to draw without problem.

Common Pitfalls
Do not use alert boxes within the Gesture-Detected Callback, doing so will steal focus from the gesture region.

Out-of-range Values
Any parameter values out of the allowed range will be limited to the nearest allowed value. E.g. giving a sensitivy greater than 100 will use 100. Numeric parameters given as text will be treated as zero.

Diagnostics
Note that diagnostics exist only for the purpose of understanding and evaluating the various parameters. They should not be enabled in the release version of the code. They may also not display correctly in every circumstance, e.g. when scrolling, or for certain sets of parameters, e.g. for nearly vertical linear gestures.


Supported Platforms Windows CE, Windows Mobile
Persistence This tag will only persist on the current page.
Min. Requirements Linear, Circle and Hold gestures require a touch screen.