sproutit-sproutcore 1.0.0.20090407205609 → 1.0.0.20090408130025

data/frameworks/sproutcore/frameworks/runtime/private/chain_observer.js

@@ -0,0 +1,135 @@
+// ==========================================================================
+// Project:   SproutCore Costello - Property Observing Library
+// Copyright: ©2006-2009 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2009 Apple, Inc. All rights reserved.
+// License:   Licened under MIT license (see license.js)
+// ==========================================================================
+
+require('system/object');
+
+// ........................................................................
+// CHAIN OBSERVER
+//
+
+// This is a private class used by the observable mixin to support chained
+// properties.
+
+// ChainObservers are used to automatically monitor a property several 
+// layers deep.
+// org.plan.name = SC._ChainObserver.create({
+//    target: this, property: 'org',
+//    next: SC._ChainObserver.create({
+//      property: 'plan',
+//      next: SC._ChainObserver.create({
+//        property: 'name', func: myFunc
+//      })
+//    })
+//  })
+//
+SC._ChainObserver = function(property) {
+  this.property = property ;
+} ;
+
+// This is the primary entry point.  Configures the chain.
+SC._ChainObserver.createChain = function(rootObject, path, target, method) {
+
+  var parts = path.split('.') ;
+  
+  // First we create the chain.
+  var root ;
+  var tail = root = new SC._ChainObserver(parts[0]) ;
+  var len = parts.length;
+  for(var idx=1;idx<len;idx++) {
+    tail = tail.next = new SC._ChainObserver(parts[idx]) ;
+  }
+  
+  // Now root has the first observer and tail has the last one.
+  // Feed the rootObject into the front to setup the chain...
+  // do this BEFORE we set the target/method so they will not be triggered.
+  root.objectDidChange(rootObject);
+  
+  // Finally, set the target/method on the tail so that future changes will
+  // trigger.
+  tail.target = target; tail.method = method ;
+  
+  // and return the root to save
+  return root ;
+};
+
+SC._ChainObserver.prototype = {
+  isChainObserver: true,
+  
+  // the object this instance is observing
+  object: null,
+  
+  // the property on the object this link is observing.
+  property: null,
+  
+  // if not null, this is the next link in the chain.  Whenever the 
+  // current property changes, the next observer will be notified.
+  next: null,
+  
+  // if not null, this is the final target observer.
+  target: null,
+  
+  // if not null, this is the final target method
+  method: null,
+  
+  // invoked when the source object changes.  removes observer on old 
+  // object, sets up new observer, if needed.
+  objectDidChange: function(newObject) {
+    if (newObject === this.object) return; // nothing to do.
+    
+    // if an old object, remove observer on it.
+    if (this.object && this.object.removeObserver) {
+      this.object.removeObserver(this.property, this, this.propertyDidChange);
+    }
+    
+    // if a new object, add observer on it...
+    this.object = newObject ;
+    if (this.object && this.object.addObserver) {
+      this.object.addObserver(this.property, this, this.propertyDidChange); 
+    }
+    
+    // now, notify myself that my property value has probably changed.
+    this.propertyDidChange() ;
+  },
+  
+  // the observer method invoked when the observed property changes.
+  propertyDidChange: function() {
+    
+    // get the new value
+    var object = this.object ;
+    var property = this.property ;
+    var value = (object && object.get) ? object.get(property) : null ;
+    
+    // if we have a next object in the chain, notify it that its object 
+    // did change...
+    if (this.next) this.next.objectDidChange(value) ;
+    
+    // if we have a target/method, call it.
+    var target = this.target; var method = this.method;
+    if (target && method) {
+      var rev = object.propertyRevision ;
+      method.call(target, object, property, value, rev) ;
+    } 
+  },
+  
+  // teardown the chain...
+  destroyChain: function() {
+    
+    // remove observer
+    var obj = this.object ;
+    if (obj && obj.removeObserver) {
+      obj.removeObserver(this.property, this, this.propertyDidChange) ;
+    }  
+    
+    // destroy next item in chain
+    if (this.next) this.next.destroyChain() ;
+    
+    // and clear left overs...
+    this.next = this.target = this.method = this.object = null ;
+    return null ;
+  }
+  
+} ;

