sproutit-sproutcore 1.0.20090721145236 → 1.0.20090721145251

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

@@ -0,0 +1,141 @@
+// ==========================================================================
+// 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, context) {
+
+  // First we create the chain.
+  var parts = path.split('.'),
+      root  = new SC._ChainObserver(parts[0]),
+      tail  = root,
+      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 ; tail.context = context ;
+  
+  // 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,
+        method  = this.method,
+        context = this.context ;
+    if (target && method) {
+      var rev = object ? object.propertyRevision : null ;
+      if (context) {
+        method.call(target, object, property, value, context, rev);
+      } else {
+        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 = this.context = null;
+    return null ;
+  }
+  
+} ;

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

@@ -0,0 +1,148 @@
+// ==========================================================================
+// 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 ;
+    }
+  },
+  
+  // Range Observers register here to indicate that they may potentially 
+  // need to start observing.
+  addPendingRangeObserver: function(observer) {
+    var ro = this.rangeObservers;
+    if (!ro) ro = this.rangeObservers = SC.CoreSet.create();
+    ro.add(observer);
+    return this ;
+  },
+  
+  _TMP_OUT: [],
+  
+  // Flush the queue.  Attempt to add any saved observers.
+  flush: function(object) { 
+       
+    // flush any observers that we tried to setup but didn't have a path yet
+    var oldQueue = this.queue ;
+    if (oldQueue && oldQueue.length > 0) {
+      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) ;
+      }
+    }
+    
+    // if this object needsRangeObserver then see if any pending range 
+    // observers need it.
+    if (object._kvo_needsRangeObserver) {
+      var set = this.rangeObservers,
+          len = set ? set.get('length') : 0,
+          out = this._TMP_OUT,
+          ro;
+          
+      for(idx=0;idx<len;idx++) {
+        ro = set[idx]; // get the range observer
+        if (ro.setupPending(object)) {
+          out.push(ro); // save to remove later
+        }
+      }
+      
+      // remove any that have setup
+      if (out.length > 0) set.removeEach(out);
+      out.length = 0; // reset
+      object._kvo_needsRangeObserver = NO ;
+    }
+    
+  },
+  
+  isObservingSuspended: 0,
+  _pending: SC.CoreSet.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.CoreSet.create() ;
+      
+      var idx, len = pending.length;
+      for(idx=0;idx<len;idx++) {
+        pending[idx]._notifyPropertyObservers() ;
+      }
+      pending.clear();
+      pending = null ;
+    }
+  }
+  
+} ;

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

@@ -0,0 +1,152 @@
+// ==========================================================================
+// 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, context) {
+    var targetGuid = (target) ? SC.guidFor(target) : "__this__";
+    
+    // get the set of methods
+    var methods = this[targetGuid] ;
+    if (!methods) {
+      methods = this[targetGuid] = SC.CoreSet.create() ;
+      methods.target = target ;
+      methods.isTargetSet = YES ; // used for getMembers().
+      this.targets++ ;
+    }
+    methods.add(method) ;
+    
+    // context is really useful sometimes but not used that often so this
+    // implementation is intentionally lazy.
+    if (context !== undefined) {
+      var contexts = methods.contexts ;
+      if (!context) contexts = {};
+      contexts[SC.guidFor(method)] = context ;
+    }
+    
+    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 ;
+      methods.contexts = null ;
+      delete this[targetGuid] ;
+      this.targets-- ;
+      
+    } else if (methods.contexts) {
+      delete methods.contexts[SC.guidFor(method)];
+    }
+
+    this._membersCacheIsValid = NO;
+    
+    return YES ;
+  },
+  
+  // Invokes the target/method pairs in the receiver.  Used by SC.RunLoop
+  // Note: does not support context
+  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 ;
+        
+        // slightly slower - only do if we have contexts
+        var contexts = value.contexts ;
+        if (contexts) {
+          while(--idx>=0) {
+            var method = value[idx] ;
+            ret.push([target, method, contexts[SC.guidFor(method)]]) ;
+          }
+        } else {
+          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 ;
+        if (oldSet.contexts) newSet.contexts = SC.clone(oldSet.contexts);
+        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/observable_protocol.js

@@ -0,0 +1,40 @@
+// ==========================================================================
+// 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)
+// ==========================================================================
+
+/**
+  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.
+*/
+SC.ObservableProtocol = {
+  
+  /**  
+    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
+    handle requests yourself.  Although this observer will be triggered 
+    more often than an observer registered on a specific property, it also
+    does not need to be registered which can make it faster to setup your 
+    object instance.
+    
+    You will often implement this observer using a switch statement on the
+    key parameter, taking appropriate action. 
+    
+    @param observer {null} no longer used; usually null
+    @param target {Object} the target of the change.  usually this
+    @param key {String} the name of the property that changed
+    @param value {Object} the new value of the property.
+    @param revision {Number} a revision you can use to quickly detect changes.
+    @returns {void}
+  */
+  propertyObserver: function(observer,target,key,value, revision) {
+    
+  }
+  
+};