Class: SC.Gesture

An SC.Gesture analyzes SC.Touch objects and determines if they are part of a gesture. If they are, SC.Gestures keep the views that own them up-to-date as that gesture progresses, informing it when it starts, when some aspect of it changes, when it ends, and—for convenience—when it is considered to have been "triggered".

Gestures can call the following methods on their views:

Gesture Lifecycle

Gestures start receiving events when their view—usually mixing in SC.Gesturable—tells it about activities with "unassigned" touches. "Unassigned" touches are touches that have not yet been assigned to a gesture.

The touch becomes "assigned" when the gesture's touchIsInGesture method returns YES. When a touch is assigned to a gesture, the gesture becomes the touch's touch responder; this means that it will receive a touchStart event (to which it must return YES), and then, all further touch events will be sent directly to the gesture—the gesture's view will not receive them at all.

At any point, the gesture may tell the view that it has started, ended, or changed. In addition, the gesture may tell the view it has been "triggered." A gesture is not necessarily "triggered" when it starts and ends; for instance, a swipe gesture might only be triggered if the swipe moves more than a specified amount. The ability to track when the gesture has been triggered allows views to easily handle the gesture as its own event, rather than as the individual events that are part of it.

If, at some point, the gesture must release the touch back (perhaps the gesture had thought the touch was a part of it, but turned out to be incorrect), the release(touch) method releases it back to the view.

Exclusivity

The concept described above gives the gestures a way to be either exclusive or inclusive as-needed: they can choose to take exclusive control of a touch if they think it is theirs, but if they are not sure, they can wait and see.

Status Object

It is a common need to track some data related to the touch, but without modifying the touch itself. SC.Gesture is able to keep track of simple hashes for you, mapping them to the SC.Touch object, so that you can maintain some state related to the touch.

For instance, you could set status.failed in touchesDragged, if a touch that you previously thought may have been part of the gesture turned out not to be, and then check for status.failed in touchIsInGesture, returning NO if present. This would cause the touch to never be considered for your gesture again.

touchIsInGesture is called with the status hash provided in the second argument. You may look up the status hash for a touch at any time by calling this.statusForTouch(touch).

Implementing a Gesture

To write a gesture, you would generally implement the following methods:

Defined in: gesture.js

Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:20 GMT-0600 (CST)