sproutcore 1.11.0.rc2 → 1.11.0.rc3

data/lib/frameworks/sproutcore/frameworks/core_foundation/panes/layout.js

@@ -63,12 +63,6 @@ SC.Pane.reopen(
     return wDim;
   },
 
-  /** @private Disable caching due to an known bug in SC. */
-  frame: function () {
-    if (this.get('designer') && SC.suppressMain) { return sc_super(); }
-    return this.computeFrameWithParentFrame(null);
-  }.property(),
-
   /**
     Invoked by the root responder whenever the window resizes.  This should
     simply begin the process of notifying children that the view size has

data/lib/frameworks/sproutcore/frameworks/core_foundation/panes/pane.js

@@ -476,7 +476,9 @@ SC.Pane = SC.View.extend(SC.ResponderContext,
     @returns {SC.Pane} receiver
   */
   remove: function() {
-    this._doDetach();
+    if (this.get('isAttached')) {
+      this._doDetach();
+    }
 
     return this ;
   },
@@ -546,13 +548,15 @@ SC.Pane = SC.View.extend(SC.ResponderContext,
     // and call sc_super() won't fail.
   },
 
-  /**
-    YES when the pane is currently attached to a document DOM.  Read only.
+  /** @deprecated Version 1.11. Use `isAttached` instead. */
+  isPaneAttached: function () {
 
-    @type Boolean
-    @readOnly
-  */
-  isPaneAttached: NO,
+    //@if(debug)
+    SC.warn("Developer Warning: The `isPaneAttached` property of `SC.Pane` has been deprecated. Please use the `isAttached` property instead.");
+    //@endif
+
+    return this.get('isAttached');
+  }.property('isAttached').cacheable(),
 
   /**
     If YES, a touch intercept pane will be added above this pane when on

data/lib/frameworks/sproutcore/frameworks/core_foundation/panes/pane_statechart.js

@@ -12,7 +12,7 @@ sc_require("panes/pane");
 SC.Pane.reopen({
 
   /** @private */
