sproutcore 0.9.0

data/frameworks/sproutcore/foundation/application.js

@@ -0,0 +1,199 @@
+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
+*/
+SC.Application = SC.Responder.extend( /** @scope SC.Application.prototype */ {
+  
+  /**
+  * The pane that is currently receiving key events.
+  * @return {SC.PaneView}
+  */
+  keyPane: function( key, value )
+  {
+    if ( value != undefined )
+    {
+      if (this._keyPane) this._keyPane.willResignKeyPane();
+      if (this._keyPane) this._keyPane.set('isKeyPane', false);
+      this._keyPane = value;
+      if (this._keyPane) this._keyPane.set('isKeyPane', true);
+      if (this._keyPane) this._keyPane.didBecomeKeyPane();
+    }
+    return this._keyPane || null;
+  }.property(),
+
+  /**
+  * The primary pane for the application.
+  * @return {SC.PaneView}
+  */
+  mainPane: function( key, value )
+  {
+    if ( value != undefined )
+    {
+      if (this._mainPane) this._mainPane.willResignMainPane();
+      if (this._mainPane) this._mainPane.set('isMainPane', false);
+      this._mainPane = value;
+      if (this._mainPane) this._mainPane.set('isMainPane', true);
+      if (this._mainPane) this._mainPane.didBecomeMainPane();
+    }
+    return this._mainPane || null;
+  }.property(),
+
+  /**
+  * Starts the application
+  * @return {void}
+  */
+  run: function()
+  {
+    // primary application pane.
+    SC.window.setup();
+    SC.window.makeMainPane();
+    SC.window.makeKeyPane();
+  },
+
+  /**
+  * Route an action message to the appropriate responder
+  * @param {String} action The action to perform
+  * @param {SC.Responder} target The object to perform the action upon. Set to null to search the Responder chain for a receiver.
+  * @param {Object} sender The sender of the action
+  * @returns return value info
+  * @type Array
+  */
+  sendAction: function( action, target, sender )
+  {
+    var target = this.targetForAction(action, target, sender);
+    return (!!target && (target.tryToPerform(action, sender) != false));
+  },
+  
+  targetForAction: function( action, target, sender )
+  {
+    // no action, no target...
+    if (!action || ($type(action) != T_STRING)) return null;
+
+    // an explicit target was passed... but make sure that it does indeed respond to the action...
+    if (target) return target.respondsTo(action) ? target : null;
+
+    // ok, no target was passed... try to find one in the responder chain
+    var keyPane   = this.get('keyPane');
+    var mainPane  = this.get('mainPane');
+
+    // TODO: add in a check for Pane and App delegates once we add support for them...
+    if (keyPane)
+    {
+      target = keyPane.get('firstResponder') || keyPane.get('defaultResponder') || keyPane;
+      do {
+        if (target.respondsTo(action)) return target;
+      } while (target = target.get('nextResponder'));
+    }
+    if (mainPane && (mainPane != keyPane))
+    {
+      target = mainPane.get('firstResponder') || mainPane.get('defaultResponder') || mainPane;
+      do {
+        if (target.respondsTo(action)) return target;
+      } while (target = target.get('nextResponder'));
+    }
+    // last stop, SC.app
+    target = this;
+    if (target.respondsTo(action)) return target;
+
+    return null;
+  },
+  
+
+  sendEvent: function( evt, target )
+  {
+    var target  = target || null;
+    var handler = null;
+
+    //console.log( '[SC.Application#sendEvent] type: %s, evt: %o, target: %o', evt._type, evt, target );
+
+    if (target && target.respondsTo(evt._type))
+    {
+      // explicit target was passed... we send the event to that target only...
+      return (target.tryToPerform(evt._type, evt)) ? target : false;
+    }
+    
+    // ok... then we need to resolve the target based on event type...
+    switch ( evt._type )
+    {
+      case 'keyDown':
+      case 'keyUp':
+      case 'flagsChanged':
+        var pane = this.get('keyPane');
+        if (!pane) return null;
+        target = pane.get('firstResponder') || pane.get('defaultResponder') || pane;
+        break;
+      case 'mouseOver':
+      case 'mouseOut':
+      case 'mouseMoved':
+      case 'mouseDown':
+      case 'mouseUp':
+      case 'click':
+      case 'doubleClick':
+        target = SC.window.firstViewForEvent(evt);
+        break;
+      default:
+        // unrecognized event type.. bail...
+        return null;
+    }
+
+    // unable to resolve a target... mouseDown on an element not in the view chain, key responder is null, etc...
+    if (!target) return null;
+
+    // calling doCommand will crawl up the responder chain until someone handles it or it hits the end of the chain (SC.PaneView).
+    handler = target.doCommand( evt._type, evt );
+    
+    // unhandled keyDown event...
+    if ((evt._type == 'keyDown') && !handler)
+    {
+      // lonely keyDown... the responder chain doesn't want you... 
+      // perhaps someone else has defined you as a shortcut?
+      if (this._attemptKeyEquivalent(evt)) return true;
+      // no?... how about keyView navigation?
+      if (this._attemptKeyInterfaceControl(evt)) return true;
+    }
+    
+    //console.log( '[SC.Application#sendEvent] ----- handler: %o', handler );
+    return handler;
+  },
+
+  _attemptKeyEquivalent: function( evt )
+  {
+    // keystring is a method name representing the keys pressed (i.e 'alt_shift_escape')
+    var keystring = SC.Responder.inputManager.codesForEvent(evt).first();
+    
+    //console.log( '[SC.Application#_attemptKeyEquivalent] keystring: %s, evt: %o', keystring, evt );
+
+    // inputManager couldn't build a keystring for this key event... nothing to do...
+    if (!keystring) return false;
+    
+    var keyPane  = this.get('keyPane');
+    var mainPane = this.get('mainPane');
+    
+    if (keyPane && keyPane.performKeyEquivalent(keystring, evt)) return true;
+    if (mainPane && (mainPane != keyPane) && mainPane.performKeyEquivalent(keystring, evt)) return true;
+    return this.performKeyEquivalent(keystring, evt);
+  },
+  _attemptKeyInterfaceControl: function( evt )
+  {
+    // keystring is a method name representing the keys pressed (i.e 'alt_shift_escape')
+    var keystring = SC.Responder.inputManager.codesForEvent(evt).first();
+
+    //console.log( '[SC.Application#_attemptKeyInterfaceControl] keystring: %s, evt: %o', keystring, evt );
+
+    var pane = this.get('keyPane');
+    if ( !pane ) return false;
+    
+    return pane.performKeyInterfaceControl(keystring, evt);
+  }
+
+});

