sproutcore 1.8.2.1 → 1.9.0

data/lib/frameworks/sproutcore/frameworks/core_foundation/controllers/object.js

@@ -12,40 +12,40 @@ sc_require('controllers/controller') ;
   An ObjectController gives you a simple way to manage the editing state of
   an object.  You can use an ObjectController instance as a "proxy" for your
   model objects.
-  
-  Any properties you get or set on the object controller, will be passed 
+
+  Any properties you get or set on the object controller, will be passed
   through to its content object.  This allows you to setup bindings to your
-  object controller one time for all of your views and then swap out the 
+  object controller one time for all of your views and then swap out the
   content as needed.
-  
+
   ## Working with Arrays
-  
-  An ObjectController can accept both arrays and single objects as content.  
-  If the content is an array, the ObjectController will do its best to treat 
+
+  An ObjectController can accept both arrays and single objects as content.
+  If the content is an array, the ObjectController will do its best to treat
   the array as a single object.  For example, if you set the content of an
   ObjectController to an array of Contact records and then call:
-  
+
       contactController.get('name');
 
-  The controller will check the name property of each Contact in the array.  
-  If the value of the property for each Contact is the same, that value will 
-  be returned.  If the any values are different, then an array will be 
-  returned with the values from each Contact in them. 
-  
-  Most SproutCore views can work with both arrays and single content, which 
+  The controller will check the name property of each Contact in the array.
+  If the value of the property for each Contact is the same, that value will
+  be returned.  If the any values are different, then an array will be
+  returned with the values from each Contact in them.
+
+  Most SproutCore views can work with both arrays and single content, which
   means that most of the time, you can simply hook up your views and this will
   work.
-  
-  If you would prefer to make sure that your ObjectController is always 
-  working with a single object and you are using bindings, you can always 
-  setup your bindings so that they will convert the content to a single object 
+
+  If you would prefer to make sure that your ObjectController is always
+  working with a single object and you are using bindings, you can always
+  setup your bindings so that they will convert the content to a single object
   like so:
-  
+
       contentBinding: SC.Binding.single('MyApp.listController.selection') ;
 
-  This will ensure that your content property is always a single object 
+  This will ensure that your content property is always a single object
   instead of an array.
-  
+
   @extends SC.Controller
   @since SproutCore 1.0
 */
