Gestures Concepts

A gesture, or better, a mouse gesture, is a predefined sequence of mouse movements that can be interpreted by software. Once a gesture is identified the software can invoke a certain action. Gestures can be as simple as "The mouse moved to the left" or moderate, e.g. "The mouse drawed a clockwise circle" or very complicated.

Gestures are supported by various software application, e.g. the opera browser, firefox (plugin needed), Windows Tablet edition and various handsets as the iPhone or HTC Touch. However each application interpretes the gesture diferently, and cross browser support is lacking. Therefore a javascript implementation is very usefull, and this libray works in combination with the jQuery javascript toolkit.

To learn more about gestures, look at the examples below

The jGesture is written for the jQuery toolkit.

Nico Goeminne - nicogoeminne at gmail.com

Table of Contents

Audience

This Documentation is designed for people familiar with JavaScript programming and object-oriented programming concepts. You should also be familiar with the jQuery javascript toolkit

Introduction

Making Gestures

Although gestures can be "on" all the time, most implementations identify a gesture by a start and stop event, for example a gesture could be recoreded when a mousebutton is pressed and could be finished when the mousebutton is released. The jGesture Plugin only supports single stroke gestures.

Lets try to make a gesture. Click and hold (keep the button pressed) the green circle below and follow the blue traject, until you reached the red circle.

How Gestures are recognised

A mouse can move in any direction (360 degrees), but this huge number of possibilities is way to much to achieve useful results, therefore jGuseture detects only eight basic movements.

Click and hold the mouse button on the green circle, then release the mouse in one of the eight squares.

Gestures need a minimum movement to be detected, which is configurable in jGesture. Click and hold on the green circle and drag to one of the numbers. Make sure you release outside the gray circle, else your gesture will not be recognized.

Gestures have no specific origin point. Make a "top left" (drag your mouse to ward the top left) gesture, starting anywhere in the gray box. The "green" start circle from previous examples was just a guide.

Complex gestures

A more complex gesture consits out two or more mouse directions, for example the "L" gesture consit out a "bottom (6)" and a "right(4)" move. Make the "L" gesture in the area below. You can try making litle "L"s or big "L".

Advanced Image Search Example

The next example features a image search page (Yahoo Image Search powered). By default the "search box" is not visible because we want to make best use out of our screen real esate. The search box is hidden at the top of the page and can be made visible by using the "down" gesture. (it looks like you are pulling the search box on to the top of the screen). The focus is set to the input field and you may enter a single search word there (+hitting enter), e.g. "nature". The result images are shown in batches of 50 images. To browse to the next batch, you can use the "right" gesture, and to go back to the previous set of images you can use the "left" gesture.

Selecting one of the images causes them to enlarge. In this setting, you can use the "right" and "left" gestures in continues mode to scale the picture (see Settings and Zoom Example). To dismiss the enlarged picture and return to the result set make a "bottomright example".

Navigating trough the image search example should feel natural. The example can be found here.

Any suggestions are welcome at nicogoeminne at gmail.com

jGesture Examples

Each basic movement has a number and a name:

  1. topleft
  2. top
  3. topright
  4. right
  5. bottomright
  6. bottom
  7. bottomleft
  8. left

and each complex gesture with two moves has a name starting with the "firstbasicgesture" underscore "secondbasicgesture", e.g. the "L" gesture is named "bottom_right". Gestures with more than two basic moves are nameless (except for some useful default gestures).

The Basics

The jGesture plugin is ment to be used in conjunction with jQuery. If you are not familiar with this great toolkit you can find more information and tutorials here.

So lets get started. The code below adds a gesture handler to a gray div (box) called "info".

<html>
  <head>
    <script src="http://code.jquery.com/jquery-latest.js" type="text/javascript" ></script>
    <script src="http://jgesture.googlepages.com/jgesture-1.0.0.js" type="text/javascript" ></script>

    <script type="text/javascript">
  $(document).ready(function(){
    $("#info").gesture(
      function(gs){
        $(this).text("Gesture : " + gs.getName() + " : " + gs.moves);
      }
    );
  });
    </script>
  </head>
  <body>
    <div id="info" style="height:400px;width:400px;background-color:gray;color:white">make a gesture</div>
  </body>
</html>

First of all you need to include the jQuery and jGesture libraries. Then you can add a gesture handler to each jQuery-selectable item, by supplying the gesture function with a handler method. If a gesture is recorded on the target element, the handler method will be invoked, and the gesture is passed along.

The gesture has a name (if it is one of the default gestures, "unknown" otherwhise.) and a string field called "moves" with all recorded mouse moves. The default gestures are:

  • each gesture with maximum of two moves (as described above)
  • "rotateclockwise", when you draw a circle clockwise
  • "rotatecounterclockwise", when you draw a circle counter clockwise
  • "open", if you make a plus sign like the first example; the moves are "6*1*4", with * any number of moves
  • "close", if you make a "X" sign; the moves are "5*2*7", with * any number of moves, e.g. "54327"

The example can be found here

Animated Example

The next example binds the gesture handler to the html element, therefore the gestures will be recognized anywhere on the page. The handler uses the "close" gesture to hide the "info" div and the "open" gesture to show the div

