sproutit-sproutcore 1.0.0.20090407205609 → 1.0.0.20090408130025

data/frameworks/sproutcore/frameworks/runtime/system/range_observer.js

@@ -0,0 +1,99 @@
+// ==========================================================================
+// 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)
+// ==========================================================================
+
+
+/**
+  A RangeObserver is used by Arrays to automatically observe all of the
+  objects in a particular range on the array.  Whenever any property on one 
+  of those objects changes, it will notify its delegate.  Likewise, whenever
+  the contents of the array itself changes, it will notify its delegate and
+  possibly update its own registration.
+
+  This implementation uses only SC.Array methods.  It can be used on any 
+  object that complies with SC.Array.  You may, however, choose to subclass
+  this object in a way that is more optimized for your particular design.
+*/
+SC.RangeObserver = {
+  
+  create: function(source, start, length, target, method) {
+    var ret = SC.beget(this);
+    ret.source = source;
+    ret.start  = start;
+    ret.length = length;
+    ret.target = target;
+    ret.method = method;
+    ret.observing = [];
+    
+    this.beginObserving();
+    return ret ;
+  },
+  
+  extend: function(attrs) {
+    var ret = SC.beget(this), args = arguments, len = args.length, idx;
+    for(idx=0;idx<len;idx++) SC.mixin(ret, args[idx]);
+    return ret ;
+  },
+  
+  destroy: function(source) { this.endObserving(); return this; },
+  
+  update: function(source, start, length) {
+    this.start = start;
+    this.length = length;
+    this.rangeDidChange();
+    return this;
+  },
+  
+  /**
+    Configures observing for each item in the current range.  Should update
+    the observing array with the list of observed objects so they can be
+    torn down later
+  */
+  beginObserving: function() {
+    var observing = this.observing, idx = this.start, source = this.source;
+    var lim = idx + this.length, meth = this.objectPropertyDidChange, obj;
+    for(;idx<lim;idx++) {
+      obj = source.objectAt(idx);
+      if (obj && obj.addObserver) {
+        observing.push(obj);
+        obj.addObserver('*', this, meth);
+      }
+    }
+    return this;
+  },
+  
+  /**
+    Remove observers for any objects currently begin observed.  This is 
+    called whenever the observed range changes due to an array change or 
+    due to destroying the observer.
+  */
+  endObserving: function() {
+    var idx, observing = this.observing, meth = this.objectPropertyDidChange;
+    var lim = observing.length, source = this.source;
+    for(idx=0;idx<lim;idx++) {
+      observing[idx].removeObserver('*', this, meth);
+    }
+    return this ;
+  },
+  
+  /**
+    Whenever the actual objects in the range changes, notify the delegate
+    then begin observing again.
+  */
+  rangeDidChange: function() {
+    this.endObserving(); // remove old observers
+    this.method.call(this.target, this.source, null, '[]');
+    this.beginObserving(); // setup new ones
+  },
+
+  /**
+    Whenever an object changes, notify the delegate
+  */
+  objectPropertyDidChange: function(object, key) {
+    this.method.call(this.target, this.source, object, key);
+  }
+  
+};

data/frameworks/sproutcore/frameworks/runtime/system/run_loop.js

