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
Gestures can call the following methods on their views:
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.SwipeGesturetriggers this after the swipe has moved a minimum amount—40px by default.
[gestureName]Start(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(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(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(args...): called when a gesture ends. A swipe would end when the user lifts their finger.
Gestures start receiving events when their view—usually mixing in
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
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.
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.
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
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
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:
YESwhen the touch is—or is likely enough to be that you want your gesture to have exclusive control over the touch. You usually do not perform much gesture logic here—instead, you save it for
touchStart, which will get called after you return YES from this method.
YESto accept control of the touch. If you do not return YES, your gesture will not receive
touchEndevents. At this point, you may (or may not) wish to tell the view that the gesture has started by using the start(args...) method.
touchesDragged: Use this as you would use it in an
SC.Viewto track the touches assigned to the gesture. At this point, you might want to tell the view that the gesture has updated by using the change(args...) method.
touchEnd: Again, use this like you would in an
SC.Viewto track when touches assigned to the gesture have ended. This is also a potential time to alert the view that the gesture has ended, by using the end(args...) method. Further, this may also be the time to "trigger" the gesture.
Defined in: gesture.js