@@ -54,8 +54,8 @@ SC.ObjectController = SC.Controller.extend(
 
   // ..........................................................
   // PROPERTIES
-  // 
-  
+  //
+
   /**
     Set to the object you want this controller to manage.  The object should
     usually be a single value; not an array or enumerable.  If you do supply
@@ -64,21 +64,21 @@ SC.ObjectController = SC.Controller.extend(
 
     Usually your content object should implement the SC.Observable mixin, but
     this is not required.  All SC.Object-based objects support SC.Observable
-    
+
     @property {Object}
   */
   content: null,
 
   /**
-    If YES, then setting the content to an enumerable or an array with more 
+    If YES, then setting the content to an enumerable or an array with more
     than one item will cause the Controller to attempt to treat the array as
     a single object.  Use of get(), for example, will get every property on
     the enumerable and return it.  set() will set the property on every item
-    in the enumerable. 
-    
+    in the enumerable.
+
     If NO, then setting content to an enumerable with multiple items will be
     treated like setting a null value.  hasContent will be NO.
-    
+
     @property {Boolean}
   */
   allowsMultipleContent: NO,
@@ -86,95 +86,95 @@ SC.ObjectController = SC.Controller.extend(
   /**
     Becomes YES whenever this object is managing content.  Usually this means
     the content property contains a single object or an array or enumerable
-    with a single item.  Array's or enumerables with multiple items will 
+    with a single item.  Array's or enumerables with multiple items will
     normally make this property NO unless allowsMultipleContent is YES.
-    
+
     @property {Boolean}
   */
   hasContent: function() {
     return !SC.none(this.get('observableContent'));
   }.property('observableContent'),
-  
+
   /**
-    Makes a controller editable or not editable.  The SC.Controller class 
-    itself does not do anything with this property but subclasses will 
+    Makes a controller editable or not editable.  The SC.Controller class
+    itself does not do anything with this property but subclasses will
     respect it when modifying content.
-    
+
     @property {Boolean}
   */
   isEditable: YES,
-  
+
   /**
-    Primarily for internal use.  Normally you should not access this property 
-    directly.  
-    
-    Returns the actual observable object proxied by this controller.  Usually 
-    this property will mirror the content property.  In some cases - notably 
+    Primarily for internal use.  Normally you should not access this property
+    directly.
+
+    Returns the actual observable object proxied by this controller.  Usually
+    this property will mirror the content property.  In some cases - notably
     when setting content to an enumerable, this may return a different object.
-    
+
     Note that if you set the content to an enumerable which itself contains
     enumerables and allowsMultipleContent is NO, this will become null.
-    
+
     @property {Object}
   */
   observableContent: function() {
     var content = this.get('content'),
         len, allowsMultiple;
-        
+
     // if enumerable, extract the first item or possibly become null
     if (content && content.isEnumerable) {
       len = content.get('length');
       allowsMultiple = this.get('allowsMultipleContent');
-      
+
       if (len === 1) content = content.firstObject();
       else if (len===0 || !allowsMultiple) content = null;
-      
+
       // if we got some new content, it better not be enum also...
       if (content && !allowsMultiple && content.isEnumerable) content=null;
     }
-    
+
     return content;
   }.property('content', 'allowsMultipleContent').cacheable(),
 
   // ..........................................................
   // METHODS
-  // 
+  //
 
   /**
     Override this method to destroy the selected object.
-    
+
     The default just passes this call onto the content object if it supports
-    it, and then sets the content to null.  
-    
-    Unlike most calls to destroy() this will not actually destroy the 
-    controller itself; only the the content.  You continue to use the 
+    it, and then sets the content to null.
+
+    Unlike most calls to destroy() this will not actually destroy the
+    controller itself; only the the content.  You continue to use the
     controller by setting the content to a new value.
-    
+
     @returns {SC.ObjectController} receiver
   */
   destroy: function() {
     var content = this.get('observableContent') ;
     if (content && SC.typeOf(content.destroy) === SC.T_FUNCTION) {
       content.destroy();
-    } 
-    this.set('content', null) ;  
+    }
+    this.set('content', null) ;
     return this;
   },
-  
+
   /**
-    Invoked whenever any property on the content object changes.  
+    Invoked whenever any property on the content object changes.
 
-    The default implementation will simply notify any observers that the 
-    property has changed.  You can override this method if you need to do 
+    The default implementation will simply notify any observers that the
+    property has changed.  You can override this method if you need to do
     some custom work when the content property changes.
-    
-    If you have set the content property to an enumerable with multiple 
-    objects and you set allowsMultipleContent to YES, this method will be 
+
+    If you have set the content property to an enumerable with multiple
+    objects and you set allowsMultipleContent to YES, this method will be
     called anytime any property in the set changes.
 
-    If all properties have changed on the content or if the content itself 
+    If all properties have changed on the content or if the content itself
     has changed, this method will be called with a key of "*".
-    
+
     @param {Object} target the content object
     @param {String} key the property that changes
     @returns {void}
@@ -183,26 +183,26 @@ SC.ObjectController = SC.Controller.extend(
     if (key === '*') this.allPropertiesDidChange();
     else this.notifyPropertyChange(key);
   },
-  
+
   /**
-    Called whenver you try to get/set an unknown property.  The default 
-    implementation will pass through to the underlying content object but 
-    you can override this method to do some other kind of processing if 
+    Called whenver you try to get/set an unknown property.  The default
+    implementation will pass through to the underlying content object but
+    you can override this method to do some other kind of processing if
     needed.
-    
+
     @property {String} key key being retrieved
     @property {Object} value value to set or undefined if reading only
     @returns {Object} property value
   */
   unknownProperty: function(key,value) {
-    
+
     // avoid circular references
     if (key==='content') {
       if (value !== undefined) this.content = value;
       return this.content;
     }
-    
-    // for all other keys, just pass through to the observable object if 
+
+    // for all other keys, just pass through to the observable object if
     // there is one.  Use getEach() and setEach() on enumerable objects.
     var content = this.get('observableContent'), loc, cur, isSame;
     if (content===null || content===undefined) return undefined; // empty
@@ -225,21 +225,21 @@ SC.ObjectController = SC.Controller.extend(
         } else value = undefined; // empty array.
 
       } else value = (content.isObservable) ? content.get(key) : content[key];
-      
+
     // setter
     } else {
       if (!this.get('isEditable')) {
         throw "%@.%@ is not editable".fmt(this,key);
       }
-      
+
       if (content.isEnumerable) content.setEach(key, value);
       else if (content.isObservable) content.set(key, value);
       else content[key] = value;
     }