<html>
  <head>
    <script src="http://code.jquery.com/jquery-latest.js" type="text/javascript" ></script>
    <script src="http://jgesture.googlepages.com/jgesture-1.0.0.js" type="text/javascript" ></script>

    <script type="text/javascript">
  $(document).ready(function(){
    $("html").gesture(
      function(gs){
        if (gs.getName() == "close") {
          $("#info").hide("slow");
        }
        if (gs.getName() == "open") {
          $("#info").show("slow");
        }
      }
    );
  });
    </script>
  </head>
  <body>
    <div id="info" style="height:400px;width:400px;background-color:gray;color:white">make a "close" gesture</div>
  </body>
</html>

The example can be found here

Settings

jGesture supports a number of settings. The defaults are shown in bold

  • startgesture: "mousedown" a string value identifying the gesture's start event (see jQuery events), such as "mousedown", "mouseup", ...
  • stopgesture: "mouseup" a string value identifying the gesture's stop event (see jQuery events), such as "mousedown", "mouseup", ...
  • mindistance: 10 a numeric value indicating the minimum pixel mouse move distance in order for the mouse move to be recoginsed
  • continuesmode: false a boolean value, if enabeled every new (direction) basic mouse move will cause the gesture's event handler to be called, hence the handler will be called before the gesture stop event.
  • repeat: false a boolean value, if enabeled every basic mouse move will be recorded, inclusive subsequent mouse movements in the same directions
  • disablecontextmenu: true a boolean value, if enabeled, the browser's context menu will be surpressed.
  • button: "012" a string value, if the startgesture event supports button numbers, only the numbers which occur in the button setting triger the start of the gesture. E.g use "0" for left mouse button, "01" for left and middle mouse button or "2" for right mouse button.

The following example use subsequent (continues and repeated) "right" and "left" gestures to zoom the width of the zoom-div. You need to jgesture-1.0.1.js in your script tag. The zoom example can be found here

<html>
  <head>
    <style>
      html, body {
       height:100%;
       width:100%;
       margin: 0;
      }

      #zoom{
       height:100%;
       width:50%;
       margin: auto;
       background-color: gray;
       color: white;
      }

    </style>

    <script src="http://code.jquery.com/jquery-latest.js" type="text/javascript" ></script>
    <script src="http://jgesture.googlepages.com/jgesture-1.0.1.js" type="text/javascript" ></script>

    <script type="text/javascript">
  var level = 50;

  $(document).ready(function(){
    $("html").gesture(
      function(gs){
        if (gs.getName() == "right") {
          level += 10;
          level = (level > 100)? 100: level;
          var set = level + "%";
          $("#zoom").stop();
          $("#zoom").animate({ width: set}, "slow");
        }
        if(gs.getName() == "left") {
          level -= 10;
          level = (level < 0)? 0: level;
          var set = level + "%";
          $("#zoom").stop();
          $("#zoom").animate({ width: set}, "slow" );
        }
      }, {repeat: true, continuesmode: true, mindistance:20}
    );
  });
    </script>
    </head>
  <body>
    <div id="zoom" >Continues example, keep your mouse pressed while making a "right" gesture to zoom in or a "left" gesture to zoom out. Notice that each subsequent mouse move is recognised and the gesture's handler is invoked.<div style="height:1px;width:1px;bootom:0px;right:0px;"></div></div>
  </body>
</html>

Right, Middle and Left Mouse Clicks

You'll notice that all examples using the "mousedown" as a start gesture work with both right, middle or left clicks. You'll often want to limit that behavior to only the middle or the right button. Therefore, as of version 1.0.3 you can set to which buttons the startgesture setting should listen, if of course the startgesture event supports button numbers, otherwhise the setting is ignored. For example use "0" for left mouse button, "01" for left and middle mouse button or "2" for right mouse button. Here is the zoom3 example, it will only react to right button clicks (the browser's context menu is also disabled, see below).

Disabling the Browser's Context Menu

Often you'd want to bind the start and stop of a gesture to the right mouse button click, however this causes the browser's context menu to pop up. As of version 1.0.2 the context menu is disabled on elements bound to a gesture. Here is the zoom2 example with using version 1.0.2, you can now use the right button and it will not cause the context menu to appear in contrast to the previous zoom example.

FAQ

What is the license for the jGesture Plugin?

The jGesture Plugin is licensed under Apache License Version 2.0

Change Log

API v1.0.0

  • Include "http://jgesture.googlepages.com/jgesture-1.0.0.js" in your script tag

API v1.0.1

  • There is now support for continues gestures
  • Include "http://jgesture.googlepages.com/jgesture-1.0.1.js" in your script tag

API v1.0.2

  • Version 1.0.2 disables the context menu on the element which is bound to a gesture
  • Include "http://jgesture.googlepages.com/jgesture-1.0.2.js" in your script tag

API v1.0.3

  • Version 1.0.3 enables the distinction between left, middle and right mouse buttons
  • Include "http://jgesture.googlepages.com/jgesture-1.0.3.js" in your script tag