sproutit-sproutcore 1.0.0.20090407205609 → 1.0.0.20090408130025

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

@@ -0,0 +1,421 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// 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('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
+*/
+SC.ObjectController = SC.Controller.extend(
+/** @scope SC.ObjectController.prototype */ {
+  
+  // ...............................
+  // PROPERTIES
+  //
+  
+  /**
+    set this to some value and the object controller will project 
+    its properties.
+  */
+  content: null,
+  contentBindingDefault: SC.Binding.multiple(),
+
+  /**
+    This will be set to true if the object currently does not have any
+    content.  You might use this to disable any controls attached to the
+    controller.
+    
+    @type Boolean
+  */
+  hasNoContent: true,
+  
+  /**
+    This will be set to true if the content is a single object or an array 
+    with a single item.  You can use this to disabled your UI.
+    
+    @type Boolean
+  */
+  hasSingleContent: false, 
+  
+  /**
+    This will be set to true if the content is an array with multiple objects 
+    in it.
+    
+    @type Boolean
+  */
+  hasMultipleContent: false,
+
+  /**
+    Set to true if the controller has any content, even an empty array.
+  */
+  hasContent: function() {
+    return this.get('content') ;
+  }.property('content'),
+
+  /**
+    Set this property to true and multiple content will be treated like a null 
+    value. This will only impact use of get() and set().
+    
+    @type Boolean
+  */
+  allowsMultipleContent: true,
+  
+  /**
+    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.
+  */
+  destroy: function() {
+    var content = this.get('content') ;
+    if (content && SC.typeOf(content.destroy) === SC.T_FUNCTION) content.destroy();
+    this.set('content', null) ;  
+  },
+  
+  // ...............................
+  // INTERNAL SUPPORT
+  //
+  
+  /**
+    When this controller commits changes, it will copy its changed values
+    to the content object and then call "commitChanges" on the content
+    object if that object implements the method.
+  */
+  performCommitChanges: function() {
+    
+    var content = this.get('content') ;
+    var ret = true ;
+    var key, loc;
+
+    // empty arrays are treated like null values, arrays.len=1 treated like 
+    // single objects.
+    var isArray = false ;
+    if (SC.isArray(content)) {
+      var len = this._lengthFor(content) ;
+      if (len === 0) {
+        content = null ; 
+      } else if (len === 1) {
+        content = this._objectAt(0, content) ;
+      } else if (this.get('allowsMultipleContent')) {
+        isArray = true ;
+      } else content = null ;
+    }
+    
+    if (!this._changes) this._changes = {} ;
+    
+    // cannot commit changes to empty content.  Return an error.
+    if (!content) {
+      return SC.$error("No Content") ;
+
+    // if content is an array, then loop through each item in the array and
+    // get the changed values.
+    } else if (isArray) {
+      
+      loc = this._lengthFor(content) ;
+      while(--loc >= 0) {
+        var object = this._objectAt(loc, content) ;
+        if (!object) continue ;
+        
+        if (object.beginPropertyChanges) object.beginPropertyChanges(); 
+        
+        // loop through all the keys in changes and get the values...
+        for(key in this._changes) {
+          if (!this._changes.hasOwnProperty(key)) continue ;
+          var value = this._changes[key];
+          
+          // if the value is an array, get the idx matching the content
+          // object.  Otherwise, just use the value of the item.
+          if(SC.isArray(value)) {
+            value = this._objectAt(loc, value) ;
+          }
+          
+          if (object.set) {
+            object.set(key,value) ;
+          } else object[key] = value ;
+        }
+
+        if (object.endPropertyChanges) object.endPropertyChanges() ;
+        if (object.commitChanges) ret = object.commitChanges() ;
+      }
+      
+    // if the content is not an array, then just loop through each changed
+    // value and copy it to the object.
+    } else {
+      
+      if (content.beginPropertyChanges) content.beginPropertyChanges() ;
+      
+      // save the set of changes to apply them.  Nothing should clear it but
+      // just in case.
+      var changes = this._changes ;
+      for(key in changes) {
+        if (!changes.hasOwnProperty(key)) continue;
+        
+        var oldValue = content.get ? content.get(key) : content[key];
+        var newValue = changes[key];
+        
+        if (SC.none(oldValue) && newValue === '') newValue = null;
+        if (newValue != oldValue) {
+          if (content.set) {
+            content.set('isDirty', YES);
+          } else {
+            content.isDirty=YES;
+          } 
+        }
+        
+        if (content.set) {
+          content.set(key, newValue);
+        } else {
+          content[key] = newValue;
+        }
+      }
+      
+      if (content.endPropertyChanges) content.endPropertyChanges() ;
+      if (content.commitChanges) ret = content.commitChanges() ;
+    }
+    
+    // if commit was successful, dump changes hash and clear editor.
+    if (SC.$ok(ret)) {
+      this._changes = {} ;
+      //this._valueControllers = {};
+      this.editorDidClearChanges() ;
+    }
+    
+    return ret ;
+  },
+  
+  /** @private */
+  performDiscardChanges: function() { 
+    this._changes = {};
+    this._valueControllers = {};
+    this.editorDidClearChanges();
+    this.allPropertiesDidChange();
+    return true ;
+  },
+  
+  /** @private */
+  unknownProperty: function(key,value)
+  {
+    if (key == "content")
+    {
+      // FOR CONTENT KEY:
+      // avoid circular references.  If you try to set content, just save the
+      // value. The propertyObserver will be triggered below to do the rest of
+      // the setup as needed.
+      if (!(value === undefined)) this[key] = value;
+      return this[key];
+    } 
+    else 
+    {
+      // FOR ALL OTHER KEYS:
+      // Save the value in our temporary hash and note the changes in the 
+      // editor.
+
+      if (!this._changes) this._changes = {} ; 
+      if (!this._valueControllers) this._valueControllers = {}; 
+      
+      if (value !== undefined)
+      {
+        // for changes, save in _changes hash and note that a change is required.
+        this._changes[key] = value;
+        if (this._valueControllers[key])
+        {
+          this._valueControllers[key] = null;
+        }
+        // notifying observers regarless if a controller had been created since they're lazy loaded
+        this.propertyWillChange(key + "Controller");
+        this.propertyDidChange(key + "Controller");
+        this.editorDidChange();
+      }
+      else
+      {
+        // are we requesting the controller for a value?
+        if (key.slice(key.length-10,key.length) == "Controller")
+        {
+          // the actual value...
+          key = key.slice(0,-10);
+          if ( !this._valueControllers[key] )
+          {
+            this._valueControllers[key] = this.controllerForValue(this._getValueForPropertyKey(key));
+          }
+          value = this._valueControllers[key];
+        }
+        else
+        {
+          // otherwise, get the value.
+          // first check the _changes hash, then check the content object.
+          value = this._getValueForPropertyKey(key);
+        }
+      }
+      return value;
+    }
+  },
+  
+  _getValueForPropertyKey: function( key )
+  {
+    // first check the changes hash for a uncommited value...
+    var value = this._changes[key];
+    // sweet, no need to proceed.
+    if ( value !== undefined ) return value;
+
+    // ok, we'll need to get the value from the content object
+    var obj = this.get('content');
+    // no content object... return null.
+    if (!obj) return null;
+
+    if (SC.isArray(obj))
+    {
+      value = [];
+      var len = this._lengthFor(obj);
+      if (len > 1)
+      {
+        // if content is an array with more than one item, collect
+        // content from array.
+        if (this.get('allowsMultipleContent')) {
+          for(var idx=0; idx < len; idx++) {
+            var item = this._objectAt(idx, obj) ;
+            value.push(item ? (item.get ? item.get(key) : item[key]) : null) ;
+          }
+        } else {
+          value = null;
+        }
+      }
+      else if (len == 1)
+      {
+        // if content is array with one item, collect from first obj.
+        obj = this._objectAt(0,obj) ;
+        value = obj.get ? obj.get(key) : obj[key] ;
+      }
+      else
+      {
+        // if content is empty array, act as if null.
+        value = null;
+      }
+    }
+    else
+    {
+      // content is a single item. Just get the property.
+      value = obj.get ? obj.get(key) : obj[key] ;
+    }
+    return value;
+  },
+
+  _lastContentPropertyRevision: 0,
+  
+  /** @private */
+  _contentDidChange: function(target,key,value,propertyRevision) {
+    
+    // handle changes to the content...
+    if ((value = this.get('content')) != this._content) {
+
+      if (this.get('hasChanges')) {
+        // if we have uncommitted changes, then discard the changes or raise
+        // an exception.
+        var er = this.discardChanges() ;
+        if (!SC.$ok(er)) throw(er) ;
+      } else {
+        // no changes, but we want to ensure that we flush the cache 
+        // of any SC.Controllers we have for the content
+        this._valueControllers = {} ;
+      }
+      
+      // get the handler method
+      var f = this._contentPropertyDidChange ;
+      
+      // stop listening to old content.
+      if (this._content) {
+        if (SC.isArray(this._content)) {
+          this._content.invoke('removeObserver', '*', this, f) ;
+        } else if (this._content.removeObserver) {
+          this._content.removeObserver('*', this, f) ;
+        }
+      }
+      
+      // start listening for changes on the new content object.
+      this._content = value ;
+      if (value) {
+        if (SC.isArray(value)) {
+          value.invoke('addObserver', '*', this, f) ;
+        } else if (value.addObserver) {
+          value.addObserver('*', this, f) ;
+        }
+      }
+
+      // determine the content type.
+      var count = !value ? 0 : (SC.isArray(value) ? this._lengthFor(value) : 1) ;
+      
+      // New content is configured, update controller stats
+      this.beginPropertyChanges() ;
+      this.set('hasNoContent',count === 0) ;
+      this.set('hasSingleContent',count === 1) ;
+      this.set('hasMultipleContent',count > 1) ;
+
+      // notify everyone that everything is different now.
+      this.allPropertiesDidChange() ;
+      this.endPropertyChanges() ;
+    }
+  }.observes('content'),
+  
+  // invoked when properties on the content object change.  Just forward
+  // to controller.
+  _contentPropertyDidChange: function(target,key,value, propertyRevision) {
+    this._changeFromContent = true ;
+    if (key === '*') {
+      this.allPropertiesDidChange() ;
+    } else {
+      this.propertyWillChange(key) ;
+      this.propertyDidChange(key,value) ;
+    }
+    this._changeFromContent = false ;
+  },
+  
+  _lengthFor: function(obj) {
+    return (obj.get ? obj.get('length') : obj.length) || 0;
+  },
+  
+  _objectAt: function(idx, obj) {
+    return obj.objectAt ? obj.objectAt(idx) : (obj.get ? obj.get(idx) : obj[idx]) ;
+  }
+      
+}) ;

