CoffeeTouch User's Manual

Configuration

Include CoffeeTouch.js in your web page and you're done. jQuery is not required. The functions are added directly to the Element object.

Use

In order to retrieve events from a DOM element you have to associate a gesture and a callback with the function onGesture.

$(“#myElement”).onGesture(“tap,tap”, function(event) {
    alert(“myElement has been taped with two fingers”)
});

onGesture(gestureName, callbackFunction):

This function is added to the Element’s prototype.

• gestureName: Designate the name of the gesture the element will be listening

• callbackFunction(event): Function to execute when the gesture is done. The callback function is called with one argument which is the event information object which is described in details after.

Warning: If gestureName is set to all, then callbackFunction will be called with two arguments, the first will be the gesture name done on the DOM element, and the second one will be the event information object, as usual.

If you want to bind a gesture to multiple elements it is easily possible, you just have to do as follow :

• $('.myElements').onGesture(gestureName, callbackFunction) - the callback function will be bind to all elements that have the 'myElements' class

Naming System

A gesture is composed of one or more actions. Here is an exhaustive list of all action possible:

• tap - doubletap
• fixed - fixedend
• drag - up - right - down - left - dragend
• flick - flick:direction
• pinch - spread
• rotate - rotate:cw - rotate:ccw

As you can see, you can listen to gesture with more or less precision. If you listen a drag gesture, every move of a finger will execute your callback function. But if you listen to a “left” gesture, your callback function will be execute only if the finger is moving to the left.

Warning: Gesture names are separated by a single coma, but there is no blank space

Notice that order is considered in the gesture name

You juste have to compose single action. For example:

• up,up,up means that you are listening three fingers going up.
• up,down,up means that you are listening the first finger going up, the second going down, and the third going up.

Notice that for pinch, spread and rotation, you can specify the number of finger used by the user. For doing that, you just have to specify a keyword number before the gesture keyword. Do as follow:

three:pinch will trigger only when the pinch will be done with three fingers.

Fingers order

Fingers are ordered in the fingers array in the Western reading direction (left to right, up to down).

If the gesture seems to start horizontally, fingers will be ordered from left to right.

If the gesture seems to start vertically, fingers will be ordered from top to bottom.

Event Information Object

event:

• rotation: Rotation value in degrees
• scale: Scale factor between fingers (only defined for gestures with two or more fingers)
• nbFingers: Number of fingers for the gesture
• timeStart: Time when the gesture started
• timeElapsed: Time elapsed from the beginning of the gesture (in ms)
• fingers[nbFingers]: Each finger has its own informations.
• startX: Initial X position
• startY: Initial Y position
• x: Actual X position
• y: Actual Y position
• timeStart: Time when the finger has touched the screen
• timeElapsed: Time elapsed from the beginning of the touch (in ms)
• panX: Distance moved in X
• panY: Distance moved in Y
• speed: Speed of the finger
• gestureName: Name of the gesture (tap, doubletap, fixed or drag)
• dragDirection: Direction of the drag (if there is one) - up, down, righ or left

Other's function

unbindGesture(gestureName, callbackFunction):

This function is added to the Element’s prototype. Remove the callback associated with the gestureName passed in parameter if it exists.

makeGesture(gestureName):

This function is added to the Element’s prototype. Execute the callback associated with the gestureName if a gesture has been associated before.