spade 0.0.1

data/sproutcore/frameworks/core_foundation/system/sparse_array.js

@@ -0,0 +1,393 @@
+// ==========================================================================
+// Project:   SproutCore Costello - Property Observing Library
+// 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('mixins/delegate_support') ;
+
+/**
+  @class
+
+  A dynamically filled array.  A SparseArray makes it easy for you to create
+  very large arrays of data but then to defer actually populating that array
+  until it is actually needed.  This is often much faster than generating an
+  array up front and paying the cost to load your data then.
+
+  Although technically all arrays in JavaScript are "sparse" (in the sense
+  that you can read and write properties at arbitrary indexes), this array
+  keeps track of which elements in the array have been populated already
+  and which ones have not.  If you try to get a value at an index that has
+  not yet been populated, the SparseArray will notify a delegate object first,
+  giving the delegate a chance to populate the component.
+
+  Most of the time, you will use a SparseArray to incrementally load data
+  from the server.  For example, if you have a contact list with 3,000
+  contacts in it, you may create a SparseArray with a length of 3,000 and set
+  that as the content for a ListView.  As the ListView tries to display the
+  visible contacts, it will request them from the SparseArray, which will in
+  turn notify your delegate, giving you a chance to load the contact data from
+  the server.
+
+  @extends SC.Enumerable
+  @extends SC.Array
+  @extends SC.Observable
+  @extends SC.DelegateSupport
+  @since SproutCore 1.0
+*/
+
+SC.SparseArray = SC.Object.extend(SC.Observable, SC.Enumerable, SC.Array,
+  SC.DelegateSupport, /** @scope SC.SparseArray.prototype */ {
+
+  // ..........................................................
+  // LENGTH SUPPORT
+  //
+
+  _requestingLength: 0,
+  _requestingIndex: 0,
+
+  /**
+    The length of the sparse array.  The delegate for the array should set
+    this length.
+
+    @property {Number}
+  */
+  length: function() {
+    var del = this.delegate ;
+    if (del && SC.none(this._length) && del.sparseArrayDidRequestLength) {
+      this._requestingLength++ ;
+      del.sparseArrayDidRequestLength(this);
+      this._requestingLength-- ;
+    }
+    return this._length || 0 ;
+  }.property().cacheable(),
+
+  /**
+    Call this method from a delegate to provide a length for the sparse array.
+    If you pass null for this property, it will essentially "reset" the array
+    causing your delegate to be called again the next time another object
+    requests the array length.
+
+    @param {Number} length the length or null
+    @returns {SC.SparseArray} receiver
+  */
+  provideLength: function(length) {
+    if (SC.none(length)) this._sa_content = null ;
+    if (length !== this._length) {
+      this._length = length ;
+      if (this._requestingLength <= 0) this.enumerableContentDidChange() ;
+    }
+    return this ;
+  },
+
+  // ..........................................................
+  // READING CONTENT
+  //
+
+  /**
+    The minimum range of elements that should be requested from the delegate.
+    If this value is set to larger than 1, then the sparse array will always
+    fit a requested index into a range of this size and request it.
+
+    @property {Number}
+  */
+  rangeWindowSize: 1,
+
+  /**
+    This array contains all the start_indexes of ranges requested. This is to
+    avoid calling sparseArrayDidRequestRange to often. Indexes are removed and
+    added as range requests are completed.
+  */
+  requestedRangeIndex: null,
+  
+  /**
+    Make sure to create the index array during init so that it is not shared
+    between all instances.
+  */
+  init: function() {
+    sc_super();
+    this.requestedRangeIndex = [];
+    
+    this._TMP_PROVIDE_ARRAY = [];
+    this._TMP_PROVIDE_RANGE = { length: 1 };
+    this._TMP_RANGE = {};
+  },
+  
+  /** 
+    Returns the object at the specified index.  If the value for the index
+    is currently undefined, invokes the didRequestIndex() method to notify
+    the delegate.
+
+    The omitMaterializing flag ensures that the object will not be materialized,
+    but it simply checks for the presence of an object at the specified index
+    and will return YES (or undefined if not found). This is useful in the case
+    of SparseArrays, where you might NOT want to request the index to be loaded, 
+    but simply need a shallow check to see if the position has been filled.
+    
+    @param {Number} idx the index to get
+    @param {Boolean} omitMaterializing
+    @return {Object} the object
+  */
+  objectAt: function(idx, omitMaterializing) {
+    var content = this._sa_content, ret ;
+    if (!content) content = this._sa_content = [] ;
+    if ((ret = content[idx]) === undefined) {
+      if(!omitMaterializing) this.requestIndex(idx);
+      ret = content[idx]; // just in case the delegate provided immediately
+    }
+    return ret ;
+  },
+
+  /**
+    Returns the set of indexes that are currently defined on the sparse array.
+    If you pass an optional index set, the search will be limited to only
+    those indexes.  Otherwise this method will return an index set containing
+    all of the defined indexes.  Currently this can be quite expensive if
+    you have a lot of indexes defined.
+
+    @param {SC.IndexSet} indexes optional from indexes
+    @returns {SC.IndexSet} defined indexes
+  */
+  definedIndexes: function(indexes) {
+    var ret = SC.IndexSet.create(),
+        content = this._sa_content,
+        idx, len;
+
+    if (!content) return ret.freeze(); // nothing to do
+
+    if (indexes) {
+      indexes.forEach(function(idx) {
+        if (content[idx] !== undefined) ret.add(idx);
+      });
+    } else {
+      len = content.length;
+      for(idx=0;idx<len;idx++) {
+        if (content[idx] !== undefined) ret.add(idx);
+      }
+    }
+
+    return ret.freeze();
+  },
+
+  _TMP_RANGE: {},
+
+  /**
+    Called by objectAt() whenever you request an index that has not yet been
+    loaded.  This will possibly expand the index into a range and then invoke
+    an appropriate method on the delegate to request the data.
+
+    It will check if the range has been already requested.
+
+    @param {Number} idx the index to retrieve
+    @returns {SC.SparseArray} receiver
+  */
+  requestIndex: function(idx) {
+    var del = this.delegate;
+    if (!del) return this; // nothing to do
+
+    // adjust window
+    var len = this.get('rangeWindowSize'), start = idx;
+    if (len > 1) start = start - Math.floor(start % len);
+    if (len < 1) len = 1 ;
+
+    // invoke appropriate callback
+    this._requestingIndex++;
+    if (del.sparseArrayDidRequestRange) {
+      var range = this._TMP_RANGE;
+      if(this.wasRangeRequested(start)===-1){
+        range.start = start;
+        range.length = len;
+        this.requestedRangeIndex.push(start);
+        del.sparseArrayDidRequestRange(this, range);
+      }
+    } else if (del.sparseArrayDidRequestIndex) {
+      while(--len >= 0) del.sparseArrayDidRequestIndex(this, start + len);
+    }
+    this._requestingIndex--;
+
+    return this ;
+  },
+
+  /*
+    This method is called by requestIndex to check if the range has already
+    been requested. We assume that rangeWindowSize is not changed often.
+
+     @param {Number} startIndex
+     @return {Number} index in requestRangeIndex
+  */
+  wasRangeRequested: function(rangeStart) {
+    var i, ilen;
+    for(i=0, ilen=this.requestedRangeIndex.length; i<ilen; i++){
+      if(this.requestedRangeIndex[i]===rangeStart) return i;
+    }
+    return -1;
+  },
+
+  /*
+    This method has to be called after a request for a range has completed.
+    To remove the index from the sparseArray to allow future updates on the
+    range.
+
+     @param {Number} startIndex
+     @return {Number} index in requestRangeIndex
+  */
+  rangeRequestCompleted: function(start) {
+    var i = this.wasRangeRequested(start);
+    if(i>=0) {
+      this.requestedRangeIndex.removeAt(i,1);
+      return YES;
+    }
+    return NO;
+  },
+
+  /**
+    This method sets the content for the specified to the objects in the
+    passed array.  If you change the way SparseArray implements its internal
+    tracking of objects, you should override this method along with
+    objectAt().
+
+    @param {Range} range the range to apply to
+    @param {Array} array the array of objects to insert
+    @returns {SC.SparseArray} reciever
+  */
+  provideObjectsInRange: function(range, array) {
+    var content = this._sa_content ;
+    if (!content) content = this._sa_content = [] ;
+    var start = range.start, len = range.length;
+    while(--len >= 0) content[start+len] = array.objectAt(len);
+    if (this._requestingIndex <= 0) this.enumerableContentDidChange(range.start, range.length);
+    return this ;
+  },
+
+  /**
+    Convenience method to provide a single object at a specified index.  Under
+    the covers this calls provideObjectsInRange() so you can override only
+    that method and this one will still work.
+
+    @param {Number} index the index to insert
+    @param {Object} the object to insert
+    @return {SC.SparseArray} receiver
+  */
+  provideObjectAtIndex: function(index, object) {
+    var array = this._TMP_PROVIDE_ARRAY, range = this._TMP_PROVIDE_RANGE;
+    array[0] = object;
+    range.start = index;
+    return this.provideObjectsInRange(range, array);
+  },
+
+  /**
+    Invalidates the array content in the specified range.  This is not the
+    same as editing an array.  Rather it will cause the array to reload the
+    content from the delegate again when it is requested.
+
+    @param {Range} the range
+    @returns {SC.SparseArray} receiver
+  */
+  objectsDidChangeInRange: function(range) {
+
+    // delete cached content
+    var content = this._sa_content ;
+    if (content) {
+      // if range covers entire length of cached content, just reset array
+      if (range.start === 0 && SC.maxRange(range)>=content.length) {
+        this._sa_content = null ;
+
+      // otherwise, step through the changed parts and delete them.
+      } else {
+        var start = range.start, loc = Math.min(start + range.length, content.length);
+        while (--loc>=start) content[loc] = undefined;
+      }
+    }    
+    this.enumerableContentDidChange(range.start, range.length) ; // notify
+    return this ;
+  },
+
+  /**
+    Optimized version of indexOf().  Asks the delegate to provide the index
+    of the specified object.  If the delegate does not implement this method
+    then it will search the internal array directly.
+
+    @param {Object} obj the object to search for
+    @returns {Number} the discovered index or -1 if not found
+  */
+  indexOf: function(obj) {
+    var del = this.delegate ;
+    if (del && del.sparseArrayDidRequestIndexOf) {
+      return del.sparseArrayDidRequestIndexOf(this, obj);
+    } else {
+      var content = this._sa_content ;
+      if (!content) content = this._sa_content = [] ;
+      return content.indexOf(obj) ;
+    }
+  },
+
+  // ..........................................................
+  // EDITING
+  //
+
+  /**
+    Array primitive edits the objects at the specified index unless the
+    delegate rejects the change.
+
+    @param {Number} idx the index to begin to replace
+    @param {Number} amt the number of items to replace
+    @param {Array} objects the new objects to set instead
+    @returns {SC.SparseArray} receiver
+  */
+  replace: function(idx, amt, objects) {
+    objects = objects || [] ;
+
+    // if we have a delegate, get permission to make the replacement.
+    var del = this.delegate ;
+    if (del) {
+      if (!del.sparseArrayShouldReplace ||
+          !del.sparseArrayShouldReplace(this, idx, amt, objects)) {
+            return this;
+      }
+    }
+
+    // go ahead and apply to local content.
+    var content = this._sa_content ;
+    if (!content) content = this._sa_content = [] ;
+    content.replace(idx, amt, objects) ;
+
+    // update length
+    var len = objects ? (objects.get ? objects.get('length') : objects.length) : 0;
+    var delta = len - amt ;
+    if (!SC.none(this._length)) {
+      this.propertyWillChange('length');
+      this._length += delta;
+      this.propertyDidChange('length');
+    }
+
+    this.enumerableContentDidChange(idx, amt, delta) ;
+    return this ;
+  },
+
+  /**
+    Resets the SparseArray, causing it to reload its content from the
+    delegate again.
+
+    @returns {SC.SparseArray} receiver
+  */
+  reset: function() {
+    this._sa_content = null ;
+    this._length = null ;
+    this.enumerableContentDidChange() ;
+    this.invokeDelegateMethod(this.delegate, 'sparseArrayDidReset', this);
+    return this ;
+  }
+
+}) ;
+
+/**
+  Convenience metohd returns a new sparse array with a default length already
+  provided.
+
+  @param {Number} len the length of the array
+  @returns {SC.SparseArray}
+*/
+SC.SparseArray.array = function(len) {
+  return this.create({ _length: len||0 });
+};

