gesture.md

Base class for all gesture recognizers. Handles low-level touch and state management, and provides some utility methods and some required methods all gesture recognizers are expected to implement.

Overview

Gestures coalesce multiple touch events to a single higher-level gesture event. For example, a tap gesture recognizer takes information about a touchstart event, a few touchmove events, and a touchend event and uses some heuristics to decide whether or not that sequence of events qualifies as a tap event. If it does, then it will notify the view of the higher-level tap events.

Gesture events follow the format:

• [GESTURE_NAME]Start - Sent when a gesture has gathered enough information to begin tracking the gesture

• [GESTURE_NAME]Change - Sent when a gesture has already started and has received touchmove events that cause its state to change

• [GESTURE_NAME]End - Sent when a touchend event is received and the gesture recognizer decides that the gesture is finished.

• [GESTURE_NAME]Cancel - Sent when a touchcancel event is received.

There are two types of gesturess: Discrete and Continuous gestures. In contrast to continuous gestures, discrete gestures don't have any change events. Rather, the start and end events are the only one that gets sent.

Usage

While you wouldn't use SC.Gesture directly, all its subclasses have the same API. For example, to implement pinch on a view, you implement pinchChange and optionally pinchStart, pinchEnd and pinchCancel.

var myView = SC.View.create({
  pinchStart: function(recognizer) {
    this.$().css('background','red');
  },

  pinchChange: function(recognizer) {
    var scale = recognizer.get('scale');
    this.$().css('-webkit-transform','scale3d('+scale+','+scale+',1)');
  },

  pinchEnd: function(recognizer) {
    this.$().css('background','blue');
  },

  pinchCancel: function(recognizer) {
    this.$().css('background','blue');
  }
});

pinchStart(), pinchEnd() and pinchCancel() will only get called once per gesture, but pinchChange() will get called repeatedly called every time one of the touches moves.

Creating Custom Gesture Recognizers

SC.Gesture also defines an API which its subclasses can implement to build custom gestures. The methods are:

• didBecomePossible - Called when a gesture enters a possible state. This means the gesture recognizer has accepted enough touches to match the number of required touches. You would usually initialize your state in this callback.

• eventWasRejected - Called if a view returns false from a gesture event. This callback allows you to reset internal state if the user rejects an event.

• shouldBegin - Allows a gesture to block itself from entering a began state. This callback will continuously be called as touches move until it begins.

• shouldEnd - Allows a gesture to block itself from entering an ended state. This callback gets called whenever a tracked touch gets a touchEnd event.

• didBegin - Called when the gesture enters a began state. Called before the view receives the Start event.

• didChange - Called when the gesture enters a began state, and when one of the touches moves. Called before the view receives the Change event.

• didEnd - Called when the gesture enters an ended state. Called before the view receives the End event.

• didCancel - Called when the gesture enters a cancelled state. Called before the view receives the Cancel event.

In all the callbacks, you can use the touches protected property to access the touches hash. The touches hash is keyed on the identifiers of the touches, and the values are the jQuery.Event objects.

You can also use the numberOfActiveTouches property to inspect how many touches are active, this is mostly useful in shouldBegin since every other callback can assume that there are as many active touches as specified in the numberOfRequiredTouches property.

Discrete vs Continuous Gestures

There are two main classes of gesture recognizers: Discrete and Continuous gestures. Discrete gestures do not get Change events sent, since they represent a single, instantaneous event, rather than a continuous motion. If you are implementing your own discrete gesture recognizer, you must set the isDiscreteGesture property to yes, and SC.Gesture will adapt its behavior.