data/frameworks/sproutcore/frameworks/runtime/private/observer_queue.js

@@ -0,0 +1,108 @@
+// ==========================================================================
+// Project:   SproutCore Costello - Property Observing Library
+// Copyright: ©2006-2009 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2009 Apple, Inc. All rights reserved.
+// License:   Licened under MIT license (see license.js)
+// ==========================================================================
+
+require('mixins/observable');
+require('system/set');
+
+/**
+  The private ObserverQueue is used to maintain a set of pending observers. 
+  This allows you to setup an observer on an object before the object exists.
+  
+  Whenever the observer fires, the queue will be flushed to connect any 
+  pending observers.
+*/
+// ........................................................................
+// OBSERVER QUEUE
+//
+// This queue is used to hold observers when the object you tried to observe
+// does not exist yet.  This queue is flushed just before any property 
+// notification is sent.
+SC.Observers = {
+  queue: [],
+  
+  // Attempt to add the named observer.  If the observer cannot be found, put
+  // it into a queue for later.
+  addObserver: function(propertyPath, target, method, pathRoot) {
+    var tuple ;
+
+    // try to get the tuple for this.
+    if (SC.typeOf(propertyPath) === SC.T_STRING) {
+      tuple = SC.tupleForPropertyPath(propertyPath, pathRoot) ;
+    } else {
+      tuple = propertyPath; 
+    }
+
+    // if a tuple was found, add the observer immediately...
+    if (tuple) {
+      tuple[0].addObserver(tuple[1],target, method) ;
+      
+    // otherwise, save this in the queue.
+    } else {
+      this.queue.push([propertyPath, target, method, pathRoot]) ;
+    }
+  },
+
+  // Remove the observer.  If it is already in the queue, remove it.  Also
+  // if already found on the object, remove that.
+  removeObserver: function(propertyPath, target, method, pathRoot) {
+    var idx, queue, tuple, item;
+    
+    tuple = SC.tupleForPropertyPath(propertyPath, pathRoot) ;
+    if (tuple) {
+      tuple[0].removeObserver(tuple[1], target, method) ;
+    } 
+
+    idx = this.queue.length; queue = this.queue ;
+    while(--idx >= 0) {
+      item = queue[idx] ;
+      if ((item[0] === propertyPath) && (item[1] === target) && (item[2] == method) && (item[3] === pathRoot)) queue[idx] = null ;
+    }
+  },
+  
+  // Flush the queue.  Attempt to add any saved observers.
+  flush: function() {
+    var oldQueue = this.queue ;
+    var newQueue = (this.queue = []) ; 
+    var idx = oldQueue.length ;
+    while(--idx >= 0) {
+      var item = oldQueue[idx] ;
+      if (!item) continue ;
+      
+      var tuple = SC.tupleForPropertyPath(item[0], item[3]);
+      if (tuple) {
+        tuple[0].addObserver(tuple[1], item[1], item[2]) ;
+      } else newQueue.push(item) ;
+    }
+  },
+  
+  isObserveringSuspended: 0,
+  _pending: SC.Set.create(),
+  
+  objectHasPendingChanges: function(obj) {
+    this._pending.add(obj) ; // save for later
+  },
+
+  // temporarily suspends all property change notifications.
+  suspendPropertyObserving: function() {
+    this.isObservingSuspended++ ;
+  },
+  
+  // resume change notifications.  This will call notifications to be
+  // delivered for all pending objects.
+  resumePropertyObserving: function() {
+    var pending ;
+    if(--this.isObservingSuspended <= 0) {
+      pending = this._pending ;
+      this._pending = SC.Set.create() ;
+      while(pending.length > 0) {
+        pending.pop()._notifyPropertyObservers() ;
+      }
+      pending = null ;
+    }
+  }
+  
+} ;

data/frameworks/sproutcore/frameworks/runtime/private/observer_set.js

