spade 0.0.1

data/sproutcore/frameworks/core_foundation/controllers/controller.js

@@ -0,0 +1,44 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2011 Strobe Inc. and contributors.
+//            Portions ©2008-2010 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+/**
+  @class
+  
+  The controller base class provides some common functions you will need
+  for controllers in your applications, especially related to maintaining
+  an editing context.
+  
+  In general you will not use this class, but you can use a subclass such
+  as ObjectController, TreeController, or ArrayController.
+  
+  h2. EDITING CONTEXTS
+  
+  One major function of a controller is to mediate between changes in the
+  UI and changes in the model.  In particular, you usually do not want 
+  changes you make in the UI to be applied to a model object directly.  
+  Instead, you often will want to collect changes to an object and then
+  apply them only when the user is ready to commit their changes.
+  
+  The editing contact support in the controller class will help you
+  provide this capability.
+  
+  @extends SC.Object
+  @since SproutCore 1.0
+*/
+SC.Controller = SC.Object.extend(
+/** @scope SC.Controller.prototype */ {
+  
+  /**
+    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
+
+});

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

@@ -0,0 +1,342 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2011 Strobe Inc. and contributors.
+//            Portions ©2008-2010 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+sc_require('controllers/controller') ;
+
+/** @class
+
+  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 
+  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 
+  content as needed.
+  
+  h2. 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 
+  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 
+  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 
+  like so:
+  
+    contentBinding: SC.Binding.single('MyApp.listController.selection') ;
+
+  This will ensure that your content property is always a single object 
+  instead of an array.
+  
+  @extends SC.Controller
+  @since SproutCore 1.0
+*/
+SC.ObjectController = SC.Controller.extend(
+/** @scope SC.ObjectController.prototype */ {
+
+  // ..........................................................
+  // 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
+    an array or enumerable with a single item in it, the ObjectController
+    will manage that single item.
+
+    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 
+    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. 
+    
+    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,
+
+  /**
+    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 
+    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 
+    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 
+    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 
+    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) ;  
+    return this;
+  },
+  
+  /**
+    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 
+    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 
+    called anytime any property in the set changes.
+
+    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}
+  */
+  contentPropertyDidChange: function(target, key) {
+    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 
+    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 
+    // 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
+
+    // getter...
+    if (value === undefined) {
+      if (content.isEnumerable) {
+        value = content.getEach(key);
+
+        // iterate over array to see if all values are the same. if so, then
+        // just return that value
+        loc = value.get('length');
+        if (loc>0) {
+          isSame = YES;
+          cur = value.objectAt(0);
+          while((--loc > 0) && isSame) {
+            if (cur !== value.objectAt(loc)) isSame = NO ;
+          }
+          if (isSame) value = cur;
+        } 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
+  //
+
+  /** @private - setup observer on init if needed. */
+  init: function() {
+    sc_super();
+    if (this.get('content')) this._scoc_contentDidChange();
+    if (this.get('observableContent')) this._scoc_observableContentDidChange();
+  },
+
+  _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.
+  */
+  _scoc_observableContentDidChange: function() {
+    var last = this._scoc_observableContent,
+        cur  = this.get('observableContent'),
+        func = this.contentPropertyDidChange,
+        efunc= this._scoc_enumerableContentDidChange;
+
+    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);
+    }
+
+    // notify!
+    if ((last && last.isEnumerable) || (cur && cur.isEnumerable)) {
+      this._scoc_enumerableContentDidChange();
+    } 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 
+    contentPropertyDidChange().  This method may be called even if the new
+    'cur' is not enumerable but the last content was enumerable.
+  */
+  _scoc_enumerableContentDidChange: function() {
+    var cur  = this.get('observableContent'),
+        set  = this._scoc_observableContentItems,
+        func = this.contentPropertyDidChange;
+    
+    // stop observing each old item
+    if (set) {
+      set.forEach(function(item) {
+        if (item.isObservable) item.removeObserver('*', this, func);
+      }, this);
+      set.clear();
+    }
+    
+    // start observing new items if needed
+    if (cur && cur.isEnumerable) {
+      if (!set) set = SC.Set.create();
+      cur.forEach(function(item) {
+        if (set.contains(item)) return ; // nothing to do
+        set.add(item);
+        if (item.isObservable) item.addObserver('*', this, func);
+      }, this); 
+    } else set = null;
+    
+    this._scoc_observableContentItems = set; // save for later cleanup
+  
+    // notify
+    this.contentPropertyDidChange(cur, '*');
+    return this ;
+  }
+        
+}) ;

data/sproutcore/frameworks/core_foundation/core.js

@@ -0,0 +1,201 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: ©2006-2011 Strobe Inc. and contributors.
+//            Portions ©2008-2010 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+/**
+  Indicates that the collection view expects to accept a drop ON the specified
+  item.
+  
+  @property {Number}
+*/
+SC.DROP_ON = 0x01 ;
+
+/**
+  Indicates that the collection view expects to accept a drop BEFORE the 
+  specified item.
+  
+  @property {Number}
+*/
+SC.DROP_BEFORE = 0x02 ;
+
+/**
+  Indicates that the collection view expects to accept a drop AFTER the
+  specified item.  This is treated just like SC.DROP_BEFORE is most views
+  except for tree lists.
+  
+  @property {Number}
+*/
+SC.DROP_AFTER = 0x04 ;
+
+/**
+  Indicates that the collection view want's to know which operations would 
+  be allowed for either drop operation.
+  
+  @property {Number}
+*/
+SC.DROP_ANY = 0x07 ;
+
+/**
+  Indicates that the content should be aligned to the left.
+*/
+SC.ALIGN_LEFT = 'left';
+
+/**
+  Indicates that the content should be aligned to the right.
+*/
+SC.ALIGN_RIGHT = 'right';
+
+/**
+  Indicates that the content should be aligned to the center.
+*/
+SC.ALIGN_CENTER = 'center';
+
+/**
+  Indicates that the content should be aligned to the top.
+*/
+SC.ALIGN_TOP = 'top';
+
+/**
+  Indicates that the content should be aligned to the middle.
+*/
+SC.ALIGN_MIDDLE = 'middle';
+
+/**
+  Indicates that the content should be aligned to the bottom.
+*/
+SC.ALIGN_BOTTOM = 'bottom';
+
+/**
+  Indicates that the content should be aligned to the top and left.
+*/
+SC.ALIGN_TOP_LEFT = 'top-left';
+
+/**
+  Indicates that the content should be aligned to the top and right.
+*/
+SC.ALIGN_TOP_RIGHT = 'top-right';
+
+/**
+  Indicates that the content should be aligned to the bottom and left.
+*/
+SC.ALIGN_BOTTOM_LEFT = 'bottom-left';
+
+/**
+  Indicates that the content should be aligned to the bottom and right.
+*/
+SC.ALIGN_BOTTOM_RIGHT = 'bottom-right';
+
+/**
+  This variable is here to make the tab focus behavior work like safari's.
+*/
+SC.SAFARI_FOCUS_BEHAVIOR = YES;
+
+SC.mixin(/** @lends SC */ {
+  
+  /**
+    Reads or writes data from a global cache.  You can use this facility to
+    store information about an object without actually adding properties to
+    the object itself.  This is needed especially when working with DOM,
+    which can leak easily in IE.
+    
+    To read data, simply pass in the reference element (used as a key) and
+    the name of the value to read.  To write, also include the data.
+    
+    You can also just pass an object to retrieve the entire cache.
+    
+    @param elem {Object} An object or Element to use as scope
+    @param name {String} Optional name of the value to read/write
+    @param data {Object} Optional data.  If passed, write.
+    @returns {Object} the value of the named data
+  */
+  data: function(elem, name, data) {
+    elem = (elem === window) ? "@window" : elem ;
+    var hash = SC.hashFor(elem) ; // get the hash key
+    
+    // Generate the data cache if needed
+    var cache = SC._data_cache ;
+    if (!cache) SC._data_cache = cache = {} ;
+    
+    // Now get cache for element
+    var elemCache = cache[hash] ;
+    if (name && !elemCache) cache[hash] = elemCache = {} ;
+    
+    // Write data if provided 
+    if (elemCache && (data !== undefined)) elemCache[name] = data ;
+    
+    return (name) ? elemCache[name] : elemCache ;
+  },
+  
+  /**
+    Removes data from the global cache.  This is used throughout the
+    framework to hold data without creating memory leaks.
+    
+    You can remove either a single item on the cache or all of the cached 
+    data for an object.
+    
+    @param elem {Object} An object or Element to use as scope
+    @param name {String} optional name to remove. 
+    @returns {Object} the value or cache that was removed
+  */
+  removeData: function(elem, name) {
+    elem = (elem === window) ? "@window" : elem ;
+    var hash = SC.hashFor(elem) ;
+    
+    // return undefined if no cache is defined
+    var cache = SC._data_cache ;
+    if (!cache) return undefined ;
+    
+    // return undefined if the elem cache is undefined
+    var elemCache = cache[hash] ;
+    if (!elemCache) return undefined;
+    
+    // get the return value
+    var ret = (name) ? elemCache[name] : elemCache ;
+    
+    // and delete as appropriate
+    if (name) {
+      delete elemCache[name] ;
+    } else {
+      delete cache[hash] ;
+    }
+    
+    return ret ;
+  }
+}) ;
+
+SC.mixin(Function.prototype, /** @scope Function.prototype */ {
+  /**
+    Creates a timer that will execute the function after a specified 
+    period of time.
+    
+    If you pass an optional set of arguments, the arguments will be passed
+    to the function as well.  Otherwise the function should have the 
+    signature:
+    
+    {{{
+      function functionName(timer)
+    }}}
+
+    @param target {Object} optional target object to use as this
+    @param interval {Number} the time to wait, in msec
+    @returns {SC.Timer} scheduled timer
+  */
+  invokeLater: function(target, interval) {
+    if (interval === undefined) interval = 1 ;
+    var f = this;
+    if (arguments.length > 2) {
+      var args = SC.$A(arguments).slice(2,arguments.length);
+      args.unshift(target);
+      // f = f.bind.apply(f, args) ;
+      var func = f ;
+      // Use "this" in inner func because it get its scope by 
+      // outer func f (=target). Could replace "this" with target for clarity.
+      f = function() { return func.apply(this, args.slice(1)); } ;
+    }
+    return SC.Timer.schedule({ target: target, action: f, interval: interval });
+  }    
+
+});