data/frameworks/sproutcore/frameworks/foundation/core.js

@@ -0,0 +1,111 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// 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.mixin(/** @scope 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, {
+  /**
+    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 that = this, func = f ;
+      f = function() { return func.apply(that, args.slice(1)); } ;
+    }
+    return SC.Timer.schedule({ target: target, action: f, interval: interval });
+  }    
+
+});

data/frameworks/sproutcore/frameworks/foundation/debug/control_test_pane.js

@@ -0,0 +1,172 @@
+// ==========================================================================
+// Project:   SproutCore - JavaScript Application Framework
+// Copyright: �2006-2009 Sprout Systems, Inc. and contributors.
+//            portions copyright @2009 Apple, Inc.
+// License:   Licened under MIT license (see license.js)
+// ==========================================================================
+
+sc_require('panes/pane');
+
+/*global test */
+
+// TODO: IMPROVE CODE QUALITY.  This code was put together quickly in order to
+// test the SproutCore framework.  It does not match up to the project's 
+// normal documentation, design and coding standards.  Do not rely on this 
+// code as an example of how to build your own applications.
+
+/** @class
+  Generates a pane that will display vertically stacked views for testing.
+  You can use this class in test mode to easily create a palette with views
+  configured in different ways.
+  
+  h1. Example
+  
+  {{{
+    var pane = SC.ControlTestPane.design()
+      .add('basic', SC.CheckboxView.design({ title: "Hello World" }))
+      .add('disabled', SC.CheckboxView.design({
+        title: "Hello World", isEnabled: NO
+      }));
+      
+    module("CheckboxView UI", pane);
+    
+    test("basic", function() {
+      var view = pane.view('basic');
+      ok(view.get('isEnabled'), 'should be enabled');
+    });
+  }}}
+  
+  @extends SC.Pane
+  @since SproutCore 1.0
+*/
+SC.ControlTestPane = SC.Pane.extend(
+/** @scope SC.ControlTestPane.prototype */ {
+  
+  classNames: ['sc-control-test-pane'],
+  layout: { right: 20, width: 480, top: 75, bottom: 20 },
+
+  /**
+    The starting top location for the first row.  This will increment as 
+    views are added to the pane.
+  */
+  top:       0,
+  
+  /**
+    The default height of each row.  This will be used for a view unless you
+    manually specify a height in the view's layout.
+  */
+  height:    20,
+  
+  /**
+    The default padding added to the edges and between each row.
+  */
+  padding:   4,
+
+  /**
+    Retrieves the test sample view that was added with the passed key name.
+    
+    @param {String} keyName the key used to register the view.
+    @returns {SC.View} view instance
+  */
+  view: function(keyName) { 
+    var idx = this._views[keyName];
+    if (!idx) throw "SC.ControlTestPane does not have a view named %@".fmt(keyName);
+    return this.childViews[idx].childViews[0]; 
+  },
+  
+  init: function() {
+    sc_super();
+    if (!this._views) this._views = {};
+    this.append(); // auto-add to screen
+  }
+});
+
+/**
+  Adds a test view to the control pane design.  The passed label will be used
+  as the key which you can use to find the view layer.  You can either pass
+  a view that is already designed or pass an array of attributes that will be
+  used to create a design on the view.
+  
+  @param {String} label the view key name
+  @param {SC.View} view a view class or view design
+  @param {Hash} attrs optional attrs to use when designing the view
+  @returns {SC.ControlTestPane} receiver
+*/
+SC.ControlTestPane.add = function(label, view, attrs) {
+  if (attrs === undefined) attrs = {};
+  if (!view.isDesign) view = view.design(attrs);
+
+  // compute layout.
+  var padding = this.prototype.padding, height = this.prototype.height;
+  var top = this.prototype.top + padding*2, layout;
+  if (top === padding*2) top = padding; // reduce padding @ top
+  
+  // if the passed in view has a layout property and the layout has an 
+  // explicit, numerical height, then use that instead.
+  if (view.prototype.layout && (typeof view.prototype.layout.height === SC.T_NUMBER)) height = view.prototype.layout.height;
+  
+  this.prototype.top = top + height; // make room
+  
+  // calculate labelView and add it
+  layout = { left: padding, width: 150, top: top, height: height };
+  var labelView = SC.LabelView.design({
+    value: label + ':', 
+    layout: { left: 0, right: 0, centerY: 0, height: 14 }, 
+    textAlign: SC.ALIGN_RIGHT, 
+    fontWeight: SC.BOLD_WEIGHT 
+  });
+
+  // wrap label in parent view in order to center text vertically
+  labelView = SC.View.design().layout(layout).childView(labelView);
+  this.childView(labelView);
+  
+  // now layout view itself...
+  var wrapper = SC.View.design({
+    classNames: ['wrapper'],
+    layout: { left: 150+padding*2, top: top, right: padding, height: height },
+    childViews: [view]
+  });
+  var idx = this.prototype.childViews.length ;
+  this.childView(wrapper);
+  
+  var views = this.prototype._views;
+  if (!views) views = this.prototype._views = {};
+  views[label] = idx ;
+  
+  return this;
+};
+
+/**
+  Returns a standard setup/teardown object for use by the module() method.
+*/
+SC.ControlTestPane.standardSetup = function() {
+  var pane = this ;
+  return {
+    setup: function() { pane._pane = pane.create(); },
+    teardown: function() {
+      if (pane._pane) pane._pane.remove();
+      pane._pane = null ;
+    }
+  } ;
+};
+
+/**
+  Convenience method.  Returns the view with the given name on the current
+  pane instance if there is one.
+*/
+SC.ControlTestPane.view = function(viewKey) {
+  var pane = this._pane || this._showPane ;
+  if (!pane) throw "view() cannot be called on a class";
+  return pane.view(viewKey);
+};
+
+/**
+  Registers a final test that will instantiate the control test pane and 
+  display it.  This allows the developer to interact with the controls once
+  the test has completed.
+*/
+SC.ControlTestPane.show = function() {
+  var pane = this ;
+  test("show control test pane", function() { pane._showPane = pane.create(); });
+};
+