Gestures

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 gestures: Discrete and Continuous gestures. In contrast to continuous gestures, discrete gestures don't have any change events. Rather, the end event is the only one that gets sent to the view.

Usage

While you wouldn't use SC.Gesture directly, all its subclasses implement the same API. For example, to implement pinch on a view, you implement one or more of the pinch events. For example:

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

  pinchChange: function(recognizer, evt) {
    var scale = recognizer.get('scale');
    this.$().css('scale',function(index, value) {
      return recognizer.get('scale') * value
    });
  },

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

  pinchCancel: function(recognizer, evt) {
    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.

Customizing Gesture Recognizers

Some of the gesture recognizers include properties that can be customized by the user for a specific instance of a view. For example, a pan gesture defaults to being a one-finger gesture, but in some scenarios, it must be defined as a two-finger gesture. In that case, you can override defaults by specifying an Options hash.

var myView = SC.View.create({
  panOptions: {
    numberOfRequiredTouches: 2
  }
});      

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 access the length 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 Start, Change nor Cancel 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.

Discrete gestures use the shouldEnd callback to either accept or decline the gesture event. If it is declined, then the gesture will enter a Cancelled state.