Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Easy JavaScript gesture recognition for iphone and ipad.
branch: master

This branch is 29 commits behind plainview:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
README
index.html
jester.js

README

////////////
// 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.
Something went wrong with that request. Please try again.