@@ -0,0 +1,214 @@
+// ==========================================================================
+// 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)
+// ==========================================================================
+
+sc_require('private/observer_set');
+
+/**
+  @class
+  
+  The run loop provides a universal system for coordinating events within
+  your application.  The run loop processes timers as well as pending 
+  observer notifications within your application.
+  
+  To use a RunLoop within your application, you should make sure your event
+  handlers always begin and end with SC.RunLoop.begin() and SC.RunLoop.end()
+  
+  The RunLoop is important because bindings do not fire until the end of 
+  your run loop is reached.  This improves the performance of your
+  application.
+  
+  h2. Example
+  
+  This is how you could write your mouseup handler in jQuery:
+  
+  {{{
+    $('#okButton').on('click', function() {
+      SC.RunLoop.begin();
+      
+      // handle click event...
+      
+      SC.RunLoop.end(); // allows bindings to trigger...
+    });
+  }}}
+  
+  @extends SC.Object
+  @since SproutCore 1.0
+*/
+SC.RunLoop = SC.Object.extend(/** @scope SC.RunLoop.prototype */ {
+  
+  /**
+    Call this method whenver you begin executing code.  
+    
+    This is typically invoked automatically for you from event handlers and 
+    the timeout handler.  If you call setTimeout() or setInterval() yourself, 
+    you may need to invoke this yourself.
+    
+    @returns {SC.RunLoop} receiver
+  */
+  beginRunLoop: function() {
+    this._start = new Date().getTime() ; // can't use Date.now() in runtime 
+    this._flushInvokeNextQueue() ; // call any invokeNext methods first
+    return this ; 
+  },
+  
+  /**
+    Call this method whenever you are done executing code.
+    
+    This is typically invoked automatically for you from event handlers and
+    the timeout handler.  If you call setTimeout() or setInterval() yourself
+    you may need to invoke this yourself.
+    
+    @returns {SC.RunLoop} receiver
+  */
+  endRunLoop: function() {
+    
+    // at the end of a runloop, flush all the delayed actions we may have 
+    // stored up.  Note that if any of these queues actually run, we will 
+    // step through all of them again.  This way any changes get flushed
+    // out completely.
+    var didChange ;
+    
+    do {
+      didChange = this.flushApplicationQueues() ;
+    } while(didChange) ;
+    this._start = null ;
+    return this ; 
+  },
+  
+  /**
+    Invokes the passed target/method pair once at the end of the runloop.
+    You can call this method as many times as you like and the method will
+    only be invoked once.  
+    
+    Usually you will not call this method directly but use invokeOnce() 
+    defined on SC.Object.
+    
+    @param {Object} target
+    @param {Function} method
+    @returns {SC.RunLoop} receiver
+  */
+  invokeOnce: function(target, method) {
+    // normalize
+    if (method === undefined) { 
+      method = target; target = this ;
+    }
+    if (SC.typeOf(method) === SC.T_STRING) method = target[method];
+    if (!this._invokeQueue) this._invokeQueue = SC._ObserverSet.create();
+    this._invokeQueue.add(target, method);
+    return this ;
+  },
+  
+  /**
+    Invokes the passed target/method pair once at the beginning of the next 
+    runloop, before any other methods (including events) are processed.
+    
+    You can call this method as many times as you like and the method will
+    only be invoked once.
+    
+    Usually you will not call this method directly but use invokeNext() 
+    defined on SC.Object.
+    
+    @param {Object} target
+    @param {Function} method
+    @returns {SC.RunLoop} receiver
+  */
+  invokeNext: function(target, method) {
+    // normalize
+    if (method === undefined) { 
+      method = target; target = this ;
+    }
+    if (SC.typeOf(method) === SC.T_STRING) method = target[method];
+    if (!this._invokeNextQueue) this._invokeNextQueue = SC._ObserverSet.create();
+    this._invokeNextQueue.add(target, method);
+    return this ;
+  },
+  
+  /**
+    Executes any pending events at the end of the run loop.  This method is 
+    called automatically at the end of a run loop to flush any pending 
+    queue changes.
+    
+    The default method will invoke any one time methods and then sync any 
+    bindings that might have changed.  You can override this method in a 
+    subclass if you like to handle additional cleanup. 
+    
+    This method must return YES if it found any items pending in its queues
+    to take action on.  endRunLoop will invoke this method repeatedly until
+    the method returns NO.  This way if any if your final executing code
+    causes additional queues to trigger, then can be flushed again.
+    
+    @returns {Boolean} YES if items were found in any queue, NO otherwise
+  */
+  flushApplicationQueues: function() {
+    var hadContent = NO ;
+    
+    // execute any methods in the invokeQueue.
+    var queue = this._invokeQueue;
+    if (queue && queue.targets > 0) {
+      this._invokeQueue = null; // reset so that a new queue will be created
+      hadContent = YES ; // needs to execute again
+      queue.invokeMethods();
+    }
+    
+    // flush any pending changed bindings.  This could actually trigger a 
+    // lot of code to execute.
+    return SC.Binding.flushPendingChanges() || hadContent ;
+  },
+  
+  _flushInvokeNextQueue: function() {
+    var queue = this._invokeNextQueue, hadContent = NO ;
+    if (queue && queue.targets > 0) {
+      this._invokeNextQueue = null; // reset queue.
+      hadContent = YES; // has targets!
+      if (hadContent) queue.invokeMethods();
+    }
+    return hadContent ;
+  }
+  
+});
+
+/** 
+  The current run loop.  This is created automatically the first time you
+  call begin(). 
+*/
+SC.RunLoop.currentRunLoop = null;
+
+/**
+  The default RunLoop class.  If you choose to extend the RunLoop, you can
+  set this property to make sure your class is used instead.
+*/
+SC.RunLoop.runLoopClass = SC.RunLoop;
+
+/** 
+  Begins a new run loop on the currentRunLoop.  If you are already in a 
+  runloop, this method has no effect.
+  
+  @returns {SC.RunLoop} receiver
+*/
+SC.RunLoop.begin = function() {    
+  var runLoop = this.currentRunLoop;
+  if (!runLoop) runLoop = this.currentRunLoop = this.runLoopClass.create();
+  runLoop.beginRunLoop();
+  return this ;
+};
+
+/**
+  Ends the run loop on the currentRunLoop.  This will deliver any final 
+  pending notifications and schedule any additional necessary cleanup.
+  
+  @returns {SC.RunLoop} receiver
+*/
+SC.RunLoop.end = function() {
+  var runLoop = this.currentRunLoop;
+  if (!runLoop) {
+    throw "SC.RunLoop.end() called outside of a runloop!";
+  }
+  runLoop.endRunLoop();
+  return this ;
+} ;
+
+

