sproutcore 1.11.0.rc3 → 1.11.0

data/lib/frameworks/sproutcore/frameworks/foundation/gestures/tap_gesture.js

@@ -0,0 +1,259 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2010 Strobe Inc. All rights reserved.
+// Author:    Peter Wagenet
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+sc_require("system/gesture");
+
+/**
+  ## What is a "tap"?
+
+  A tap is a touch that starts and ends in a short amount of time without moving along either axis.
+  A tap may consist of more than one touch, provided that the touches start and end together. The time
+  allowed for touches to start and end together is defined by `touchUnityDelay`.
+  Again, to be considered a tap, there should be very little movement of any touches on either axis
+  while still touching. The amount of movement allowed is defined by `tapWiggle`.
+
+  @class
+  @extends SC.Gesture
+*/
+SC.TapGesture = SC.Gesture.extend(
+/** @scope SC.TapGesture.prototype */{
+
+  /** @private The time that the first touch started at. */
+  _sc_firstTouchAddedAt: null,
+
+  /** @private The time that the first touch ended at. */
+  _sc_firstTouchEndedAt: null,
+
+  /** @private A flag used to track when the touch was long enough to register tapStart (and tapEnd). */
+  _sc_isTapping: false,
+
+  /** @private The number of touches in the current tap. */
+  _sc_numberOfTouches: 0,
+
+  /** @private A timer started after the first touch starts. */
+  _sc_tapStartTimer: null,
+
+  /**
+    @type String
+    @default "tap"
+    @readOnly
+  */
+  name: "tap",
+
+  /**
+    The amount of time in milliseconds between when the first touch starts and the last touch ends
+    that should be considered a short enough time to constitute a tap.
+
+    @type Number
+    @default 250
+  */
+  tapLengthDelay: 250,
+
+  /**
+    The amount of time in milliseconds after the first touch starts at which, *if the tap hasn't
+    ended in that time*, the `tapStart` event should trigger.
+
+    Because taps may be very short or because movement of the touch may invalidate a tap gesture
+    entirely, you generally won't want to update the state of the view immediately when a touch
+    starts.
+
+    @type Number
+    @default 150
+    */
+  tapStartDelay: 150,
+
+  /**
+    The number of pixels that a touch may move before it will no longer be considered a tap. If any
+    of the touches move more than this amount, the gesture will give up.
+
+    @type Number
+    @default 10
+  */
+  tapWiggle: 10,
+
+  /**
+    The number of milliseconds that touches must start and end together in in order to be considered a
+    tap. If the touches start too far apart in time or end too far apart in time based on this
+    value, the gesture will give up.
+
+    @type Number
+    @default 75
+  */
+  touchUnityDelay: 75,
+
+  /** @private Calculates the distance a touch has moved. */
+  _sc_calculateDragDistance: function (touch) {
+    return Math.sqrt(Math.pow(touch.pageX - touch.startX, 2) + Math.pow(touch.pageY - touch.startY, 2));
+  },
+
+  /** @private Cleans up the touch session. */
+  _sc_cleanUpTouchSession: function (wasCancelled) {
+    if (this._sc_isTapping) {
+      // Trigger the gesture, 'tapCancelled'.
+      if (wasCancelled) {
+        this.cancel();
+
+      // Trigger the gesture, 'tapEnd'.
+      } else {
+        this.end();
+      }
+
+      this._sc_isTapping = false;
+    }
+
+    // Clean up.
+    this._sc_tapStartTimer.invalidate();
+    this._sc_numberOfTouches = 0;
+    this._sc_tapStartTimer = this._sc_firstTouchAddedAt = this._sc_firstTouchEndedAt = null;
+  },
+
+  /** @private Triggers the tapStart event. Should *not* be reachable unless the tap is still valid. */
+  _sc_triggerTapStart: function () {
+      // Trigger the gesture, 'tapStart'.
+    this.start();
+
+    this._sc_isTapping = true;
+  },
+
+  /**
+    The tap gesture only remains interested in a touch session as long as none of the touches have
+    started too long after the first touch (value of `touchUnityDelay`). Once any touch has started
+    too late, the tap gesture gives up for the entire touch session and won't attempt to re-engage
+    (i.e. even if an extra touch "taps" cleanly in the same touch session, it won't trigger any
+    further tap callbacks).
+
+    @param {SC.Touch} touch The touch to be added to the session.
+    @param {Array} touchesInSession The touches already in the session.
+    @returns {Boolean} True as long as the new touch doesn't start too late after the first touch.
+    @see SC.Gesture#touchAddedToSession
+    */
+  touchAddedToSession: function (touch, touchesInSession) {
+    var stillInterestedInSession,
+        delay;
+
+    // If the new touch came in too late after the first touch was added.
+    delay = Date.now() - this._sc_firstTouchAddedAt;
+    stillInterestedInSession = delay < this.get('touchUnityDelay');
+
+    return stillInterestedInSession;
+  },
+
+  /**
+    If a touch cancels, the tap doesn't care and remains interested.
+
+    @param {SC.Touch} touch The touch to be removed from the session.
+    @param {Array} touchesInSession The touches in the session.
+    @returns {Boolean} True
+    @see SC.Gesture#touchCancelledInSession
+    */
+  touchCancelledInSession: function (touch, touchesInSession) {
+    return true;
+  },
+
+  /**
+    The tap gesture only remains interested in a touch session as long as none of the touches have
+    ended too long after the first touch ends (value of `touchUnityDelay`). Once any touch has ended
+    too late, the tap gesture gives up for the entire touch session and won't attempt to re-engage
+    (i.e. even if an extra touch "taps" cleanly in the same touch session, it won't trigger any
+    further tap callbacks).
+
+    @param {SC.Touch} touch The touch to be removed from the session.
+    @param {Array} touchesInSession The touches in the session.
+    @returns {Boolean} True if it is the first touch to end or a subsequent touch that ends not too long after the first touch ended.
+    @see SC.Gesture#touchEndedInSession
+  */
+  touchEndedInSession: function (touch, touchesInSession) {
+    var stillInterestedInSession;
+
+    // Increment the number of touches in the tap.
+    this._sc_numberOfTouches += 1;
+
+    // If it's the first touch to end, remain interested unless tapLengthDelay has passed.
+    if (this._sc_firstTouchEndedAt === null) {
+      this._sc_firstTouchEndedAt = Date.now();
+      stillInterestedInSession = this._sc_firstTouchEndedAt - this._sc_firstTouchAddedAt < this.get('tapLengthDelay');
+
+    // If the touch ended too late after the first touch ended, give up entirely.
+    } else {
+      stillInterestedInSession = Date.now() - this._sc_firstTouchEndedAt < this.get('touchUnityDelay');
+    }
+
+    return stillInterestedInSession;
+  },
+
+  /**
+    The tap gesture only remains interested in a touch session as long as none of the touches have
+    moved too far (value of `tapWiggle`). Once any touch has moved too far, the tap gesture gives
+    up for the entire touch session and won't attempt to re-engage (i.e. even if an extra touch
+    "taps" cleanly in the same touch session, it won't trigger any further tap callbacks).
+
+    @param {Array} touchesInSession All touches in the session.
+    @returns {Boolean} True as long as none of the touches have moved too far to be a clean tap.
+    @see SC.Gesture#touchesMovedInSession
+    */
+  touchesMovedInSession: function (touchesInSession) {
+    var stillInterestedInSession = true;
+
+    for (var i = 0, len = touchesInSession.length; i < len; i++) {
+      var touch = touchesInSession[i],
+          movedTooFar = this._sc_calculateDragDistance(touch) > this.get('tapWiggle');
+
+      // If any touch has gone too far, we don't want to consider any further tap actions for this
+      // session. No need to continue.
+      if (movedTooFar) {
+        stillInterestedInSession = false;
+        break;
+      }
+    }
+
+    return stillInterestedInSession;
+  },
+
+  /**
+    Cleans up all touch session variables.
+
+    @returns {void}
+    @see SC.Gesture#touchSessionCancelled
+    */
+  touchSessionCancelled: function () {
+    // Clean up (will fire tapCancelled if _sc_isTapping is true).
+    this._sc_cleanUpTouchSession(true);
+  },
+
+  /**
+    Cleans up all touch session variables and triggers the gesture.
+
+    @returns {void}
+    @see SC.Gesture#touchSessionEnded
+    */
+  touchSessionEnded: function () {
+    // Trigger the gesture, 'tap'.
+    this.trigger(this._sc_numberOfTouches);
+
+    // Clean up (will fire tapEnd if _sc_isTapping is true).
+    this._sc_cleanUpTouchSession(false);
+  },
+
+  /**
+    Registers when the first touch started.
+
+    @param {SC.Touch} touch The touch that started the session.
+    @returns {void}
+    @see SC.Gesture#touchSessionStarted
+    */
+  touchSessionStarted: function (touch) {
+    // Initialize.
+    this._sc_firstTouchAddedAt = Date.now();
+
+    this._sc_tapStartTimer = SC.Timer.schedule({
+      target: this,
+      action: this._sc_triggerTapStart,
+      interval: this.get('tapStartDelay')
+    });
+  }
+
+});