@@ -0,0 +1,128 @@
+// ==========================================================================
+// Project:   SproutCore Costello - Property Observing Library
+// Copyright: ©2006-2009 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2009 Apple, Inc. All rights reserved.
+// License:   Licened under MIT license (see license.js)
+// ==========================================================================
+
+// ........................................................................
+// ObserverSet
+//
+// This private class is used to store information about obversers on a 
+// particular key.  Note that this object is not observable.  You create new
+// instances by calling SC.beget(SC._ObserverSet) ;
+//
+SC._ObserverSet = {
+
+  // the number of targets in the set.
+  targets: 0,
+  
+  _membersCacheIsValid: NO,
+  
+  // adds the named target/method observer to the set.  The method must be
+  // a function, not a string..
+  add: function(target, method) {
+    var targetGuid = (target) ? SC.guidFor(target) : "__this__";
+    
+    // get the set of methods
+    var methods = this[targetGuid] ;
+    if (!methods) {
+      methods = this[targetGuid] = SC.Set.create() ;
+      methods.target = target ;
+      methods.isTargetSet = YES ; // used for getMembers().
+      this.targets++ ;
+    }
+    
+    methods.add(method) ;
+    this._membersCacheIsValid = NO ;
+  },
+  
+  // removes the named target/method observer from the set.  If this is the
+  // last method for the named target, then the number of targets will also
+  // be reduced.
+  //
+  // returns YES if the items was removed, NO if it was not found.
+  remove: function(target, method) {
+    var targetGuid = (target) ? SC.guidFor(target) : "__this__";
+    
+    // get the set of methods
+    var methods = this[targetGuid] ;    
+    if (!methods) return NO ;
+    
+    methods.remove(method) ;
+    if (methods.length <= 0) {
+      methods.target = null;
+      methods.isTargetSet = NO ;
+      delete this[targetGuid] ;
+      this.targets-- ;
+    }
+    
+    this._membersCacheIsValid = NO;
+    
+    return YES ;
+  },
+  
+  // Invokes the target/method pairs in the receiver.  Used by SC.RunLoop
+  invokeMethods: function() {
+    // iterate through the set, look for sets.
+    for(var key in this) {
+      if (!this.hasOwnProperty(key)) continue ;
+      var value = this[key] ;
+      if (value && value.isTargetSet) {
+        var idx = value.length;
+        var target = value.target ;
+        while(--idx>=0) value[idx].call(target);
+      }
+    }
+  },
+  
+  // Returns an array of target/method pairs.  This is cached.
+  getMembers: function() {
+    if (this._membersCacheIsValid) return this._members ;
+    
+    // need to recache, reset the array...
+    if (!this._members) {
+      this._members = [] ;
+    } else this._members.length = 0 ; // reset
+    var ret = this._members ;
+
+    // iterate through the set, look for sets.
+    for(var key in this) {
+      if (!this.hasOwnProperty(key)) continue ;
+      var value = this[key] ;
+      if (value && value.isTargetSet) {
+        var idx = value.length;
+        var target = value.target ;
+        while(--idx>=0) ret.push([target, value[idx]]) ;
+      }
+    }
+
+    this._membersCacheIsValid = YES ;
+    return ret ;
+  },
+  
+  // Returns a new instance of the set with the contents cloned.
+  clone: function() {
+    var oldSet, newSet, key, ret = SC._ObserverSet.create() ;
+    for(key in this) {
+      if (!this.hasOwnProperty(key)) continue ;
+      oldSet = this[key];
+      if (oldSet && oldSet.isTargetSet) {
+        newSet = oldSet.clone();
+        newSet.target = oldSet.target ;
+        ret[key] = newSet ;
+      }
+    }
+    ret.targets = this.targets ;
+    ret._membersCacheIsValid = NO ;
+    return ret ;
+  },
+  
+  // Creates a new instance of the observer set.
+  create: function() { return SC.beget(this); }
+  
+} ;
+
+SC._ObserverSet.slice = SC._ObserverSet.clone ;
+
+

data/frameworks/sproutcore/frameworks/runtime/protocols/sparse_array_delegate.js

