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:

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

Field Detail

SC.Gesturable.acceptsMultitouch Boolean
Gestures need to understand multiple touches.
Default value:
true
See:
SC.View#acceptsMultitouch
SC.Gesturable.concatenatedProperties Array
Default value:
['gestures']
See:
SC.Object#concatenatedProperties
SC.Gesturable.gestures Array

The gestures that the view will support. This property must be set on the consumer of SC.Gesturable before it is initialized.

These gestures should be objects that extend the SC.Gesture class. You can use SproutCore's pre-built gestures or create your own. If you create your own, you can use a property name in the list of gestures to refer to the actual gesture class, similar to how the childViews array works. For example,

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
}),

Note that gestures is a concatenated property, which means that it will not be overwritten by subclasses. So for example, if the base class lists gestures as [SC.PinchGesture] and its subclass lists gestures as [SC.TapGesture], the actual gestures supported by the subclass will be [SC.PinchGesture,SC.TapGesture].

Default value:
null

Class Method Detail

gestureLostInterest(gesture)

Called by a gesture that has lost interest in the entire touch session, likely due to too much time having passed since gestureTouchStart or gestureTouchesDragged having been called.

Simply removes the gesture from the list of interested gestures and calls touchSessionCancelled on the gesture.

Parameters:
gesture
gestureTouchCancelled(touch)

Tells the gesture recognition system that an unassigned touch has cancelled.

This informs all of the gestures that the touch cancelled. The touch is an unassigned touch as, if it were assigned to a gesture, it would have been sent directly to the gesture, bypassing this view.

Parameters:
touch
gestureTouchEnd(touch)

Tells the gesture recognition system that an unassigned touch has ended.

This informs all of the gestures that the touch ended. The touch is an unassigned touch as, if it were assigned to a gesture, it would have been sent directly to the gesture, bypassing this view.

Parameters:
touch
gestureTouchesDragged(evt, touches)
Tells the gesture recognition system that touches have moved.
Parameters:
evt SC.Event
The touch event.
touches Array
The touches previously claimed by this view.
Returns:
void
gestureTouchStart(touch)

Tells the gesture recognizing system about a new touch. This notifies all gestures of a new touch session starting (if there were no previous touches) or notifies all interested gestures that a touch has been added.

As touches are added beyond the first touch, gestures may "lose interest" in the touch session. For example, a gesture may explicitly want only a single touch and if a second touch appears, the gesture may not want any further updates on this touch session (even if the second touch ends again).

Parameters:
touch SC.Touch
The touch that started.
Returns:
Boolean
Whether any gesture is interested in the touch or not.
initMixin()
When SC.Gesturable initializes, any gestures named on the view are instantiated.
See:
SC.ObjectMixinProtocol#initMixin
touchCancelled(touch)

Tells the gesture recognizing code about a touch cancelling.

If you override touchCancelled, you will need to call gestureTouchCancelled for any touches you called gestureTouchStart for in touchStart (if overridden).

Parameters:
touch SC.Touch
The touch that cancelled.
See:
SC.ResponderProtocol#touchCancelled
touchEnd(touch)

Tells the gesture recognizing code about a touch ending.

If you override touchEnd, you will need to call gestureTouchEnd for any touches you called gestureTouchStart for in touchStart (if overridden).

Parameters:
touch SC.Touch
The touch that ended.
See:
SC.ResponderProtocol#touchEnd
touchesDragged(evt, touches)

Tells the gesture recognizing code about touches moving.

If you override touchesDragged, you will need to call gestureTouchesDragged (at least for any touches you called gestureTouchStart for in touchStart) to allow the gesture system to update.

Parameters:
evt
touches
See:
SC.ResponderProtocol#touchesDragged
touchStart(touch)

Handles touch start by handing it to the gesture recognizing code.

If you override touchStart, you will need to call gestureTouchStart to give the gesture system control of the touch. You will continue to get events until if and when a gesture decides to take "possession" of a touch— at this point, you will get a [gestureName]Start event.

You do not have to call gestureTouchStart immediately; you can call it at any time. This allows you to avoid passing control until after you have determined your own touchStart, touchesDragged, and touchEnd methods are not going to handle it.

Parameters:
touch SC.Touch
The touch that started.
Returns:
Boolean
Whether the touch should be claimed by the view or not.
See:
SC.ResponderProtocol#touchStart
Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:20 GMT-0600 (CST)