data/frameworks/sproutcore/foundation/array.js

@@ -0,0 +1,348 @@
+// ==========================================================================
+// SproutCore -- JavaScript Application Framework
+// copyright 2006-2007, Sprout Systems, Inc. and contributors.
+// ==========================================================================
+
+require('foundation/observable');
+
+// Make Arrays observable
+Object.extend(Array.prototype, SC.Observable) ;
+
+SC.OUT_OF_RANGE_EXCEPTION = "Index out of range" ;
+
+/**
+  @namespace SC.Array
+  
+  This module implements Observer-friendly Array-like behavior.  This mixin is 
+  picked up by the Array class as well as other controllers, etc. that want to  
+  appear to be arrays.
+  
+  You can use the methods defined in this module to access and modify array 
+  contents in a KVO-friendly way.  You can also be notified whenever the 
+  membership if an array changes by observing the "[]" property.
+
+  To support SC.Array in your own class, you must override two
+  primitives to use it: replace() and objectAt().  
+
+*/
+SC.Array = {
+
+/**
+  @property {Number} length
+  
+  Your array must support the length property.  your replace methods should
+  set this property whenever it changes.
+*/
+  // length: 0,
+  
+/**
+  This is one of the primitves you must implement to support SC.Array.  You 
+  should replace amt objects started at idx with the objects in the passed 
+  array.  You should also call this.arrayContentDidChange() ;
+  
+  @param {Number} idx 
+    Starting index in the array to replace.  If idx >= length, then append to 
+    the end of the array.
+
+  @param {Number} amt 
+    Number of elements that should be removed from the array, starting at 
+    *idx*.
+
+  @param {Array} objects 
+    An array of zero or more objects that should be inserted into the array at 
+    *idx* 
+*/
+  replace: function(idx, amt, objects) {
+    throw "replace() must be implemented to support SC.Array" ;
+  },
+
+/**
+  This is one of the primitives you must implement to support SC.Array.  
+  Returns the object at the named index.  If your object supports retrieving 
+  the value of an array item using get() (i.e. myArray.get(0)), then you do
+  not need to implement this method yourself.
+  
+  @param {Number} idx
+    The index of the item to return.  If idx exceeds the current length, 
+    return null.
+*/
+  objectAt: function(idx)
+  {
+    if (idx >= this.get('length')) return undefined;
+    return this.get(idx);
+  },
+
+  // this is required to support the enumerable options.  Override with your
+  // own method if you prefer.
+  _each: function(iterator) {
+    var len ;
+    for (var i = 0, len = this.get('length'); i < len; i++)
+      iterator(this.objectAt(i));
+  },
+  
+  /**  
+    When you implement replace(), be sure to call this method whenever the 
+    membership of your array changes.  This will make sure users are properly 
+    notified.
+  */
+  arrayContentDidChange: function() {
+    this.propertyDidChange('[]') ;  
+  },
+  
+  /**
+    @property []
+
+    This is the handler for the special array content property.  If you get
+    this property, it will return this.  If you set this property it a new 
+    array, it will replace the current content.
+  */
+  '[]': function(key, value) {
+    if (value !== undefined) {
+      this.replace(0, this.get('length'), value) ;
+    }  
+    return this ;
+  }.property(),
+  
+/**  
+  This will use the primitive replace() method to insert an object at the 
+  specified index.
+  
+  @param {Number} idx index of insert the object at.
+  @param {Object} object object to insert
+*/
+  insertAt: function(idx, object) {
+    if (idx > this.get('length')) throw SC.OUT_OF_RANGE_EXCEPTION ;
+    this.replace(idx,0,[object]) ;
+    return this ;
+  },
+  
+  /**
+    Remove an object at the specified index using the replace() primitive method.
+  
+    @param {Number} idx index of object to remove
+  */
+  removeAt: function(idx) {
+    if ((idx < 0) || (idx >= this.get('length'))) throw SC.OUT_OF_RANGE_EXCEPTION;
+    this.replace(idx,1,[]);
+    return this ;
+  },
+  
+  /**
+    Search the array of this object, removing any occurrences of it.
+    @param {object} obj object to remove
+  */
+  removeObject: function(obj) {
+    var loc = this.get('length') || 0;
+    while(--loc >= 0) {
+      var curObject = this.objectAt(loc) ;
+      if (curObject == obj) this.removeAt(loc) ;
+    }
+    return this ;
+  },
+  
+  /**
+    Push the object onto the end of the array.  Works just like push() but it 
+    is KVO-compliant.
+  */
+  pushObject: function(obj) {
+    this.insertAt(this.get('length'), obj) ;
+    return obj ;
+  },
+  
+  /**
+    Pop object from array or nil if none are left.  Works just like pop() but 
+    it is KVO-compliant.
+  */
+  popObject: function() {
+    var len = this.get('length') ;
+    if (len == 0) return null ;
+    
+    var ret = this.objectAt(len-1) ;
+    this.removeAt(len-1) ;
+    return ret ;
+  },
+  
+  /**
+    Shift an object from start of array or nil if none are left.  Works just 
+    like shift() but it is KVO-compliant.
+  */
+  shiftObject: function() {
+    if (this.get('length') == 0) return null ;
+    var ret = this.objectAt(0) ;
+    this.removeAt(0) ;
+    return ret ;
+  },
+  
+  /**
+    Unshift an object to start of array.  Works just like unshift() but it is 
+    KVO-compliant.
+  */
+  unshiftObject: function(obj) {
+    this.insertAt(0, obj) ;
+    return obj ;
+  },
+  
+  /**  
+    Compares each item in the array.  Returns true if they are equal.
+  */
+  isEqual: function(ary) {
+    if (!ary) return false ;
+    if (ary == this) return true;
+    
+    var loc = ary.get('length') ;
+    if (loc != this.get('length')) return false ;
+
+    while(--loc >= 0) {
+      if (ary.objectAt(loc) != this.objectAt(loc)) return false ;
+    }
+    return true ;
+  }
+  
+} ;
+
+// All arrays have the SC.Array mixin.  Do this before we add the 
+// enumerable methods since Arrays are already enumerable.
+Object.extend(Array.prototype, SC.Array) ; 
+
+// Now make SC.Array enumerable.
+Object.extend(SC.Array, Enumerable) ;
+
+// ........................................................
+// A few basic enhancements to the Array class.
+// These methods add support for the SproutCore replace() method as well as 
+// optimizing certain enumerable methods.
+//
+Object.extend(Array.prototype, {
+
+  // primitive for array support.
+  replace: function(idx, amt, objects) {
+    if (!objects || objects.length == 0) {
+      this.splice(idx, amt) ;
+    } else {
+      var args = [idx, amt].concat(objects) ;
+      this.splice.apply(this,args) ;
+    }
+    this.arrayContentDidChange() ;
+    return this ;
+  },
+  
+  // These are faster implementations of the iterations defined by prototype.
+  // The iterators there are cool but they consume large numbers of stack
+  // frames.  These are API compatible, but much faster because they duplicate
+  // code instead of calling a bunch of common methods.
+
+  each: function(iterator) {
+    try {
+      for(var index=0;index<this.length;index++) {
+        var item = this[index] ;
+        iterator.call(item,item,index) ;
+      }
+    } catch (e) {
+      if (e != $break) throw e ;
+    }
+    return this ;
+  },
+
+  invoke: function(iterator) {
+    var args = $A(arguments) ;
+    var methodName = args.shift() ;
+    var ret = [] ;
+    try {
+      for(var index=0;index<this.length;index++) {
+        var item = this[index] ;
+        ret.push(item[methodName].apply(item,args)) ;
+      } ;
+    } catch (e) {
+      if (e != $break) throw e ;
+    }
+    return ret ;
+  },
+
+  map: function(iterator) {
+    var ret = [] ;
+    try {
+      for(var index=0;index<this.length;index++) {
+        var item = this[index] ;
+        ret.push((iterator || Prototype.K).call(item,item,index))  ;
+      } ;
+    } catch (e) {
+      if (e != $break) throw e ;
+    }
+    return ret ;
+  },
+
+  // This will invoke the passed method and arguments on the member elements
+  // as long as the value returned is the first argument.
+  invokeWhile: function(retValue, methodName) {
+    var ret ;
+    var args = $A(arguments) ;
+    retValue = args.shift() ;
+    methodName = args.shift() ; 
+
+    try {
+      for(var index=0; index < this.length; index++) {
+        var item = this[index] ;
+        var func = (item) ? item[methodName] : null ;
+        ret = func.apply(item, args) ;
+        if (ret != retValue) return retValue ;
+      }
+    } catch (e) {
+      if (e != $break) throw e ;
+    }
+    return ret ;
+  },
+  
+  // If you ask for an unknown property, then try to collect the value
+  // from member items.
+  unknownProperty: function(key, value) {
+    if (value !== undefined) return null ;
+    return this.invoke('get', key) ;
+  }
+}) ;
+
+Array.prototype.collect = Array.prototype.map ;
+
+
+// Returns the passed item as an array.  If the item is already an array,
+// it is returned as is.  If it is not an array, it is placed into one.  If
+// it is null, an empty array is returned.
+Array.asArray = function (array)
+{
+  if(array && !(array instanceof Array))
+  {
+    return [array]; 
+  }
+  if(array)
+  {
+    return array;
+  }
+  return [];
+};
+
+// Alias for asArray
+Array.from = Array.asArray ;
+
+// Map added array methods to other enumerables
+Object.extend(Enumerable, {
+  
+  invokeWhile: function(retValue, methodName) {
+    var ret ;
+    var args = $A(arguments) ;
+    retValue = args.shift() ;
+    methodName = args.shift() ; 
+
+    try {
+      var obj = this ;
+      this._each(function(item) {
+        var func = (item) ? item[methodName] : null ;
+        ret = func.apply(item, args) ;
+        if (ret != retValue) $break ;
+      }) ;
+    } catch (e) {
+      if (e != $break) throw e ;
+    }
+    return ret ;
+  }
+
+}) ;
+