data/sproutcore/frameworks/core_foundation/system/theme.js

@@ -0,0 +1,316 @@
+// ==========================================================================
+// 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
+  Represents a theme, and is also the core theme in which SC looks for
+  other themes.
+
+  If an SC.View has a theme of "ace", it will look in its parent's theme
+  for the theme "ace". If there is no parent--that is, if the view is a
+  frame--it will look in SC.Theme for the named theme. To find a theme,
+  it calls find(themeName) on the theme.
+
+  To be located, themes must be registered either as a root theme (by
+  calling SC.Theme.addTheme) or as a child theme of another theme (by
+  calling theTheme.addTheme).
+
+  All themes are instances. However, new instances based on the current
+  instance can always be created: just call .create(). This method is used
+  by SC.View when you name a theme that doesn't actually exist: it creates
+  a theme based on the parent theme.
+
+  Renderers
+  ---------------------------
+  Themes are used to keep track of theme class names and, more important,
+  to keep track of renderers.
+
+  Renderers are added to a theme using theme.addRenderer(theRenderer). After
+  this has been done, they may be instantiated using theme.renderer(rendererName).
+
+  Instantiating with renderer() instantiates a version of that renderer
+  specialized for this specific theme-- not any parent themes. The renderer
+  will include all class names for _this_ theme. This means that you can
+  theme controls differently without overriding any renderers: just subclass
+  the original theme that _has_ the renderers, give it its own name, and
+  all renderers will render with that name as a class name.
+
+  Locating Child Themes
+  ----------------------------
+  Locating child themes is relatively simple for the most part: it looks in
+  its own "themes" property, which is an object inheriting from its parent's
+  "themes" set, so it includes all parent themes.
+
+  However, it does _not_ include global themes. This is because, when find()
+  is called, it wants to ensure any child theme is specialized. That is, the
+  child theme should include all class names of the base class theme. This only
+  makes sense if the theme really is a child theme of the theme or one of its
+  base classes; if the theme is a global theme, those class names should not
+  be included.
+
+  This makes sense logically as well, because when searching for a renderer,
+  it will locate it in any base theme that has it, but that doesn't mean
+  class names from the derived theme shouldn't be included.
+
+  @extends SC.Object
+  @since SproutCore 1.1
+  @author Alex Iskander
+*/
+SC.Theme = {
+  /**
+    Walks like a duck.
+  */
+  isTheme: YES,
+
+  /**
+    Class names for the theme.
+
+    These class names include the name of the theme and the names
+    of all parent themes. You can also add your own.
+   */
+  classNames: SC.CoreSet.create(),
+
+  /**
+    @private
+    A helper to extend class names with another set of classnames. The
+    other set of class names can be a hash, an array, a Set, or a space-
+    delimited string.
+  */
+  _extend_class_names: function(classNames) {
+    // class names may be a CoreSet, array, string, or hash
+    if (classNames) {
+      if (SC.typeOf(classNames) === SC.T_HASH && !classNames.isSet) {
+        for (var className in classNames) {
+          if (classNames[className]) this.classNames.add(className);
+          else this.classNames.remove(className);
+        }
+      } else if (typeof classNames === "string") {
+        this.classNames.addEach(classNames.split(' '));
+      } else {
+        // it must be an array or another CoreSet... same difference.
+        this.classNames.addEach(classNames);
+      }
+    }
+  },
+
+  /**
+    @private
+    Helper method that extends this theme with some extra properties.
+
+    Used during Theme.create();
+   */
+  _extend_self: function(ext) {
+    if (ext.classNames) this._extend_class_names(ext.classNames);
+
+    // mixin while enabling sc_super();
+    var key, value, cur;
+    for (key in ext) {
+      if (key === 'classNames') continue; // already handled.
+      if (!ext.hasOwnProperty(key)) continue;
+
+      value = ext[key];
+      if (value instanceof Function && !value.base && (value !== (cur=this[key]))) {
+        value.base = cur;
+      }
+
+      this[key] = value;
+    }
+  },
+
+  /**
+    Creates a new theme based on this one. The name of the new theme will
+    be added to the classNames set.
+  */
+  create: function() {
+    var result = SC.beget(this);
+    result.baseTheme = this;
+
+    // if we don't beget themes, the same instance would be shared between
+    // all themes. this would be bad: imagine that we have two themes:
+    // "Ace" and "Other." Each one has a "capsule" child theme. If they
+    // didn't have their own child themes hash, the two capsule themes
+    // would conflict.
+    if (this.themes === SC.Theme.themes) {
+      result.themes = {};
+    } else {
+      result.themes = SC.beget(this.themes);
+    }
+    
+    // we also have private ("invisible") child themes; look at invisibleSubtheme
+    // method.
+    result._privateThemes = {};
+
+    // the theme also specializes all renderers it creates so that they
+    // have the theme's classNames and have their 'theme' property set.
+    result._specializedRenderers = {};
+
+    // also, the theme specializes all child themes as they are created
+    // to ensure that all of the class names on this theme are included.
+    result._specializedThemes = {};
+
+    // we could put this in _extend_self, but we don't want to clone
+    // it for each and every argument passed to create().
+    result.classNames = SC.clone(this.classNames);
+
+    var args = arguments, len = args.length, idx, mixin;
+    for (idx = 0; idx < len; idx++) {
+      result._extend_self(args[idx]);
+    }
+
+    if (result.name) result.classNames.add(result.name);
+
+    return result;
+  },
+
+  /**
+    Creates a child theme based on this theme, with the given name,
+    and automatically registers it as a child theme.
+  */
+  subtheme: function(name) {
+    // extend the theme
+    var t = this.create({ name: name });
+
+    // add to our set of themes
+    this.addTheme(t);
+
+    // and return the theme class
+    return t;
+  },
+  
+  /**
+    Semi-private, only used by SC.View to create "invisible" subthemes. You
+    should never need to call this directly, nor even worry about.
+    
+    Invisible subthemes are only available when find is called _on this theme_;
+    if find() is called on a child theme, it will _not_ locate this theme.
+    
+    The reason for "invisible" subthemes is that SC.View will create a subtheme
+    when it finds a theme name that doesn't exist. For example, imagine that you 
+    have a parent view with theme "base", and a child view with theme "popup".
+    If no "popup" theme can be found inside "base", SC.View will call
+    base.subtheme. This will create a new theme with the name "popup",
+    derived from "base". Everyone is happy.
+    
+    But what happens if you then change the parent theme to "ace"? The view
+    will try again to find "popup", and it will find it-- but it will still be
+    a child theme of "base"; SC.View _needs_ to re-subtheme it, but it won't
+    know it needs to, because it has been found.
+  */
+  invisibleSubtheme: function(name) {
+    // extend the theme
+    var t = this.create({ name: name });
+
+    // add to our set of themes
+    this._privateThemes[name] = t;
+    
+    // and return the theme class
+    return t;
+  },
+  
+  //
+  // THEME MANAGEMENT
+  //
+
+  themes: {},
+
+  /**
+    Finds a theme by name within this theme (the theme must have
+    previously been added to this theme or a base theme by using addTheme, or
+    been registered as a root theme).
+
+    If the theme found is not a root theme, this will specialize the theme so
+    that it includes all class names for this theme.
+  */
+  find: function(themeName) {
+    if (this === SC.Theme) return this.themes[themeName];
+    var theme;
+
+    // if there is a private theme (invisible subtheme) by that name, use it
+    theme = this._privateThemes[themeName];
+    if (theme) return theme;
+
+    // if there is a specialized version (the theme extended with our class names)
+    // return that one
+    theme = this._specializedThemes[themeName];
+    if (theme) return theme;
+
+    // otherwise, we may need to specialize one.
+    theme = this.themes[themeName];
+    if (theme && !this._specializedThemes[themeName]) {
+      return (this._specializedThemes[themeName] = theme.create({ classNames: this.classNames }));
+    }
+
+    // and finally, if it is a root theme, we do nothing to it.
+    theme = SC.Theme.themes[themeName];
+    if (theme) return theme;
+
+    return null;
+  },
+
+  /**
+    Adds a child theme to the theme. This allows the theme to be located
+    by SproutCore views and such later.
+
+    Each theme is registered in the "themes" property by name. Calling
+    find(name) will return the theme with the given name.
+
+    Because the themes property is an object begetted from (based on) any
+    parent theme's "themes" property, if the theme cannot be found in this
+    theme, it will be found in any parent themes.
+  */
+  addTheme: function(theme) {
+    this.themes[theme.name] = theme;
+  },
+
+  /**
+    Adds a renderer to the theme. The renderer's name will be used to
+    keep track of it and identify it later.
+
+    The biggest responsibility of addRenderer is to ensure that renderer()
+    can be used to instantiate that renderer. If a renderer is not instantiated
+    through renderer(), it will not know its theme's classNames.
+  */
+  addRenderer: function(renderer) {
+    this[renderer.name] = renderer;
+  },
+
+   /**
+     Finds the named renderer and instantiates it, returning the result.
+     It also ensures it is using a version of the renderer specialized for
+     this theme. It keeps a cache of specialized versions of the renderer.
+
+     Any arguments after the name are passed on to the instantiated
+     renderer.
+   */
+  renderer: function(name) {
+    var renderer = this._specializedRenderers[name], base = this[name];
+    if (!renderer || renderer._specializedFrom !== base) {
+      if (!base) return null;
+
+      renderer = base.extend({ classNames: this.classNames, theme: this });
+    }
+
+    var args = SC.$A(arguments);
+    args.shift();
+    renderer = renderer.create.apply(renderer, args);
+    return renderer;
+  }
+};
+
+// SproutCore _always_ has its base theme. This is not quite
+// optimal, but the reasoning is because of test running: the
+// test runner, when running foundation unit tests, cannot load
+// the theme. As such, foundation must include default versions of
+// all of its renderers, and it does so in BaseTheme. All SproutCore
+// controls have renderers in BaseTheme.
+SC.BaseTheme = SC.Theme.create({
+  name: '' // it is a base class, and doesn't need a class name or such
+});
+
+// however, SproutCore does need a default theme, even if no
+// actual theme is loaded.
+SC.Theme.themes['sc-base'] = SC.BaseTheme;
+SC.defaultTheme = 'sc-base';