Warning Older Docs! - You are viewing documentation for a previous released version of RhoMobile Suite.

Gesture Module

The Gesture Module is used to define touch screen. Check the gestures overview page for more detail on different types of gestures.

Syntax

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", ...}

Methods

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

Parameters

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

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.

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.

Remarks

Gesture Notes

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.

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

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.

Finger Scrolling

Gestures are not compatible with Finger Scrolling

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 sensitivity 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. Diagnostics are not available for Tilt and Shake gestures.

Requirements

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.

HTML/JavaScript Examples

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> 
Back to Top