-    
+
     return value;
   },
-  
+
   // ...............................
   // INTERNAL SUPPORT
   //
@@ -254,23 +254,21 @@ SC.ObjectController = SC.Controller.extend(
   _scoc_contentDidChange: function () {
     var last = this._scoc_content,
         cur  = this.get('content');
-        
+
     if (last !== cur) {
       this._scoc_content = cur;
       var func = this._scoc_enumerableContentDidChange;
       if (last && last.isEnumerable) {
-        //console.log('no longer observing [] on last');
         last.removeObserver('[]', this, func);
       }
       if (cur && cur.isEnumerable) {
-        //console.log('observing [] on cur');
         cur.addObserver('[]', this, func);
       }
     }
   }.observes("content"),
-  
+
   /**  @private
-    
+
     Called whenever the observable content property changes.  This will setup
     observers on the content if needed.
   */
@@ -282,15 +280,15 @@ SC.ObjectController = SC.Controller.extend(
 
     if (last === cur) return this; // nothing to do
     //console.log('observableContentDidChange');
-    
+
     this._scoc_observableContent = cur; // save old content
-    
+
     // stop observing last item -- if enumerable stop observing set
     if (last) {
       if (last.isEnumerable) last.removeObserver('[]', this, efunc);
       else if (last.isObservable) last.removeObserver('*', this, func);
     }
-    
+
     if (cur) {
       if (cur.isEnumerable) cur.addObserver('[]', this, efunc);
       else if (cur.isObservable) cur.addObserver('*', this, func);
@@ -302,10 +300,10 @@ SC.ObjectController = SC.Controller.extend(
     } else this.contentPropertyDidChange(cur, '*');
 
   }.observes("observableContent"),
-  
+
   /** @private
     Called when observed enumerable content has changed.  This will teardown
-    and setup observers on the enumerable content items and then calls 
+    and setup observers on the enumerable content items and then calls
     contentPropertyDidChange().  This method may be called even if the new
     'cur' is not enumerable but the last content was enumerable.
   */
@@ -313,7 +311,7 @@ SC.ObjectController = SC.Controller.extend(
     var cur  = this.get('observableContent'),
         set  = this._scoc_observableContentItems,
         func = this.contentPropertyDidChange;
-    
+
     // stop observing each old item
     if (set) {
       set.forEach(function(item) {
@@ -321,7 +319,7 @@ SC.ObjectController = SC.Controller.extend(
       }, this);
       set.clear();
     }
-    
+
     // start observing new items if needed
     if (cur && cur.isEnumerable) {
       if (!set) set = SC.Set.create();
@@ -329,14 +327,14 @@ SC.ObjectController = SC.Controller.extend(
         if (set.contains(item)) return ; // nothing to do
         set.add(item);
         if (item.isObservable) item.addObserver('*', this, func);
-      }, this); 
+      }, this);
     } else set = null;
-    
+
     this._scoc_observableContentItems = set; // save for later cleanup
-  
+
     // notify
     this.contentPropertyDidChange(cur, '*');
     return this ;
   }
-        
+
 }) ;

data/lib/frameworks/sproutcore/frameworks/core_foundation/ext/object.js

