sproutcore 0.9.1 → 0.9.2

data/frameworks/sproutcore/foundation/application.js

@@ -1,18 +1,22 @@
 require('Core');
 require('foundation/responder');
 
-/**
-* The SC.Application object manages a SproutCore application. 
-* A single instance is created and placed in a global variable named SC.app.
-* All events and actions are routed through this object.
-* @class
-* @constructor
-* @extends SC.Responder
-* @author Skip Baney
-* @copyright 2006-2007, Sprout Systems, Inc. and contributors.
-* @version 0.1
+/** 
+
+  @class
+
+  The SC.Application object manages a SproutCore application. A single 
+  instance is created and placed in a global variable named SC.app. All events 
+  and actions are routed through this object.
+ 
+  
+  @extends SC.Responder
+  @author Skip Baney
+  @copyright 2006-2008, Sprout Systems, Inc. and contributors.
+  @version 0.1
 */
-SC.Application = SC.Responder.extend( /** @scope SC.Application.prototype */ {
+SC.Application = SC.Responder.extend( 
+/** @scope SC.Application.prototype */ {
   
   /**
   * The pane that is currently receiving key events.

data/frameworks/sproutcore/foundation/benchmark.js

@@ -1,6 +1,6 @@
 // ========================================================================
 // SproutCore
-// copyright 2006-2007 Sprout Systems, Inc.
+// copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
 require('Core') ;

data/frameworks/sproutcore/foundation/binding.js

@@ -1,6 +1,6 @@
 // ========================================================================
 // SproutCore
-// copyright 2006-2007 Sprout Systems, Inc.
+// copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
 require('foundation/object') ;
@@ -216,7 +216,7 @@ SC.Binding.mixin({
 // of properties.  The second param is a set of properties.  Both are opt.
 SC.Binding.From = function(from,opts) {
   if (!opts) opts = {} ;
-  if ((typeof(from) == "string") || (from instanceof Array)) {
+  if (($type(from) == T_STRING) || ($type(from) == T_ARRAY)) {
     opts.from = from ;
   } else Object.extend(opts,from) ;
   var ret = SC.Binding.extend(opts) ; 

data/frameworks/sproutcore/foundation/date.js

@@ -1,6 +1,6 @@
 // ========================================================================
 // SproutCore
-// copyright 2006-2007 Sprout Systems, Inc.
+// copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
 // Extensions to the Date object. Comes from JavaScript Toolbox at:

data/frameworks/sproutcore/foundation/error.js

@@ -1,6 +1,6 @@
 // ========================================================================
 // SproutCore
-// copyright 2006-2007 Sprout Systems, Inc.
+// copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
 require('foundation/object');

data/frameworks/sproutcore/foundation/input_manager.js

@@ -1,30 +1,39 @@
 // ========================================================================
 // SproutCore
-// copyright 2006-2007 Sprout Systems, Inc.
+// copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
 require('Core') ;
 require('foundation/object') ;
 
-// An InputManager knows how to convert incoming keyboard events and convert
-// them into actions on a responder.  The default version should provide the
-// correct behavior for most people.  However, if you want some special
-// behavior, you can always write your own.
-//
-// An instance of this input manager is created as a property of
-// SC.Responder.  To overide the inputManager used for all responders, replace
-// this property with your own instance.  To override the inputManager used 
-// only for one responder, set the inputManager property on your specific 
-// instance.
-//
-// Note that generally you do not want to write your own inputManager.  They
-// are tricky to get right.  Instead, you should implement the various handler
-// methods on the responder.
-SC.InputManager = SC.Object.extend({
+/** @class
+
+  An InputManager knows how to convert incoming keyboard events and convert
+  them into actions on a responder.  The default version should provide the
+  correct behavior for most people.  However, if you want some special
+  behavior, you can always write your own.
+
+  An instance of this input manager is created as a property of
+  SC.Responder.  To overide the inputManager used for all responders, replace
+  this property with your own instance.  To override the inputManager used 
+  only for one responder, set the inputManager property on your specific 
+  instance.
+
+  Note that generally you do not want to write your own inputManager.  They
+  are tricky to get right.  Instead, you should implement the various handler
+  methods on the responder.
+  
+  @extends SC.Object
+  @author Charles Jolley
+*/
+SC.InputManager = SC.Object.extend(
+/** @scope SC.InputManager.prototype */ {
   
-  // The is the primary entry point for the inputManager.  If you override
-  // the input manager, have this method process the key event and invoke
-  // methods on the responder. 
+  /**
+    The is the primary entry point for the inputManager.  If you override
+    the input manager, have this method process the key event and invoke
+    methods on the responder. 
+  */
   interpretKeyEvents: function(event, responder)
   {
     var codes = this.codesForEvent(event) ;
@@ -50,8 +59,10 @@ SC.InputManager = SC.Object.extend({
     return false ; //nothing to do.
   },
   
-  // this will get a standardized command code for the event.  It returns
-  // null if the event is plain text, not a command code.
+  /**
+    this will get a standardized command code for the event.  It returns
+    null if the event is plain text, not a command code.
+  */  
   codesForEvent: function(e) {
     var code = e.keyCode ;
     var ret = null ; var key = null ;

data/frameworks/sproutcore/foundation/mock.js

@@ -4,7 +4,7 @@ require('foundation/object');
 /**
   @namespace Mocks for unit testing
   @author Skip Baney
-  @copyright 2006-2007, Sprout Systems, Inc. and contributors.
+  @copyright 2006-2008, Sprout Systems, Inc. and contributors.
   @version 0.1
   
   Mock objects provide basic support for unit testing.  Look for subclasses.

data/frameworks/sproutcore/foundation/node_descriptor.js

@@ -1,15 +1,18 @@
 // ========================================================================
 // SproutCore
-// copyright 2006-2007 Sprout Systems, Inc.
+// copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
 require('Core') ;
 
-// This object can generate HTML DOM elements from a hash-based description of 
-// the nodes.  See the NodeDescriptor wiki page for complete docs.
-//
-// See https://wiki.sproutit.com/engineering/show/NodeDescriptor 
-//
+/**
+  This object can generate HTML DOM elements from a hash-based description of 
+  the nodes.  See the NodeDescriptor wiki page for complete docs.
+
+  See https://wiki.sproutit.com/engineering/show/NodeDescriptor 
+
+  @deprecated
+*/
 SC.NodeDescriptor = {
   create: function(descriptor, opts) {
     if (!opts) opts = {} ;

data/frameworks/sproutcore/foundation/object.js

@@ -1,31 +1,52 @@
 // ========================================================================
 // SproutCore
-// copyright 2006-2007 Sprout Systems, Inc.
+// copyright 2006-2008 Sprout Systems, Inc.
 // ========================================================================
 
 require('Core') ;
 require('foundation/benchmark') ;
-require('foundation/observable') ;
+require('mixins/observable') ;
+require('mixins/array') ;
 
 SC.BENCHMARK_OBJECTS = NO;
 
 /** 
-  @class Root Object for SproutCore framework.
+  @class 
+
+  Root Object for the SproutCore Framework
+  
+  h2. Class at a Glance
+  
+  Add a one or two paragraph description of the class here.
   
   This is the root object of the SproutCore framework.  All other objects
   inherit from you.  SC.Object among other things implements support for
   class inheritance, observers, and bindings.  You should use SC.Object to
   create your own subclasses as well.
+
+  h2. Overview
   
+  Some overview information about the class should go here.
   Please see online documentation for more information about this.
+
+  h2. Subclassing Notes
   
   I should be able to put a long list of things here I suppose.
   
-  Do bullet
-  points
-  work?
+  - Do bullet
+  - points
+  - work?
+  
+  {{{
+    // Also some sample
+    code.goesHere() ;
+  }}}
   
   @extends SC.Observable 
+  @author Charles Jolley
+  @version 1.0
+  @since Version 1.0
+
 */
 SC.Object = function(noinit) { 
 	if (noinit == SC.Object._noinit_) return ;
@@ -33,12 +54,18 @@ SC.Object = function(noinit) {
   return ret ;
 };
 
-Object.extend(SC.Object, {
+Object.extend(SC.Object, 
+/** @scope SC.Object */ {
 
 	_noinit_: '__noinit__',
 	
-  // Use this to add class methods to an object.
-  mixin: function() {
+  /**
+    Add properties to a object's class definition.
+    
+    @params {Hash} props the properties you want to add
+    @returns {void}
+  */
+  mixin: function(props) {
     var ext = $A(arguments) ;
     for(var loc=0;loc<ext.length;loc++) {
       Object.extend(this,ext[loc]);
@@ -46,9 +73,14 @@ Object.extend(SC.Object, {
     return this ;
   },
   
-  // this will created a new version of the passed object, updating the 
-  // prototype to use the new code.
-  extend: function() {   
+  /**
+    Creates a new subclass, add to the receiver any passed properties
+    or methods.
+    
+    @params {Hash} props the methods of properties you want to add
+    @returns {Class} A new object class
+  */
+  extend: function(props) {   
     
     if (SC.BENCHMARK_OBJECTS) SC.Benchmark.start('SC.Object.extend') ;
      
@@ -78,20 +110,51 @@ Object.extend(SC.Object, {
     
     return ret ;
   },
-  
-  // create a new instance of the object.
-  create: function() {
+
+  /**
+    Creates a new instance of the class.
+
+    Unlike most frameworks, you do not pass paramters into the init funciton
+    for an object.  Instead, you pass a hash of additonal properties you want
+    to have assigned to the object when it is first created.  This is
+    functionally like creating a anonymous subclass of the receiver and then
+    instantiating it, but more efficient.
+    
+    You can use create() like you would a normal constructor in a class-based
+    system, or you can use it to create highly customized singleton objects
+    such as controllers or app-level objects.  This is often more efficient
+    than creating subclasses and than instantiating them.
+    
+    @param {Hash} props optional hash of method or properties to add to the instance.
+    @returns {SC.Object} new instance of the receiver class.
+  */
+  create: function(props) {
     var ret = new this($A(arguments),this) ;
     return ret ;
   },
     
-  // takes an array of configs and returns instances of each object.
+  /**
+    Takes an array of hashes and returns newly created instances.
+    
+    This convenience method will take an array of properties and simply
+    instantiates objects from them.
+    
+    @params {Array} array Array of hashes with properties to assigned to each object.
+    @returns {Array} array of instantiated objects.
+  */
   createArray: function(array) {
     var obj = this ;
     return array.map(function(props) { return obj.create(props); }) ;
   },
 
-  // configure this object as an outlet
+  /**
+    Adding this function to the end of a view declaration will define the 
+    class as an outlet that can be constructed using the outlet() method 
+    (instead of get()).
+    
+    @returns {Outlet} a specially constructed function that will be used to
+     build the outlet later.
+  */
   outlet: function() {
     var obj = this ;
     return function() {
@@ -99,7 +162,74 @@ Object.extend(SC.Object, {
     } ;
   },
   
-  isClass: true,
+  /**
+    Alway YES since this is a class.
+  */
+  isClass: YES,
+  
+  /**
+    Returns the name of this class.  If the name is not known, triggers
+    a search.  This can be expensive the first time it is called.
+  */
+  objectClassName: function() {
+    if (!this._objectClassName) this._findObjectClassNames() ;
+    if (this._objectClassName) return this._objectClassName ;
+    var ret = this ;
+    while(ret && !ret._objectClassName) ret = ret._type; 
+    return (ret._objectClassName) ? ret._objectClassName : 'Anonymous' ;
+  },
+
+  /** @private
+    This is a way of performing brute-force introspection.  This searches 
+    through all the top-level properties looking for classes.  When it finds
+    one, it saves the class path name.
+  */
+  _findObjectClassNames: function() {
+    
+    if (SC._foundObjectClassNames) return ;
+    SC._foundObjectClassNames = true ;
+    
+    var seen = [] ;
+    var searchObject = function(root, object, levels) {
+      levels-- ;
+
+      // not the fastest, but safe
+      if (seen.indexOf(object) >= 0) return ;
+      seen.push(object) ;
+
+      for(var key in object) {
+        if (key == '__scope__') continue ;
+        if (key == '_type') continue ;
+        if (!key.match(/^[A-Z0-9]/)) continue ;
+
+        var path = (root) ? [root,key].join('.') : key ;
+        var value = object[key] ;
+
+
+        switch($type(value)) {
+        case T_CLASS:
+          if (!value._objectClassName) value._objectClassName = path;
+          if (levels>=0) searchObject(path, value, levels) ;
+          break ;
+
+        case T_OBJECT:
+          if (levels>=0) searchObject(path, value, levels) ;
+          break ;
+
+        case T_HASH:
+          if (((root != null) || (path=='SC')) && (levels>=0)) searchObject(path, value, levels) ;
+          break ;
+
+        default:
+          break;
+        }
+      }
+    } ;
+    
+    searchObject(null, window, 2) ;
+  },
+  
+  toString: function() { return this.objectClassName(); },
   
   // ..........................................
   // PROPERTY SUPPORT METHODS
@@ -162,7 +292,7 @@ Object.extend(SC.Object, {
     var concats = {} ;
     if (cprops) for(var cloc=0;cloc<cprops.length;cloc++) {
       var p = cprops[cloc]; var p1 = base[p]; var p2 = ext[p] ;
-      p1 = (p1 && p2) ? p1.concat(p2) : (p1 || p2) ;
+      p1 = (p1 && p2) ? Array.from(p1).concat(p2) : (p1 || p2) ;
       concats[p] = p1 ;
     }
     
@@ -213,8 +343,6 @@ Object.extend(SC.Object, {
     return base ;
   },
   
-  toString: function() { return 'Object('+ SC.getGUID(this) +')'; },
-  
   // Returns true if the receiver is a subclass of the named class.  If the
   // receiver is the class passed, this will return false.  See kindOf().
   subclassOf: function(scClass) {
@@ -262,16 +390,33 @@ SC.report = function() {
 // 
 SC.Object.prototype = {
   
+  /**
+    Always YES since this is an object and not a class.
+  */
   isObject: true,
   
-  respondsTo: function( name )
+  /**
+    Returns YES if the named value is an executable function.
+    
+    @param methodName {String} the property name to check
+    @returns {Boolean}
+  */
+  respondsTo: function( methodName )
   {
-    return !!(name && this[name] && ($type(this[name]) == T_FUNCTION));
+    return !!(methodName && this[methodName] && ($type(this[methodName]) == T_FUNCTION));
   },
   
-  tryToPerform: function( name, args )
+  /**
+    If the passed property is a method, then it will be executed with the
+    passed arguments.  Otherwise, returns NO.
+    
+    @param methodName {String} the method name to try to perform.
+    @param args {*arguments} arbitrary arguments to pass along to the method.
+    @returns {Object} NO if method could not be performed or method result.
+  */
+  tryToPerform: function( methodName, args )
   {
-    if ( !name ) return false;
+    if ( !methodName ) return false;
     
     var args = $A(arguments);
     var name = args.shift();
@@ -376,12 +521,25 @@ SC.Object.prototype = {
       }
     }
 
+    // Call 'initMixin' methods to automatically setup modules.
+    if (this.initMixin) {
+      var inc = Array.from(this.initMixin) ;
+      for(var idx=0; idx < inc.length; idx++) inc[idx].call(this);
+    }
+    
     if (r) { SC.idt.t += ((new Date().getTime()) - idtStart); }
   },
   
   /**  
-    EXPERIMENTAL: You can use this to call super in any method.  This 
-    currently does not work in some versions of Safari.
+    EXPERIMENTAL: You can use this to call super in any method.  
+    
+    This currently does not work in some versions of Safari.  Instead you
+    should use:
+    
+    argments.callee.base.apply(this, arguments); to call super.
+    
+    @params args {*args} any arguments you want to pass along.
+    @returns {void}
   */
   $super: function(args) {
     var caller = SC.Object.prototype.$super.caller; 
@@ -390,7 +548,10 @@ SC.Object.prototype = {
   },
   
   /**  
-  Use this to add class methods to an object.
+    Add passed properties to the object's class.
+    
+    @param props {Hash} properties to append.
+    @returns {void}
   */
   mixin: function() { return SC.Object.mixin.apply(this,arguments) ; },
 
@@ -409,6 +570,9 @@ SC.Object.prototype = {
   /**  
     returns true if the receiver is an instance of the named class.  See also
     kindOf().
+    
+    @param {Class} scClass the class
+    @returns {Boolean}
   */
   instanceOf: function(scClass) {
     return this._type == scClass ;  
@@ -417,6 +581,9 @@ SC.Object.prototype = {
   /**  
     Returns true if the receiver is an instance of the named class or any 
     subclass of the named class.  See also instanceOf().
+    
+    @param scClass {Class} the class
+    @returns {Boolean}
   */
   kindOf: function(scClass) {
     var t = this._type ;
@@ -428,34 +595,26 @@ SC.Object.prototype = {
   },
 
   /** @private */
-  _enumerator: function() {
-    
-    // build in enumerator.
-    if (this.objectAtIndex) {
-      ret = {
-        nextObject: function() { 
-          var loc = this.loc ;
-          return (loc>=0) ? this.obj.objectAtIndex(--loc) : null ; 
-        },
-        loc: this.get('length') || 0,
-        obj: this
-      } ;
-
-    // or just return one that does nothing.
-    } else {
-      ret = { nextObject: function() { return null; } } ;
-    }
-    
-    return ret ;
+  toString: function() {
+    if (!this.__toString) {
+      this.__toString = "%@:%@".fmt(this._type.objectClassName(), this._guid);
+    } 
+    return this.__toString ;
   },
-
+  
   // ..........................................
   // OUTLETS
   // 
 
   /**  
+    Activates any outlet connections in the the object.  This is called 
+    automatically for views typically.
+    
     A view may contain outlets.  Outlets are a way to find and connect to
     elements within the view.
+    
+    @param key {String} optional single key to awake.
+    @returns {void}
   */
   awake: function(key) { 
     // if a key is passed, convert that from an outlet and awake it. otherwise
@@ -504,17 +663,27 @@ SC.Object.prototype = {
   },
   
   /**  
-    name your outlets here or name the outlets "somethingOutlet".  See 
-    also outletFor in views.
+    Array of outlets to awake automatically.
+    
+    If you have outlets defined on a class, add this array with their
+    property names to have them awake automatically.  This array is merged
+    with the parent class outlet's array automatically when you call extend().
+    
+    @type {Array}
+    @field
   */
   outlets: [],
 
   /**
+    Just like get() except it will also create an outlet-packaged view if that 
+    is the value of the property.
+    
     This method works just like get() except if the value of the property
     is an outlet-packaged View, the view will be created first.  You can use
-    this to create lazy outlets.  (DOC-INCOMPLETE)
+    this to create lazy outlets.
     
     @param {String} key The key to read as an outlet.
+    @returns {Object} the value of the key, possibly an awakened outlet.
   */        
   outlet: function(key) {
     var value = this[key] ; // get the current value.
@@ -524,6 +693,7 @@ SC.Object.prototype = {
       if (!this._originalOutlets) this._originalOutlets = {} ;
       this._originalOutlets[key] = value ;
 
+      // create the outlet by calling the outlet function.  this should be the owner view.
       value = value.call(this) ;
       this.set(key, value) ;
     } else if (typeof(value) == "string") {
@@ -537,16 +707,38 @@ SC.Object.prototype = {
 
     return value ;
   },
-  
+
   /**
-    DEPRECATED: Will be removed in SproutCore 1.0.
+    Invokes the named method after the specified period of time.
+    
+    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:
+    
+    {{{
+      methodName: function(timer)
+    }}}
+    
+    If you would prefer to pass your own parameters instead, you can instead
+    call invokeLater() directly on the function object itself.
+    
+    @param interval {Number} period from current time to schedule.
+    @param methodName {String} method name to perform.
+    @returns {SC.Timer} scheduled timer.
   */
-  invokeLater: function(period) {
-    var args = $A(arguments) ; args.unshift(this) ;
-    return SC.runLoop.schedule.apply(SC.runLoop,args) ; 
+  invokeLater: function(methodName, interval) {
+    if (interval === undefined) interval = 1 ;
+    var f = methodName ;
+    if (arguments.length > 2) {
+      var args =$A(arguments).slice(2,arguments.length);
+      args.unshift(this);
+      if ($type(f) === T_STRING) f = this[methodName] ;
+      f = f.bind.apply(f, args) ;
+    }
+    return SC.Timer.schedule({ target: this, action: f, interval: interval });
   },
   
-  _cprops: ['_cprops','outlets','_bindings','_observers','_properties']  
+  _cprops: ['_cprops','outlets','_bindings','_observers','_properties', 'initMixin']  
 
 } ;
 
@@ -557,126 +749,6 @@ function logChange(target,key,value) {
   console.log("CHANGE: " + target + "["+key+"]=" + value) ;
 }
 
-// ........................................................................
-// FUNCTION ENHANCEMENTS
-//
-// Enhance function.
-Object.extend(Function.prototype,{
-  
-  // Declare a function as a property.  This makes it something that can be
-  // accessed via get/set.
-  property: function() {
-    this.dependentKeys = $A(arguments) ; 
-    this.isProperty = true; return this; 
-  },
-  
-  // Declare that a function should observe an object at the named path.  Note
-  // that the path is used only to construct the observation one time.
-  observes: function(propertyPaths) { 
-    this.propertyPaths = $A(arguments); 
-    return this;
-  },
-  
-  typeConverter: function() {
-    this.isTypeConverter = true; return this ;
-  }
-  
-}) ;
-
-// ........................................................................
-// 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: {},
-  
-  addObserver: function(propertyPath, func) {
-    // try to get the tuple for this.
-    if (typeof(propertyPath) == "string") {
-      var tuple = SC.Object.tupleForPropertyPath(propertyPath) ;
-    } else {
-      var tuple = propertyPath; 
-    }
-    
-    if (tuple) {
-      tuple[0].addObserver(tuple[1],func) ;
-    } else {
-      var ary = this.queue[propertyPath] || [] ;
-      ary.push(func) ;
-      this.queue[propertyPath] = ary ;
-    }
-  },
-  
-  removeObserver: function(propertyPath, func) {
-    var tuple = SC.Object.tupleForPropertyPath(propertyPath) ;
-    if (tuple) {
-      tuple[0].removeObserver(tuple[1],func) ;
-    }
-    
-    var ary = this.queue[propertyPath] ;
-    if (ary) {
-      ary = ary.without(func) ;
-      this.queue[propertyPath] = ary ;
-    }
-  },
-  
-  flush: function() {
-    var newQueue = {} ;
-    for(var path in this.queue) {
-      var funcs = this.queue[path] ;
-      var tuple = SC.Object.tupleForPropertyPath(path) ;
-      if (tuple) {
-        var loc = funcs.length ;
-        while(--loc >= 0) {
-          var func = funcs[loc] ;
-          tuple[0].addObserver(tuple[1],func) ;
-        }
-      } else newQueue[path] = funcs ;
-    }
-    
-    // set queue to remaining items
-    this.queue = newQueue ; 
-  }
-} ;
-
-// ........................................................................
-// NOTIFCATION QUEUE
-//
-// Property notifications are placed into this queue first and then processed
-// to keep the stack size down.
-SC.NotificationQueue = {
-  queue: [],
-  maxFlush: 5000, // max time you can spend flushing before we reschedule.
-  _flushing: false,
-  add: function(target, func, args) { this.queue.push([target, func, args]);},
-  flush: function() {
-    if (this._flushing) return ;
-    this._flushing = true ;
-    
-    var start = new Date().getTime() ;
-    var now = start ;
-    var n = null ;
-    while(((now - start) < this.maxFlush) && (n = this.queue.pop())) { 
-      try {
-        var t = n[0] || n[1] ;
-        n[1].apply(t,n[2]) ;
-      }
-      catch(e) {
-        console.log("Exception while notify("+n[1]+"): " + e) ;
-      } // catch  
-      now = Date.now() ;
-    }
-    this._flushing = false ;
-    
-    if (this.queue.length > 0) { 
-      setTimeout(this._reflush,1); 
-    }
-  },
-  
-  _reflush: function() { SC.NotificationQueue.flush(); }
-} ;
 
 // ........................................................................
 // CHAIN OBSERVER