The Gesture Module is used to define touch screen. Check the gestures overview page for more detail on different types of gestures.
| gesture (Module) <META> Syntax |
|---|
<META HTTP-Equiv="Gesture" content="[method / parameter]"> |
<META HTTP-Equiv="Gesture" contents="Detected:url('[jsFunction | url]')"> |
| Gesture JavaScript Object Syntax: |
|---|
| By default the JavaScript Object 'gesture' will exist on the current page and can be used to interact directly with the gesture. |
To Invoke gesture methods via JavaScript use the following syntax: gesture.method();
e.g. gesture.create(); |
To Set gesture parameters via JavaScript use the following syntax: gesture.parameter = 'value'; remembering to enclose your value in quotes where appropriate.
e.g. gesture.type = 'value'; |
To Set gesture return events via JavaScript use the following syntax: gesture.event = JavaScript Function;
e.g. gesture.detected = 'doFunction(%json)'; For more details on the event syntax and parameters see the Retrieval Events page. |
To set multiple EMML parameters / events on a single line use the following syntax: gesture.setEMML("[Your EMML Tags]");
e.g. gesture.setEMML("type:value;detected:url('JavaScript:doFunction(%json)');create"); |
| Gesture Ruby Object Syntax: |
|---|
| By default the Ruby Object 'Gesture' will exist on the current page and can be used to interact directly with the Gesture. All Methods, Parameters and Events are the same as JavaScript, however, notice 'Gesture' needs to start with an uppercase letter. Another difference in Ruby is that methods do not end in '()' |
|
To Invoke Gesture methods via Ruby use the following syntax: Gesture.method()
e.g. Gesture.create |
To Set Gesture parameters via Ruby use the following syntax: Gesture.parameter = 'value' remembering to enclose your value in quotes where appropriate.
e.g. Gesture.type = 'value' |
To Set Gesture return events via Ruby use the following syntax: Gesture.event = url_for(:action => :event_callback)
e.g. Gesture.detected = url_for(:action => :gesture_event_callback) For more details on the event syntax and parameters see the Retrieval Events page. To access the event parameters in a Ruby callback function, you reference the @params object within the callback function. This object is simply a ruby hash {"parameter1 name" => "parameter1 value", "parameter2 name" => "parameter2 value", ...} |
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 |
| delete | Deletes the gesture last defined by the ID property. See example. | N/A |
Items listed in this section indicate parameters, or attributes which can be set.
| Name | Possible Values | Description | Default Value |
|---|---|---|---|
| type:[Value] | Linear, Circle, Hold, Tilt and Shake | 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 |
| startX:[Value] | 0 to 10000 | Linear Gestures: Starting point of gesture. | 10% of screen width. |
| startY:[Value] | 0 to 10000 | Linear Gestures: Starting point of gesture. | 50% of screen height. |
| endX:[Value] | 0 to 10000 | Linear Gestures: End point of gesture. | 90% of screen width. |
| endY:[Value] | 0 to 10000 | Linear Gestures: End point of gesture. | 50% of screen height. |
| skew:[Value] | 0 to 90 | Linear Gestures: Maximum angle which straight line through mouse track can make to the gesture path. | 20 |
| deviation:[Value] | 0 to 100 | Linear Gestures: Maximum deviation of mouse track from a straight line. | 20 |
| regionWidth:[Value] | 0 to 10000 | Linear Gestures: 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. |
| centerX:[Value] | -10000 to 10000 | Circle & Hold Gestures: Center of gesture. | Center of screen. |
| centerY:[Value] | -10000 to 10000 | Circle & Hold Gestures: Center of gesture. | Center of screen. |
| radius:[Value] | 1 to 10000 | Circle & Hold Gestures: Radius (in pixels) of gesture. | 33% of screen width or height, whichever is smaller. |
| start:[Value] | 0 to 10000 | Circle Gestures: Starting angle of gesture in degrees. Angles are measured clockwise from 3 o'clock position. | 0 |
| end:[Value] | 0 to 10000 | Circle Gestures: Ending angle of gesture in degrees. Angles are measured clockwise from 3 o'clock position. | 180 |
| tolerance:[Value] | 0 to 10000 | Linear & Circle Gestures: How far (in pixels) the mouse track can vary from the gesture path. | Linear: 25% of screen height. Circle: 16% of screen width. |
| sensitivity:[Value] | 0 to 100 | Linear & Circle Gestures: Percentage of gesture path which mouse track must cover. Rounds down if this results in a non-whole number of regions. | 50 |
| delay:[Value] | >=0 | Hold Gestures: Time (in milliseconds) that screen must be touched within gesture before first detected. | 1000 |
| interval:[Value] | >=0 | Hold Gestures: 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 navigate to a new page. | 0 |
| TargetX:[Value] | -90 to 90 | Tilt Gestures: Target orientation of device on X-axis | 0 |
| TargetY:[Value] | -90 to 90 | Tilt Gestures: Target orientation of device on Y-axis | 0 |
| TargetZ:[Value] | -90 to 90 | Tilt Gestures: Target orientation of device on Z-axis | 90 |
| TiltTolerance:[Value] | 0 to 90 | Tilt Gestures: How close the device must be to the target orientation. | 10 |
| Hysteresis:[Value] | 0 to 90 | Tilt Gestures: How far the device must move away from the target orientation before the gesture can be detected again. | 10 |
| Threshold:[Value] | 0 to 1000 | Shake Gestures: How vigorously the device must be shaken. The smaller the value the more vigorous. | 500 |
| Quiet:[Value] | >=0 | Shake Gestures: Time (in milliseconds) that the device must be still before another shake gesture can be detected. | 1000 |
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.
| 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. |
Depending on your device configuration you may find it very difficult to perform a gesture without performing any scrolling, particularly within the Internet Explorer engine. If you find your gestures disappear because you have accidentally scrolled, you must tap the screen to make them return.
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 Tilt face-up (0, 0, 90), face-down (0, 0, -90), face-up upright (0, 90, 0), turn-down (0, -90, 0), turn-left (90, 0, 0), turn-right (-90, 0, 0) Shake normal normal
“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.
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.
Gestures are not compatible with Finger Scrolling
Do not use alert boxes within the Gesture-Detected Callback, doing so will steal focus from the gesture region.
Any parameter values out of the allowed range will be limited to the nearest allowed value. E.g. giving a sensitivity greater than 100 will use 100. Numeric parameters given as text will be treated as zero.
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. Diagnostics are not available for Tilt and Shake gestures.
| RhoElements Version | 1.0.0 or above |
|---|---|
| Supported Devices | All supported devices. On Windows the tilt and shake gestures are supported only on MPA3.0 devices. |
| Minimum Requirements | Linear, Circle and Hold gestures require a touch screen. |
| Persistence | Transient - any changes made by changing parameters will be lost when navigating to a new page. |
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');')">
The following example deletes a gesture via a JavaScript function.
function deleteGesture(gestureID) { gesture.id = gestureID; gesture.delete(); }
Create 3D gestures: a tilt gesture that is called when the device is placed in upright position and a shake gesture. The JavaScript function onGesture() is called when either gesture is detected.
<META HTTP-Equiv="gesture" Content="type:tilt"> <META HTTP-Equiv="gesture" Content="id:swipe"> <META HTTP-Equiv="gesture" Content="create"> <META HTTP-Equiv="gesture" Content="type:shake"> <META HTTP-Equiv="gesture" Content="id:shake"> <META HTTP-Equiv="gesture" Content="create"> <META HTTP-Equiv="gesture-detected" Content="url('JavaScript:onGesture(%json);')"> <script type="text/javascript"> function onGesture(jsonObject) { var html = "<b>Gesture Detected: </b>" + jsonObject.id + ""; gestureOut.innerHTML=html; } </script> <DIV id="gestureOut">Gesture Output will appear here</div>