@@ -9,76 +9,106 @@
 SC.mixin(SC.Object.prototype, /** @scope SC.Object.prototype */ {
 
   /**
-    Invokes the named method after the specified period of time.
+    Invokes the named method after the specified period of time.  This
+    uses SC.Timer, which works properly with the Run Loop.
 
-    This is a convenience method that will create a single run timer to
-    invoke a method after a period of time.  The method should have the
-    signature:
+    Any additional arguments given to invokeOnce will be passed to the
+    method.
 
-        methodName: function(timer)
+    For example,
 
-    If you would prefer to pass your own parameters instead, you can instead
-    call invokeLater() directly on the function object itself.
+        var obj = SC.Object.create({
+          myMethod: function(a, b, c) {
+            alert('a: %@, b: %@, c: %@'.fmt(a, b, c));
+          }
+        });
 
-    @param methodName {String} method name to perform.
+        obj.invokeLater('myMethod', 200, 'x', 'y', 'z');
+
+        // After 200 ms, alerts "a: x, b: y, c: z"
+
+    @param method {String} method name to perform.
     @param interval {Number} period from current time to schedule.
     @returns {SC.Timer} scheduled timer.
   */
-  invokeLater: function(methodName, interval) {
+  invokeLater: function(method, interval) {
+    var f, args;
+
+    // Normalize the method and interval.
+    if (SC.typeOf(method) === SC.T_STRING) { method = this[method]; }
     if (interval === undefined) { interval = 1 ; }
-    var f = methodName, args, func;
 
-    // if extra arguments were passed - build a function binding.
+    // If extra arguments were passed - build a function binding.
     if (arguments.length > 2) {
       args = SC.$A(arguments).slice(2);
-      if (SC.typeOf(f) === SC.T_STRING) { f = this[methodName] ; }
-      func = f ;
-      f = function() { return func.apply(this, args); } ;
+      f = function() { return method.apply(this, args); } ;
+    } else {
+      f = method;
     }
 
     // schedule the timer
     return SC.Timer.schedule({ target: this, action: f, interval: interval });
   },
-  
+
   /**
-    A convenience method which makes it easy to coalesce invocations to ensure 
-    that the method is only called once. This is useful if you need to schedule 
-    a call but only want it to trigger once after some defined interval has 
-    passed.
-    
+    A convenience method which makes it easy to coalesce invocations to ensure
+    that the method is only called once after the given period of time. This is
+    useful if you need to schedule a call from multiple places, but only want
+    it to run at most once.
+
+    Any additional arguments given to invokeOnceLater will be passed to the
+    method.
+
+    For example,
+
+        var obj = SC.Object.create({
+          myMethod: function(a, b, c) {
+            alert('a: %@, b: %@, c: %@'.fmt(a, b, c));
+          }
+        });
+
+        obj.invokeOnceLater('myMethod', 200, 'x', 'y', 'z');
+
+        // After 200 ms, alerts "a: x, b: y, c: z"
+
     @param {Function|String} method reference or method name
     @param {Number} interval
   */
   invokeOnceLater: function(method, interval) {
-    if (interval === undefined) { interval = 1 ; }
+    var args, f,
+        methodGuid,
+        timers = this._sc_invokeOnceLaterTimers,
+        existingTimer, newTimer;
 
-    var timers = this._sc_invokeOnceLaterTimers,
-        methodGuid, existingTimer, f, newTimer;
+    // Normalize the method, interval and timers cache.
+    if (SC.typeOf(method) === SC.T_STRING) { method = this[method]; }
+    if (interval === undefined) { interval = 1 ; }
+    if (!timers) { timers = this._sc_invokeOnceLaterTimers = {}; }
 
-    // ensure we always deal with real functions
-    if (SC.typeOf(method) === SC.T_STRING) {
-      method = this[method];
-    }
-    
+    // If there's a timer outstanding for this method, invalidate it in favor of
+    // the new timer.
     methodGuid = SC.guidFor(method);
-    
-    if(!timers) {
-      this._sc_invokeOnceLaterTimers = timers = {};
-    }
-    
     existingTimer = timers[methodGuid];
-    if(existingTimer) existingTimer.invalidate();
-    
+    if (existingTimer) existingTimer.invalidate();
+
+    // If extra arguments were passed - apply them to the method.
+    if (arguments.length > 2) {
+      args = SC.$A(arguments).slice(2);
+    } else {
+      args = arguments;
+    }
+
+    // Create a function binding every time, so that the timers cache is properly cleaned out.
     f = function() {
       // GC assistance for IE
       delete timers[methodGuid];
-      return method.apply(this, arguments);
+      return method.apply(this, args);
     };
-    
-    // schedule the timer
+
+    // Schedule the new timer and track it.
     newTimer = SC.Timer.schedule({ target: this, action: f, interval: interval });
     timers[methodGuid] = newTimer;
-    
+
     return newTimer;
   },