data/lib/frameworks/sproutcore/frameworks/foundation/mixins/gesturable.js

@@ -8,8 +8,7 @@
 /**
   @namespace
 
-  You can mix in SC.Gesturable to your views to add some support for recognizing
-  gestures.
+  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
@@ -76,9 +75,33 @@
       })
 
   @extends SC.ObjectMixinProtocol
+  @extends SC.ResponderProtocol
 */
 SC.Gesturable = {
 
+  /** @private An array of all gestures currently interested in the touch session.
+
+    @type Array
+    @default null
+  */
+  _sc_interestedGestures: null,
+
+  /** @private An array of the touches that are currently active in a touch session.
+
+    @type Array
+    @default null
+  */
+  _sc_touchesInSession: null,
+
+  /**
+    Gestures need to understand multiple touches.
+
+    @type Boolean
+    @default true
+    @see SC.View#acceptsMultitouch
+  */
+  acceptsMultitouch: true,
+
   /**
     @type Array
     @default ['gestures']
@@ -114,6 +137,59 @@ SC.Gesturable = {
   */
   gestures: null,
 
+  /** @private Shared method for finishing a touch.
+
+    @param {SC.Touch} touch The touch that ended or cancelled.
+    @param {Boolean} wasCancelled Whether the touch was cancelled or not (i.e. ended normally).
+  */
+  _sc_gestureTouchFinish: function (touch, wasCancelled) {
+    var touchesInSession = this._sc_touchesInSession,
+        touchIndexInSession = touchesInSession.indexOf(touch);
+
+    // Decrement our list of touches that are being acted upon.
+    touchesInSession.replace(touchIndexInSession, 1);
+
+    var gestures = this._sc_interestedGestures,
+        idx,
+        gesture;
+
+    // Loop through the gestures in reverse, as the list may be mutated.
+    for (idx = gestures.length - 1; idx >= 0; idx--) {
+      var isInterested;
+
+      gesture = gestures[idx];
+
+      if (wasCancelled) {
+        isInterested = gesture.touchCancelledInSession(touch, touchesInSession);
+      } else {
+        isInterested = gesture.touchEndedInSession(touch, touchesInSession);
+      }
+
+      // If the gesture is no longer interested in *any* touches for this session, remove it.
+      if (!isInterested) {
+        // Tell the gesture that the touch session has ended for it.
+        gesture.touchSessionCancelled();
+
+        gestures.replace(idx, 1);
+      }
+    }
+
+    // Once there are no more touches in the session, reset the interested gestures.
+    if (touchesInSession.length === 0) {
+      // Notify all remaining interested gestures that the touch session has finished cleanly.
+      var len;
+
+      for (idx = 0, len = gestures.length; idx < len; idx++) {
+        gesture = gestures[idx];
+
+        gesture.touchSessionEnded();
+      }
+
+      // Clear out the current cache of interested gestures for the session.
+      this._sc_interestedGestures.length = 0;
+    }
+  },
+
   /**
     When SC.Gesturable initializes, any gestures named on the view are instantiated.
 
@@ -178,9 +254,13 @@ SC.Gesturable = {
     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.
+
+    @param {SC.Touch} touch The touch that started.
+    @returns {Boolean} Whether the touch should be claimed by the view or not.
+    @see SC.ResponderProtocol#touchStart
   */
   touchStart: function(touch) {
-    this.gestureTouchStart(touch);
+    return this.gestureTouchStart(touch);
   },
 
   /**
@@ -189,6 +269,8 @@ SC.Gesturable = {
     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.
+
+    @see SC.ResponderProtocol#touchesDragged
   */
   touchesDragged: function(evt, touches) {
     this.gestureTouchesDragged(evt, touches);
@@ -198,58 +280,164 @@ SC.Gesturable = {
     Tells the gesture recognizing code about a touch ending.
 
     If you override touchEnd, you will need to call gestureTouchEnd
-    for any touches you called touchStart for.
+    for any touches you called gestureTouchStart for in touchStart (if overridden).
+
+    @param {SC.Touch} touch The touch that ended.
+    @see SC.ResponderProtocol#touchEnd
   */
   touchEnd: function(touch) {
     this.gestureTouchEnd(touch);
   },
 
   /**
-    Tells the gesture recognizing system about a new touch.
+    Tells the gesture recognizing code about a touch cancelling.
 
-    This informs all gestures that a new touch, "unassigned" to any gesture,
-    has been located. Later, each gesture has an opportunity to claim the touch.
+    If you override touchCancelled, you will need to call gestureTouchCancelled
+    for any touches you called gestureTouchStart for in touchStart (if overridden).
 
-    Once they have claimed the touch, further events will go _directly_ to them—
-    this view will cease receiving the touchesDragged and will not receive a touchEnd.
+    @param {SC.Touch} touch The touch that cancelled.
+    @see SC.ResponderProtocol#touchCancelled
   */
-  gestureTouchStart: function(touch) {
-    touch.isInteresting = 0;
+  touchCancelled: function (touch) {
+    this.gestureTouchCancelled(touch);
+  },
 
-    var gestures = this.get("gestures"), idx, len = gestures.length, g;
-    for (idx = 0; idx < len; idx++) {
-      g = gestures[idx];
-      g.unassignedTouchDidStart(touch);
+  /**
+    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.
+  */
+  gestureLostInterest: function (gesture) {
+    var gestures = this._sc_interestedGestures,
+        gestureIndex = gestures.indexOf(gesture);
+
+    // Remove the gesture.
+    if (gestureIndex >= 0) {
+      gesture.touchSessionCancelled();
+
+      gestures.replace(gestureIndex, 1);
     }
   },
 
   /**
-    Tells the gesture recognition system that some touches have moved.
+    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.
 
-    This informs all gestures that these touches have changed. All such touches
-    are "unassigned" because all "assigned" touches already get sent directly
-    to the gesture.
+    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).
+
+    @param {SC.Touch} touch The touch that started.
+    @returns {Boolean} Whether any gesture is interested in the touch or not.
   */
-  gestureTouchesDragged: function(evt, touches) {
-    var gestures = this.get("gestures"), idx, len = gestures.length, g;
-    for (idx = 0; idx < len; idx++) {
-      g = gestures[idx];
-      g.unassignedTouchesDidChange(evt, touches);
+  gestureTouchStart: function (touch) {
+    var interestedGestures = this._sc_interestedGestures,
+        touchesInSession = this._sc_touchesInSession,
+        claimedTouch = false,
+        idx;
+
+    // Instantiate once.
+    if (touchesInSession === null) {
+      touchesInSession = this._sc_touchesInSession = [];
+      interestedGestures = this._sc_interestedGestures = [];
+    }
+
+    // When there are no touches in the session, check all gestures.
+    if (touchesInSession.length === 0) {
+      var gestures = this.get("gestures"),
+          len;
+
+      for (idx = 0, len = gestures.length; idx < len; idx++) {
+        var gesture = gestures[idx];
+
+        gesture.touchSessionStarted(touch);
+        interestedGestures.push(gesture);
+      }
+
+      // Keep this touch.
+      claimedTouch = true;
+
+    // Only check gestures that are interested.
+    } else {
+      // Loop through the gestures in reverse, as the list may be mutated.
+      for (idx = interestedGestures.length - 1; idx >= 0; idx--) {
+        var interestedGesture = interestedGestures[idx],
+            isInterested;
+
+        // Keep only the gestures still interested in the touch.
+        isInterested = interestedGesture.touchAddedToSession(touch, touchesInSession);
+
+        if (isInterested) {
+          // Keep this touch.
+          claimedTouch = true;
+        } else {
+          // Tell the gesture that the touch session has ended for it.
+          interestedGesture.touchSessionCancelled();
+
+          interestedGestures.replace(idx, 1);
+        }
+      }
+    }
+
+    // If any gesture is interested in the new touch. Add it to the list of touches in the session.
+    if (claimedTouch) {
+      touchesInSession.push(touch);
     }
+
+    return claimedTouch;
   },
 
   /**
-    Tells the gesture recognition system that a touch have ended.
+    Tells the gesture recognition system that touches have moved.
+
+    @param {SC.Event} evt The touch event.
+    @param {Array} touches The touches previously claimed by this view.
+    @returns {void}
+  */
+  gestureTouchesDragged: function (evt, touches) {
+    var gestures = this._sc_interestedGestures,
+        touchesInSession = this._sc_touchesInSession;
+
+    // Loop through the gestures in reverse, as the list may be mutated.
+    for (var i = gestures.length - 1; i >= 0; i--) {
+      var gesture = gestures[i],
+          isInterested = gesture.touchesMovedInSession(touchesInSession);
+
+      // If the gesture is no longer interested in *any* touches for this session, remove it.
+      if (!isInterested) {
+        // Tell the gesture that the touch session has ended for it.
+        gesture.touchSessionCancelled();
+
+        gestures.replace(i, 1);
+
+        // TODO: When there are no more interested gestures? Do what with the touches? Anything?
+      }
+    }
+  },
+
+  /**
+    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.
   */
   gestureTouchEnd: function(touch) {
-    var gestures = this.get("gestures"), idx, len = gestures.length, g;
-    for (idx = 0; idx < len; idx++) {
-      g = gestures[idx];
-      g.unassignedTouchDidEnd(touch);
-    }
+    this._sc_gestureTouchFinish(touch, false);
+  },
+
+  /**
+    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.
+  */
+  gestureTouchCancelled: function(touch) {
+    this._sc_gestureTouchFinish(touch, true);
   }
 };