data/frameworks/sproutcore/frameworks/runtime/system/set.js

@@ -0,0 +1,246 @@
+// ==========================================================================
+// 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/enumerable') ;
+require('mixins/observable') ;
+
+/**
+  @class 
+
+  An unordered collection of objects.
+
+  A Set works a bit like an array except that its items are not ordered.  
+  You can create a set to efficiently test for membership for an object. You 
+  can also iterate through a set just like an array, even accessing objects
+  by index, however there is no gaurantee as to their order.
+
+  Note that SC.Set is a primitive object, like an array.  It does implement
+  limited key-value observing support but it does not extend from SC.Object
+  so you should not subclass it.
+
+  h1. Creating a Set
+
+  You can create a set like you would most objects using SC.Set.create() or
+  new SC.Set().  Most new sets you create will be empty, but you can also
+  initialize the set with some content by passing an array or other enumerable
+  of objects to the constructor.
+
+  Finally, you can pass in an existing set and the set will be copied.  You
+  can also create a copy of a set by calling SC.Set#clone().
+
+  {{{
+    // creates a new empty set
+    var foundNames = SC.Set.create();
+
+    // creates a set with four names in it.
+    var names = SC.Set.create(["Charles", "Peter", "Chris", "Erich"]) ;
+
+    // creates a copy of the names set.
+    var namesCopy = SC.Set.create(names);
+
+    // same as above.
+    var anotherNamesCopy = names.clone();
+  }}}
+
+  h1. Adding/Removing Objects
+
+  You generally add or removed objects from a set using add() or remove().
+  You can add any type of object including primitives such as numbers,
+  strings, and booleans.
+
+  Note that objects can only exist one time in a set.  If you call add() on
+  a set with the same object multiple times, the object will only be added 
+  once.  Likewise, calling remove() with the same object multiple times will
+  remove the object the first time and have no effect on future calls until 
+  you add the object to the set again.
+
+  Note that you cannot add/remove null or undefined to a set.  Any attempt to
+  do so will be ignored.  
+
+  In addition to add/remove you can also call push()/pop().  Push behaves just
+  like add() but pop(), unlike remove() will pick an arbitrary object, remove
+  it and return it.  This is a good way to use a set as a job queue when you
+  don't care which order the jobs are executed in.
+
+  h1. Testing for an Object
+
+  To test for an object's presence in a set you simply call SC.Set#contains().
+  This method tests for the object's hash, which is generally the same as the
+  object's _guid but if you implement the hash() method on the object, it will
+  use the return value from that method instead.
+
+  @extends Object
+  @extends SC.Enumerable 
+  @extends SC.Observable
+  @since SproutCore 0.9.15
+*/
+SC.Set = function(items) {
+  this.initObservable();
+  if (items && items.length > 0) {
+    var idx = items.get ? items.get('length') : items.length ;
+    if (items.objectAt) {
+      while(--idx >= 0) this.add(items.objectAt(idx)) ;
+    } else {
+      while(--idx >= 0) this.add(items[idx]) ;
+    }
+  }
+  return this ;
+} ;
+
+SC.Set.prototype = {
+
+  /**
+    This property will change as the number of objects in the set changes.
+
+    @type number
+  */
+  length: 0,
+
+  /**
+    Clears the set 
+  */
+  clear: function() { this.length = 0; },
+
+  /**
+    Call this method to test for membership.
+  */
+  contains: function(obj) {
+
+    // because of the way a set is "reset", the guid for an object may 
+    // still be stored as a key, but points to an index that is beyond the
+    // length.  Therefore the found idx must both be defined and less than
+    // the current length.
+    if (obj === null) return NO ;
+    var idx = this[SC.hashFor(obj)] ;
+    return (!SC.none(idx) && (idx < this.length)) ;
+  },
+
+  /**
+    Call this method to add an object. performs a basic add.
+
+    If the object is already in the set it will not be added again.
+
+    @param obj {Object} the object to add
+    @returns {Object} this
+  */
+  add: function(obj) {
+    if (SC.none(obj)) return this; // cannot add null to a set.
+
+    var guid = SC.hashFor(obj) ;
+    var idx = this[guid] ;
+    var len = this.length ;
+    if (SC.none(idx) || (idx >= len)) {
+      this[len] = obj ;
+      this[guid] = len ;
+      this.length = len+1;
+    }
+    return this ;
+  },
+
+  /**
+    Add all the items in the passed array.
+  */
+  addEach: function(objects) {
+    var idx = objects.get('length') ;
+    if (objects.objectAt) {
+      while(--idx >= 0) this.add(objects.objectAt(idx)) ;
+    } else {
+      while(--idx >= 0) this.add(objects[idx]) ;
+    }
+    return this ;
+  },  
+
+  /**
+    Removes the object from the set if it is found.
+
+    If the object is not in the set, nothing will be changed.
+
+    @param obj {Object} the object to remove
+    @returns {this} this
+  */  
+  remove: function(obj) {
+
+    if (SC.none(obj)) return this ;
+    var guid = SC.hashFor(obj);
+    var idx = this[guid] ;
+    var len = this.length;
+
+    if (SC.none(idx) || (idx >= len)) return this; // not in set.
+
+    // clear the guid key
+    delete this[guid] ;
+
+    // to clear the index, we will swap the object stored in the last index.
+    // if this is the last object, just reduce the length.
+    if (idx < (len-1)) {
+      obj = this[idx] = this[len-1];
+      this[SC.hashFor(obj)] = idx ;
+    }
+
+    // reduce the length
+    this.length = len-1;
+    return this ;
+  },
+
+  /**
+    Removes an arbitrary object from the set and returns it.
+
+    @returns {Object} an object from the set or null
+  */
+  pop: function() {
+    var obj = (this.length > 0) ? this[this.length-1] : null ;
+    if (obj) this.remove(obj) ;
+    return obj ;
+  },
+
+  /**
+    Removes all the items in the passed array.
+  */
+  removeEach: function(objects) {
+    var idx = objects.get('length') ;
+    if (objects.objectAt) {
+      while(--idx >= 0) this.remove(objects.objectAt(idx)) ;
+    } else {
+      while(--idx >= 0) this.remove(objects[idx]) ;
+    }
+    return this ;
+  },  
+
+  /**
+   Clones the set into a new set.  
+  */
+  clone: function() {
+    return SC.Set.create(this);    
+  },
+
+  // .......................................
+  // PRIVATE 
+  //
+  _each: function(iterator) {
+    var len = this.length ;
+    for(var idx=0;idx<len;idx++) iterator(this[idx]) ;
+  },
+
+  toString: function() {
+    return "SC.Set<%@>".fmt(SC.$A(this)) ;
+  }  
+
+} ;
+
+SC.Set.prototype.slice = SC.Set.prototype.clone ;
+
+// Make this enumerable and observable
+SC.mixin(SC.Set.prototype, SC.Enumerable, SC.Observable) ;
+
+SC.Set.prototype.push = SC.Set.prototype.unshift = SC.Set.prototype.add ;
+SC.Set.prototype.shift = SC.Set.prototype.pop ;
+
+
+/**
+  To create a set, pass an array of items instead of a hash.
+*/
+SC.Set.create = function(items) { return new SC.Set(items); };