Mixin: SC.Gesturable

Extends SC.ObjectMixinProtocol, SC.ResponderProtocol.

You can mix in SC.Gesturable to your views to add some support for recognizing gestures.

SproutCore views have built-in touch events. However, sometimes you may want to recognize gestures like tap, pinch, swipe, etc. This becomes tedious if you need to do this often, and more so if you need to check for multiple possible gestures on the same view.

SC.Gesturable allows you to define a collection of gestures (SC.Gesture objects) that your view should recognize. When a gesture is recognized, methods will be called on the view:

• gestureName: called when the gesture has occurred. This is useful for event-style gestures, where you aren't interested in when it starts or ends, but just that it has occurred. SC.SwipeGesture triggers this after the swipe has moved a minimum amount—40px by default.
• [gestureName]Start(gesture, args...): called when the gesture is first recognized. For instance, a swipe gesture may be recognized after the finger has moved a minimum distance in a horizontal.
• [gestureName]Changed(gesture, args...): called when some property of the gesture has changed. For instance, this may be called continuously as the user swipes as the swipe's distance changes.
• [gestureName]Cancelled(gesture, args...): called when a gesture, for one reason or another, is no longer recognized. For instance, a horizontal swipe gesture could cancel if the user moves too far in a vertical direction.
• [gestureName]End(gesture, args...): called when a gesture ends. A swipe would end when the user lifts their finger.

Each of these methods is passed the gesture instance, in addition to any arguments the gesture sends for your convenience. The default swipe gesture sends an SC.Touch instance, the swipe direction, and the distance the swipe has moved in that direction.

Using SC.Gesturable

To make your view recognize gestures, mix in Gesturable and add items to the 'gestures' property:

SC.View.extend(SC.Gesturable, {
  gestures: [SC.PinchGesture, 'mySwipeGesture'],

  // specifying as a string allows you to configure it:
  mySwipeGesture: SC.SwipeGesture.extend({
    direction: SC.SWIPE_VERTICAL,
    startDistance: 3,
    swipeDistance: 20
  }),

  // handle the swipe action
  swipe: function(touch, direction) {
    console.error("Swiped! In direction: " + direction);
  },

  swipeStart: function(touch, direction, delta) {
    console.error("Swipe started in direction: " + direction + "; dist: " + delta);
  },

  swipeChanged: function(touch, direction, delta) {
    console.error("Swipe continued in direction: " + direction + "; dist: " + delta);
  },

  swipeEnd: function(touch, direction, delta) {
    console.error("Completed swipe in direction: " + direction + "; dist: " + delta);
  }

})

Defined in: gesturable.js

Field Summary

Class Methods

• gestureLostInterest(gesture)
• gestureTouchCancelled(touch)
• gestureTouchEnd(touch)
• gestureTouchesDragged(evt, touches)
• gestureTouchStart(touch)
• initMixin()
• touchCancelled(touch)
• touchEnd(touch)
• touchesDragged(evt, touches)
• touchStart(touch)

gestures: [SC.PinchGesture, 'mySwipeGesture'],

// Specifying the Gesture by property name allows you to configure it.
mySwipeGesture: SC.SwipeGesture.extend({
  direction: SC.SWIPE_VERTICAL,
  startDistance: 3,
  swipeDistance: 20
}),