-  _notifyDidAttach: function () {
+  _executeDoAttach: function () {
     // hook into root responder
     var responder = (this.rootResponder = SC.RootResponder.responder);
     responder.panes.add(this);
@@ -20,16 +20,17 @@ SC.Pane.reopen({
     // Update the currentWindowSize cache.
     this.set('currentWindowSize', responder.currentWindowSize);
 
+    // Set the initial design mode.  The responder will update this if it changes.
+    this.updateDesignMode(this.get('designMode'), responder.get('currentDesignMode'));
+
+    sc_super();
+
     // Legacy.
-    this.set('isPaneAttached', YES);
     this.paneDidAttach();
 
     // Legacy?
     this.recomputeDependentProperties();
 
-    // Set the initial design mode.  The responder will update this if it changes.
-    this.updateDesignMode(this.get('designMode'), responder.get('currentDesignMode'));
-
     // handle intercept if needed
     this._addIntercept();
 
@@ -39,17 +40,12 @@ SC.Pane.reopen({
       // We call viewDidResize so that it calls parentViewDidResize on all child views.
       this.viewDidResize();
     }
-
-    sc_super();
   },
 
   /** @private */
-  _notifyWillDetach: function () {
+  _executeDoDetach: function () {
     sc_super();
 
-    // Legacy.
-    this.set('isPaneAttached', NO);
-
     // remove intercept
     this._removeIntercept();
 

data/lib/frameworks/sproutcore/frameworks/core_foundation/protocols/child_view_layout_protocol.js

@@ -4,9 +4,14 @@
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 
-/**
-  The SC.ChildViewLayoutProtocol defines the expected and optional properties
-  and methods to implement in your own child view layout plugin.
+/** @namespace
+  The `SC.ChildViewLayoutProtocol` protocol defines the properties and methods that you may
+  implement in your custom child view layout plugins. The only required method for a plugin to
+  implement is `layoutChildViews`.
+
+  *Note: Do not mix `SC.ChildViewLayoutProtocol` into your classes. As a protocol, it exists only
+  for reference sake. You only need define any of the properties or methods listed below in order to
+  use this protocol.*
 */
 SC.ChildViewLayoutProtocol = {
 

data/lib/frameworks/sproutcore/frameworks/core_foundation/protocols/observable_protocol.js

@@ -5,16 +5,19 @@
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 
-/**
-  The SC.ObservableProtocol defines optional methods you can implement on your
-  objects.  They will be used if defined but are not required for observing to
-  work.
+/** @namespace
+  The `SC.ObservableProtocol` protocol defines the properties and methods that you may implement
+  in your `SC.Observable` consumers (i.e. `SC.Object`) in order to access additional observer
+  functionality. They will be used if defined but are not required for observing to work.
+
+  *Note: Do not mix `SC.ObservableProtocol` into your classes. As a protocol, it exists only for
+  reference sake. You only need define any of the properties or methods listed below in order to use
+  this protocol.*
 */
 SC.ObservableProtocol = {
 
   /**
-    Generic property observer called whenever a property on the receiver
-    changes.
+    Generic property observer called whenever a property on the receiver changes.
 
     If you need to observe a large number of properties on your object, it
     is sometimes more efficient to implement this observer only and then to

data/lib/frameworks/sproutcore/frameworks/{desktop/protocols/responder.js → core_foundation/protocols/responder_protocol.js}

@@ -5,18 +5,15 @@
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 
+/** @namespace
+  The `SC.ResponderProtocol` protocol defines the properties and methods that you may implement
+  in your `SC.Responder` (i.e. `SC.View`) subclasses in order to handle specific responder chain
+  events.
 
-/** @static
+  *Note: Do not mix `SC.ResponderProtocol` into your classes. As a protocol, it exists only for
+  reference sake. You only need define any of the properties or methods listed below in order to use
+  this protocol.*
 
-  This protocol defines the allowable responder methods. To implement a
-  specific responder method, and a method with the correct signature to your
-  class.
-
-  **DO NOT INCLUDE THIS MIXIN**.
-
-  If you try and include this mixin, an error will be raised on startup.
-
-  @author Erich Ocean
   @since SproutCore 1.0
 */
 SC.ResponderProtocol = {
@@ -78,6 +75,14 @@ SC.ResponderProtocol = {
   */
   mouseMoved: function(evt) {},
 
+  /**
+     Called when a contextmenu event is triggered. Used to disable contextmenu
+     per view.
+
+     @param evt {SC.Event} the contextmenu event
+     @returns {void}
+   */
+  contextMenu: function(evt) {},
 
   /**
     Called when a selectstart event in IE is triggered. **ONLY IE**
@@ -88,17 +93,78 @@ SC.ResponderProtocol = {
   */
   selectStart: function(evt) {},
 
+  // .......................................................................
+  // Touch Event Handlers
+  //
+
   /**
-     Called when a contextmenu event is triggered. Used to disable contextmenu
-     per view.
+    Called when a touch begins. Capturing a touch is a special case behavior that allows for the
+    nesting of touch capable views. In some situations, an outer view may want to capture a touch
+    *before* the inner view acts on it. For example, a container view may want to act on swipes or
+    pinches, while the inner view may only respond to taps. If the normal event path was followed,
+    the inner view would get the `touchStart` event and by accepting it, would inadvertently prevent
+    the outer view from being able to act on it.
+
+    For this reason, when a touch begins, each view from the top-down has a chance to capture a
+    touch first, before it is passed to the bottom-most target view. For example, SC.ScrollView
+    captures touches so that it can determine if the touch is the beginning of a swipe or pinch. If
+    the touch does become one of these gestures, SC.ScrollView can act on it. However, if the touch
+    doesn't become one of these gestures, SC.ScrollView understands that it needs to pass the touch
+    to its children.
+
+    Therefore, implementors of `captureTouch` are expected to release the touch if they won't use it
+    by calling the touch's `captureTouch` method and passing themself as the new starting point
+    (capturing will continue from the implementor onward as it would have if the implementor hadn't
+    temporarily captured it).
+
+    Note, `captureTouch` is only meaningful for container type views where their children may
+    handle touches as well. For most controls that want to handle touch, there is no reason to
+    capture a touch, because they don't have any children. For these views, simply use the
+    `touchStart`, `touchesDragged`, `touchCancelled` and `touchEnd` methods.
+
+    @param touch {SC.Touch} the touch
+    @returns {Boolean} YES to claim the touch and receive touchStart, NO otherwise
+    @see SC.Touch#captureTouch
+  */
+  captureTouch: function (touch) {},
 
-     @param evt {SC.Event} the contextmenu event
-     @returns {void}
-   */
-  contextMenu: function(evt) {},
+  /**
+    Called when a touch previously claimed by returning `true` from `touchStart` is cancelled.
+
+    @param touch {SC.Touch} the touch
+    @returns {void}
+  */
+  touchCancelled: function (touch) {},
+
+  /**
+    Called when an active touch moves. The touches array contains all of the touches that this view
+    has claimed by returning `true` from `touchStart`.
+
+    @param evt {SC.Event} the event
+    @param touches {Array} the touches
+    @returns {void}
+  */
+  touchesDragged: function (evt, touches) {},
+
+  /**
+    Called when a touch previously claimed by returning `true` from `touchStart` ends.
+
+    @param touch {SC.Touch} the touch
+    @returns {void}
+  */
+  touchEnd: function (touch) {},
+
+  /**
+    Called when a touch begins. You must return `YES` to receive `touchesDragged` and `touchEnd` in
+    the future.
+
+    @param touch {SC.Touch} the touch
+    @returns {Boolean} YES to receive additional touch events, NO otherwise
+  */
+  touchStart: function (touch) {},
 
   // .......................................................................
-  // Event Handlers
+  // Keyboard Event Handlers
   //
   // These methods are called by the input manager in response to keyboard
   // events.  Most of these methods are defined here for you, but not actually

data/lib/frameworks/sproutcore/frameworks/core_foundation/protocols/{sparse_array_delegate.js → sparse_array_delegate_protocol.js}

@@ -6,18 +6,22 @@
 // ==========================================================================
 
 /** @namespace
+  The `SC.SparseArrayDelegateProtocol` protocol defines the properties and methods that you may
+  implement in your sparse array delegate objects.
 
-  Delegate that provides data for a sparse array.  If you set the delegate for
-  a sparse array to an object that implements one or more of these methods,
-  they will be invoked by the sparse array to fetch data or to update the
-  array content as needed.
+  An object that implements this protocol may act as a delegate that provides data for a sparse
+  array.  The delegate is invoked by the sparse array to fetch data or to update the array content
+  as needed.
 
-  Your object does not need to implement all of these methods, but it should
-  at least implement the sparseArrayDidRequestIndex() method.
+  Your object does not need to implement all of these methods, but it should at least implement the `sparseArrayDidRequestIndex()` method.
+
+  *Note: Do not mix `SC.SparseArrayDelegateProtocol` into your classes. As a protocol, it exists
+  only for reference sake. You only need define any of the properties or methods listed below in
+  order to use this protocol.*
 
   @since SproutCore 1.0
 */
-SC.SparseArrayDelegate = {
+SC.SparseArrayDelegateProtocol = {
 
   /**
     Invoked when an object requests the length of the sparse array and the

data/lib/frameworks/sproutcore/frameworks/core_foundation/protocols/view_transition_protocol.js

@@ -6,11 +6,16 @@
 
 
 /** @namespace
-  This protocol defines the allowable transition plugin methods.
+  The `SC.ViewTransitionProtocol` protocol defines the properties and methods that you may
+  implement in your custom transition plugins. The only required method for a plugin to
+  implement is `run`.
 
-  SC.View uses transition plugins to setup, execute and cleanup the
-  swapping between views and expects the given transition plugin object
-  to implement the methods in this protocol.
+  SC.View uses transition plugins to setup, execute and cleanup the swapping between views and
+  expects the given transition plugin object to implement this protocol.
+
+  *Note: Do not mix `SC.ViewTransitionProtocol` into your classes. As a protocol, it exists only
+  for reference sake. You only need define any of the properties or methods listed below in order to
+  use this protocol.*
 */
 SC.ViewTransitionProtocol = {
 
@@ -31,8 +36,8 @@ SC.ViewTransitionProtocol = {
   setup: function (view, options, inPlace) {},
 
   /**
-    This method is called to transition the view in or visible (i.e.
-    transitionIn or transitionShow).
+    This method is called to transition the view in or visible (i.e. transitionIn or
+    transitionShow).
 
     When the transition completes, this function *must* call `didTransitionIn()`
     on the view, passing this object and the original options as

data/lib/frameworks/sproutcore/frameworks/core_foundation/system/color.js

@@ -47,7 +47,7 @@
   rgba values stay within the device's gamut (0 to 255 on a normal screen, and 0 to 1
   for alpha). For example, adding white to white will result in r, g and b values of
   510, a nonsensical value. (The `cssText` property will, however, correctly clamp the
-  component values, and the color will output `#FFFFFF`.) This behavior is required
+  component values, and the color will output #FFFFFF.) This behavior is required
   for operations such as interpolating between colors (see "SC.Color and SC.View"
   below); it also gives SC.Color more predictable math, where A + B - B = A, even if
   the intermediate (A + B) operation results in underlying values outside of the normal
@@ -133,7 +133,7 @@
   ### Edge Case: Supporting Alpha in IE
 
   Supporting the alpha channel in older versions of IE requires a little extra work.
-  The bindable `cssText` property will return valid ARGB (e.g. `#99FFFFFF`) when it
+  The bindable `cssText` property will return valid ARGB (e.g. #99FFFFFF) when it
   detects that it's in an older version of IE which requires it, but unfortunately you
   can't simply plug that value into `background-color`. The following code will detect
   this case and provide the correct CSS snippet:

data/lib/frameworks/sproutcore/frameworks/core_foundation/system/page.js

@@ -37,31 +37,9 @@ SC.Page = SC.Object.extend(
     var value = this[key] ;
     if (value && value.isClass) {
       this[key] = value = value.create({ page: this }) ;
-      if (!this.get('inDesignMode')) value.awake() ;
       return value ;
     } else return sc_super();
   },
-  
-  /**
-    Finds all views defined on this page instances and builds them.  This is 
-    a quick, brute force way to wake up all of the views in a page object.  It
-    is not generally recommended. Instead, you should use get() or getPath() 
-    to retrieve views and rely on the lazy creation process to set them up.
-    
-    @return {SC.Page} receiver
-  */
-  awake: function() {
-    // step through all views and build them
-    var value, key;
-    for(key in this) {
-      if (!this.hasOwnProperty(key)) continue ;
-      value = this[key] ;
-      if (value && value.isViewClass) {
-        this[key] = value = value.create({ page: this }) ;
-      }
-    }
-    return this;
-  },
 
   /**
     Returns the named property unless the property is a view that has not yet

data/lib/frameworks/sproutcore/frameworks/core_foundation/system/root_responder.js

@@ -230,7 +230,7 @@ SC.RootResponder = SC.Object.extend(
       var candidate;
       while (previousKeyPanes.length > 0) {
         candidate = previousKeyPanes.pop();
-        if (candidate.get('isPaneAttached')  &&  candidate.get('acceptsKeyPane')) {
+        if (candidate.get('isVisibleInWindow') && candidate.get('acceptsKeyPane')) {
           newKeyPane = candidate ;
           break ;
         }
@@ -2108,33 +2108,37 @@ SC.RootResponder = SC.Object.extend(
     // First, save the click count. The click count resets if the mouse down
     // event occurs more than 250 ms later than the mouse up event or more
     // than 8 pixels away from the mouse down event or if the button used is different.
-    this._clickCount += 1 ;
-    if (!this._lastMouseUpAt || this._lastClickWhich !== evt.which || ((Date.now() - this._lastMouseUpAt) > 250)) {
-      this._clickCount = 1 ;
-    } else {
-      var deltaX = this._lastMouseDownX - evt.clientX,
-          deltaY = this._lastMouseDownY - evt.clientY,
-          distance = Math.sqrt(deltaX*deltaX + deltaY*deltaY) ;
-
-      if (distance > 8.0) this._clickCount = 1 ;
-    }
-    evt.clickCount = this._clickCount ;
-
-    this._lastClickWhich = evt.which;
-    this._lastMouseDownX = evt.clientX ;
-    this._lastMouseDownY = evt.clientY ;
+    this._clickCount += 1;
 
     var view = this.targetViewForEvent(evt);
 
     view = this._mouseDownView = this.sendEvent('mouseDown', evt, view) ;
     if (view && view.respondsTo('mouseDragged')) this._mouseCanDrag = YES ;
 
-    // Determine if any views took responsibility for the
-    // event. If so, save that information so we can prevent
-    // the next click event we receive from propagating to the browser.
+    // Determine if any views took responsibility for the event. If so, save that information so we
+    // can prevent the next click event we receive from propagating to the browser.
     var ret = view ? evt.hasCustomEventHandling : YES;
     this._lastMouseDownCustomHandling = ret;
 
+    // If it has been too long since the last click, the handler has changed or the mouse has moved
+    // too far, reset the click count.
+    if (!this._lastMouseUpAt || this._lastMouseDownView !== this._mouseDownView || ((Date.now() - this._lastMouseUpAt) > 250)) {
+      this._clickCount = 1;
+    } else {
+      var deltaX = this._lastMouseDownX - evt.clientX,
+          deltaY = this._lastMouseDownY - evt.clientY,
+          distance = Math.sqrt(deltaX*deltaX + deltaY*deltaY) ;
+
+      if (distance > 8.0) this._clickCount = 1;
+    }
+    evt.clickCount = this._clickCount;
+
+    // Cache the handler and point of the last mouse down in order to determine whether a successive mouse down should
+    // still increment the click count.
+    this._lastMouseDownView = this._mouseDownView;
+    this._lastMouseDownX = evt.clientX;
+    this._lastMouseDownY = evt.clientY;
+
     return ret;
   },
 
@@ -2159,41 +2163,41 @@ SC.RootResponder = SC.Object.extend(
       var view = this._mouseDownView,
         targetView = this.targetViewForEvent(evt);
 
-    // record click count.
-    evt.clickCount = this._clickCount ;
+      // record click count.
+      evt.clickCount = this._clickCount ;
 
-    // attempt the mouseup call only if there's a target.
-    // don't want a mouseup going to anyone unless they handled the mousedown...
-    if (view) {
-      handler = this.sendEvent('mouseUp', evt, view) ;
+      // attempt the mouseup call only if there's a target.
+      // don't want a mouseup going to anyone unless they handled the mousedown...
+      if (view) {
+        handler = this.sendEvent('mouseUp', evt, view) ;
 
-      // try doubleClick
-      if (!handler && (this._clickCount === 2)) {
-        handler = this.sendEvent('doubleClick', evt, view) ;
-        clickOrDoubleClickDidTrigger = YES;
-      }
+        // try doubleClick
+        if (!handler && this._clickCount === 2) {
+          handler = this.sendEvent('doubleClick', evt, view) ;
+          clickOrDoubleClickDidTrigger = YES;
+        }
 
-      // try single click
-      if (!handler) {
-        handler = this.sendEvent('click', evt, view) ;
-        clickOrDoubleClickDidTrigger = YES;
+        // try single click
+        if (!handler) {
+          handler = this.sendEvent('click', evt, view) ;
+          clickOrDoubleClickDidTrigger = YES;
+        }
       }
-    }
 
-    // try whoever's under the mouse if we haven't handle the mouse up yet
-    if (!handler && !clickOrDoubleClickDidTrigger) {
+      // try whoever's under the mouse if we haven't handle the mouse up yet
+      if (!handler && !clickOrDoubleClickDidTrigger) {
 
-      // try doubleClick
-      if (this._clickCount === 2) {
-        handler = this.sendEvent('doubleClick', evt, targetView);
-      }
+        // try doubleClick
+        if (this._clickCount === 2) {
+          handler = this.sendEvent('doubleClick', evt, targetView);
+        }
 
-      // try singleClick
-      if (!handler) {
-        handler = this.sendEvent('click', evt, targetView) ;
+        // try singleClick
+        if (!handler) {
+          handler = this.sendEvent('click', evt, targetView) ;
+        }
       }
     }
-    }
 
     // cleanup
     this._mouseCanDrag = NO;
@@ -2529,32 +2533,32 @@ SC.RootResponder = SC.Object.extend(
 
   /* @private Handler for animationstart events. */
   animationstart: function (evt) {
-      var view = this.targetViewForEvent(evt) ;
-      this.sendEvent('animationDidStart', evt, view) ;
+    var view = this.targetViewForEvent(evt);
+    this.sendEvent('animationDidStart', evt, view);
 
     return view ? evt.hasCustomEventHandling : YES;
   },
 
   /* @private Handler for animationiteration events. */
   animationiteration: function (evt) {
-      var view = this.targetViewForEvent(evt) ;
-      this.sendEvent('animationDidIterate', evt, view) ;
+    var view = this.targetViewForEvent(evt);
+    this.sendEvent('animationDidIterate', evt, view);
 
     return view ? evt.hasCustomEventHandling : YES;
   },
 
   /* @private Handler for animationend events. */
   animationend: function (evt) {
-      var view = this.targetViewForEvent(evt) ;
-      this.sendEvent('animationDidEnd', evt, view) ;
+    var view = this.targetViewForEvent(evt);
+    this.sendEvent('animationDidEnd', evt, view);
 
     return view ? evt.hasCustomEventHandling : YES;
   },
 
   /* @private Handler for transitionend events. */
   transitionend: function (evt) {
-      var view = this.targetViewForEvent(evt) ;
-      this.sendEvent('transitionDidEnd', evt, view) ;
+    var view = this.targetViewForEvent(evt);
+    this.sendEvent('transitionDidEnd', evt, view);
 
     return view ? evt.hasCustomEventHandling : YES;
   }
@@ -2565,8 +2569,9 @@ SC.RootResponder = SC.Object.extend(
   Invoked when the document is ready, but before main is called.  Creates
   an instance and sets up event listeners as needed.
 */
-SC.ready(SC.RootResponder, SC.RootResponder.ready = function() {
+SC.ready(SC.RootResponder, SC.RootResponder.ready = function () {
   var r;
-  r = SC.RootResponder.responder = SC.RootResponder.create() ;
-  r.setup() ;
+
+  r = SC.RootResponder.responder = SC.RootResponder.create();
+  r.setup();
 });