//////////// // Jester // ////////////

For the latest news and most up-to-date information, check the Jester GitHub Wiki! http://wiki.github.com/plainview/Jester/

0.0 - Intro 1.0 - Project Status 1.1 - Project Aims 1.2 - Project Todos 2.0 - How To Use 2.1 - Basic Syntax 2.2 - Handlers 2.3 - Options 3.0 - Bugs? Questions?

0.0 Intro

A small JavaScript library for easily recognising gestures on DOM elements on the iPhone and iPad.

1.0 Project Status

Jester works for Swipes, Flicks, Taps and Double Taps. Pinches should be added by the end of the week.

Examples of code can be seen at the bottom of this README in the "How to Use" section.

1.1 Project Aims

• Super easy gesture recognition on DOM Elements.
• Elegant syntax. I like jQuery's style so will go with a bastardisation of that for now.
• Library agnostic : must not rely on jQuery, Moo, Dojo etc. Pure JavaScript only.
• Open code base : The objects and interfaces used internally by Jester should be reasonably accessible without editing the core code.
• No selector engine : how you fetch DOM elements is none of Jester's business.
• No other bumf : this is all about gesture recognition and nothing else.

A basic example can be viewed in the index.html page. Boot it up on an iPhone, iPad or Simulator and swipe, flick, tap and doubletap on the black square.

This is very much a learning project. Mistakes will be made and enjoyed whole-heartedly.

1.2 Project Todos

• Pinch recognition.
• Clear and thorough documentation.
• Project website.

2.0 How to Use

Jester makes recognising gestures on DOM elements really easy. First you need to know how to get a DOM element, though. To get an element by its ID, use:

// will assign the element with an ID of "wrapper" to the variable el var el = document.getElementById("wrapper");

If you're using jQuery or another library which wraps elements in a custom object/interface, you need to get to the DOM element directly. In jQuery:

// will assign the element with an ID of "wrapper" to the variable el var el = $("#wrapper").get(0);

More examples with other libraries coming soon.

OK, on with the Jester information....

2.1 Basic Syntax

jester(element) .swipe(swipeHandler) // attach a handler to the element's swipe event .doubletap(dtHandler); // attach a handler to the element's doubletap event

2.2 Handlers

var handler = function(touchGroup, direction) { // handler code }

Handlers are passed a TouchGroup object which contains information about the gesture including touch position(s), changes in position, speed and acceleration. For swipe and flick events, a direction is also passed as a string (i.e. "left" or "right").

// Log the direction in which a gesture occured var whichDirection = function(touches, direction) { console.log("Swiped to the " + direction); };

// Log how far one of the touches in a gesture travelled var howFar = function(touches, direction) { var distanceTravelled = touches.touch(0).total.x(); console.log(distanceTravelled); };

// Attach the new handlers to some events jester(document.getElementById("wrapper")) .flick(whichDirection) .swipe(howFar);

2.3 Options

You can also pass Jester options which affect the way gestures are recognised:

jester(document.getElementById("wrapper"), { swipeDistance: 400, flickTime: 200 }) .swipe(handler1) .flick(handler2);

Currently supported Options are:

bubble Boolean Whether or not to bubble touch events performed on the element.

tapDistance Integer Maximum distance a finger is allowed to travel for a tap to be registered. tapTime Integer Maximum time a finger is allowed to have contact with the screen for a tap to be registered.

doubleTapTime Integer The maximum time between two taps to register as a double tap.

swipeDistance Integer The minimum distance a gesture must travel before a swipe is registered.

flickTime Integer The maximum length of time a gesture can last for it to be registered as a flick. flickDistance Integer The minimum distance a gesture must travel for it to be registered as a flick.

3.0 Bugs? Questions?

Jester is currently the work of me, Scott Seaward. My username on GitHub is plainview. Get in touch through GitHub if you have anything to say about Jester.