@@ -0,0 +1,131 @@
+// ==========================================================================
+// Project:   SproutCore Costello - Property Observing Library
+// Copyright: ©2006-2009 Sprout Systems, Inc. and contributors.
+//            Portions ©2008-2009 Apple, Inc. All rights reserved.
+// License:   Licened under MIT license (see license.js)
+// ==========================================================================
+
+/** @namespace
+
+  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.
+  
+  Your object does not need to implement all of these methods, but it should 
+  at least implment the sparseArrayDidRequestIndex() method.
+
+  @since SproutCore 1.0
+*/
+SC.SparseArrayDelegate = {
+  
+  /**
+    Invoked when an object requests the length of the sparse array and the 
+    length has not yet been set.  You can implement this method to update 
+    the length property of the sparse array immediately or at a later time
+    by calling the provideLength() method on the sparse array.
+    
+    This method will only be called once on your delegate unless you 
+    subsequently call provideLength(null) on the array, which will effectively
+    "empty" the array and cause the array to invoke the delegate again the
+    next time its length is request.
+    
+    If you do not set a length on the sparse array immediately, it will return
+    a length of 0 until you provide the length.
+    
+    @param {SC.SparseArray} sparseArray the array that needs a length.
+    @returns {void}
+  */
+  sparseArrayDidRequestLength: function(sparseArray) {
+    // Default does nothing.
+  },
+  
+  /**
+    Invoked when an object requests an index on the sparse array that has not
+    yet been set.  You should implement this method to set the object at the
+    index using provideObjectsAtIndex() or provideObjectsInRange() on the 
+    sparse array.  You can call these methods immediately during this handler
+    or you can wait and call them at a later time once you have loaded any 
+    data.
+    
+    This method will only be called when an index is requested on the sparse
+    array that has not yet been filled.  If you have filled an index or range
+    and you would like to reset it, call the objectsDidChangeInRange() method
+    on the sparse array.
+    
+    Note that if you implement the sparseArrayDidRequestRange() method, that
+    method will be invoked instead of this one whenever possible to allow you
+    to fill in the array with the most efficiency possible.
+    
+    @param {SC.SparseArray} sparseArray the sparse array
+    @param {Number} index the requested index
+    @returns {void}
+  */
+  sparseArrayDidRequestIndex: function(sparseArray, index) {
+    
+  },
+  
+  /**
+    Alternative method invoked when an object requests an index on the 
+    sparse array that has not yet been set.  If you set the 
+    rangeWindowSize property on the Sparse Array, then all object index 
+    requests will be expanded to to nearest range window and then this 
+    method will be called with that range.
+    
+    You should fill in the passed range by calling the provideObjectsInRange()
+    method on the sparse array.
+    
+    If you do not implement this method but set the rangeWindowSize anyway,
+    then the sparseArrayDidRequestIndex() method will be invoked instead.
+  
+    Note that the passed range is a temporary object.  Be sure to clone it if
+    you want to keep the range for later use.
+    
+    @param {SC.SparseArray} sparseArray the sparse array
+    @param {Range} range read only range.
+    @returns {void}
+  */
+  sparseArrayDidRequestRange: function(sparseArray, range) {
+    
+  },
+  
+  /**
+    Optional delegate method you can use to determine the index of a 
+    particular object.  If you do not implement this method, then the 
+    sparse array will just search the objects it has loaded already.
+    
+    @param {SC.SparseArray} sparseArray the sparse array
+    @param {Object} object the object to find the index of
+    @return {Number} the index or -1
+    @returns {void}
+  */
+  sparseArrayDidRequestIndexOf: function(sparseArray, object) {
+    
+  },
+  
+  /**
+    Optional delegate method invoked whenever the sparse array attempts to 
+    changes its contents.  If you do not implement this method or if you 
+    return NO from this method, then the edit will not be allowed.
+    
+    @param {SC.SparseArray} sparseArray the sparse array
+    @param {Number} idx the starting index to replace
+    @param {Number} amt the number if items to replace
+    @param {Array} objects the array of objects to insert
+    @returns {Boolean} YES to allow replace, NO to deny
+  */
+  sparseArrayShouldReplace: function(sparseArray, idx, amt, objects) {
+    return NO ;
+  },
+  
+  /**
+    Invoked whenever the sparse array is reset.  Resetting a sparse array 
+    will cause it to flush its content and go back to the delegate for all
+    property requests again.
+    
+    @param {SC.SparseArray} sparseArray the sparse array
+    @returns {void}
+  */
+  sparseArrayDidReset: function(sparseArray) { 
+  }
+};