sproutit-sproutcore 1.0.0.20090416161445 → 1.0.0.20090720093355

data/frameworks/sproutcore/frameworks/foundation/mixins/selection_support.js

@@ -33,122 +33,200 @@
 */
 SC.SelectionSupport = {
   
-  /** 
-    Call this method whenever your source content changes to ensure the 
-    selection always remains up-to-date and valid.
-  */
-  updateSelectionAfterContentChange: function() {
-    var objects = SC.makeArray(this.get('arrangedObjects')) ;
-    var currentSelection = SC.makeArray(this.get('selection')) ;
-    var sel = [] ;
-    
-    // the new selection is the current selection that exists in 
-    // arrangedObjects or an empty selection if selection is not allowed.
-    var max = currentSelection.get('length') ;
-    if (this.get('allowsSelection')) {
-      for(var idx=0;idx<max;idx++) {
-        var obj = currentSelection.objectAt(idx) ;
-        if (objects.indexOf(obj) >= 0) sel.push(obj) ;
-      }
-    }
-    
-    // if the new selection is a multiple selection, get the first object
-    var selectionLength = sel.get('length') ;
-    if ((selectionLength > 1) && !this.get('allowsMultipleSelection')) {
-      sel = [sel.objectAt(0)] ;
-    }
-    
-    // if the selection is empty, select the first item.
-    if ((selectionLength == 0) && !this.get('allowsEmptySelection')) {
-      if (objects.get('length') > 0) sel = [objects.objectAt(0)] ;
-    }
-    
-    // update the selection.
-    this.set('selection', sel) ;
-  },
+  // ..........................................................
+  // PROPERTIES
+  // 
+  
+  hasSelectionSupport: YES,
   
   /**
-    @property
-    @type SC.Array
+    If YES, selection is allowed. Default is YES.
     
-    Returns the set of content objects the selection should be a part of.
-    Selections in general may contain objects outside of this content, but
-    this set will be used when enforcing items such as no empty selection.
+    @type Boolean
+  */
+  allowsSelection: YES,
+  
+  /**
+    If YES, multiple selection is allowed. Default is YES.
     
-    The default version of this property returns the receiver.
+    @type Boolean
   */
-  arrangedObjects: function() { return this; }.property(),
+  allowsMultipleSelection: YES,
   
   /**
-    @property
-    @type SC.Set
+    If YES, allow empty selection Default is YES.
     
+    @type Boolean
+  */
+  allowsEmptySelection: YES,
+  
+  /**
     This is the current selection.  You can make this selection and another
     controller's selection work in concert by binding them together. You
     generally have a master selection that relays changes TO all the others.
+    
+    @property
+    @type SC.SelectionSet
   */
   selection: function(key, value) {
+    var content, empty;
+    
     if (value !== undefined) {
-      // are we even allowing selection at all? If not, return early...
-      if (!this.get('allowsSelection')) return this._selection ;
-      
-      value = SC.makeArray(value) ; // always force to an array
       
-      // ok, new decide if the *type* of seleciton is allowed...
-      switch (value.get('length')) {
-        case 0:
-          // check to see if we're attemting to set an empty array
+      // are we even allowing selection at all?  Also, must be enumerable
+      if (this.get('allowsSelection') && value && value.isEnumerable) {
+        
+        // ok, new decide if the *type* of selection is allowed...
+        switch (value.get('length')) {
+          
+          // check to see if we're attempting to set an empty array
           // if that's not allowed, set to the first available item in 
           // arrangedObjects
-          if (!this.get('allowsEmptySelection')) {
-            var objects = this.get('arrangedObjects') ;
-            if (objects.get('length') > 0) value = [objects.objectAt(0)];
-          }
-          this._selection = value ;
-          break;
-        case 1:
-          this._selection = value;
-          break;
-        default:
+          case 0:
+            empty   = this.get('allowsEmptySelection');
+            content = this.get('arrangedObjects');
+            if (empty && content && content.get('length')>0) {
+                value = SC.SelectionSet.create().add(content, 0).freeze();
+            } else value = null ;
+            break;
+            
+          // single items are always allows
+          case 1:
+            break;
+
           // fall through for >= 2, only allow if configured for multi-select
-          this._selection = this.get('allowsMultipleSelection') ?
-            value :
-            this._selection ;
-          break;
-      }
-    }
-    else return this._selection ;
-  }.property(),
+          default:
+            if (!this.get('allowsMultipleSelection')) value = null;
+            break;
+        }
+      } else value = null;
+      
+      // always make selection into something then save
+      if (!value) value = SC.SelectionSet.EMPTY;
+      this._scsel_selection = value;
+      
+    // read only mode
+    } else return this._scsel_selection ;
+    
+  }.property('arrangedObjects', 'allowsEmptySelection', 
+      'allowsMultipleSelection', 'allowsSelection').cacheable(),
   
   /**
-    If YES, selection is allowed. Default is YES.
+    YES if the receiver currently has a non-zero selection.
     
-    @type Boolean
+    @property Boolean
   */
-  allowsSelection: YES,
+  hasSelection: function() {
+    var sel = this.get('selection') ;
+    return !!sel && (sel.get('length') > 0) ;
+  }.property('selection').cacheable(),
   
+  // ..........................................................
+  // METHODS
+  // 
+
   /**
-    If YES, multiple selection is allowed. Default is YES.
-    
-    @type Boolean
+    Selects the passed objects in your content.  If you set "extend" to YES,
+    then this will attempt to extend your selection as well.
+  
+    @param {SC.Enumerable} objects objects to select
+    @param {Boolean} extend optionally set to YES to extend selection
+    @returns {Object} receiver
   */
-  allowsMultipleSelection: YES,
+  selectObjects: function(objects, extend) {
+
+    // handle passing an empty array
+    if (!objects || objects.get('length')===0) {
+      if (!extend) this.set('selection', SC.SelectionSet.EMPTY);
+      return this;
+    }
+    
+    var sel = this.get('selection');
+    if (extend && sel) sel = sel.copy();
+    else sel = SC.SelectionSet.create();
+    
+    sel.addObjects(objects).freeze();
+    this.set('selection', sel);
+    return this ;
+  },
   
   /**
-    If YES, allow empty selection Default is YES.
+    Selects a single passed object in your content.  If you set "extend" to 
+    YES then this will attempt to extend your selection as well.
     
-    @type Boolean
+    @param {Object} object object to select
+    @param {Boolean} extend optionally set to YES to extend selection
+    @returns {Object} receiver
   */
-  allowsEmptySelection: YES,
+  selectObject: function(object, extend) {
+    if (object === null) {
+      if (!extend) this.set('selection', null);
+      return this ;
+      
+    } else return this.selectObjects([object], extend);
+  },    
+
+  /**
+    Deselects the passed objects in your content.
+    
+    @param {SC.Enumerable} objects objects to select
+    @returns {Object} receiver
+  */
+  deselectObjects: function(objects) {
+
+    if (!objects || objects.get('length')===0) return this; // nothing to do
+    
+    var sel = this.get('selection');
+    if (!sel || sel.get('length')===0) return this; // nothing to do
+
+    // find index for each and remove it
+    sel = sel.copy().removeObjects(objects).freeze();
+    this.set('selection', sel.freeze());
+    return this ;
+  },
   
   /**
-    YES if the receiver currently has a non-zero selection.
+    Deselects the passed object in your content.
     
-    @property Boolean
+    @param {SC.Object} object single object to select
+    @returns {Object} receiver
   */
-  hasSelection: function() {
-    var sel = this.get('selection') ;
-    return !!sel && (sel.get('length') > 0) ;
-  }.property('selection')
+  deselectObject: function(object) {
+    if (!object) return this; // nothing to do
+    else return this.deselectObjects([object]);
+  },
+  
+  /** 
+    Call this method whenever your source content changes to ensure the 
+    selection always remains up-to-date and valid.
+  */
+  updateSelectionAfterContentChange: function() {
+    
+    var content = this.get('arrangedObjects'),
+        sel     = this.get('selection'),
+        indexes, len, max, ret;
+
+    if (!sel) sel = SC.SelectionSet.EMPTY;
+    
+    // if selection is not allowed, just force to be empty.
+    if (!this.get('allowsSelection') && sel.get('length')>0) {
+      ret = SC.SelectionSet.EMPTY;
+      
+      
+    // selection is allowed, make sure it is valid
+    } else {
+      
+      // remove from the sel any items selected beyond the length of the new
+      // arrangedObjects
+      indexes = content ? sel.indexSetForSource(content) : null;
+      len     = content ? content.get('length') : 0;
+      max     = indexes ? indexes.get('max') : 0;
+      if (max > len) ret = sel.copy().constrain(content).freeze();
+      
+    }
   
+    if (ret) this.set('selection', ret);
+    return this ;
+  }
+    
 };

data/frameworks/sproutcore/frameworks/foundation/mixins/static_layout.js

@@ -27,17 +27,46 @@
   
   To enable static layout on your view, just include this mixin on the view.
   SproutCore's builtin views that are capable of being used in static 
-  layouts already incorporate this mixin.  
+  layouts already incorporate this mixin.  Then set the "useStaticLayout" 
+  property on your view class to YES.
   
   You can then use CSS or the render() method on your view to setup the 
   positioning on your view using any browser layout mechanism you want.
   
+  h2. Example
+  
+  {{{
+    
+    // JavaScript
+    
+    MyApp.CommentView = SC.View.extend(SC.StaticLayout, {
+    
+      classNames: ['comment-view'],
+      
+      useStaticLayout: YES,
+
+      ...
+    });
+    
+    // CSS
+    
+    .comment-view {
+      display: block;
+      position: relative;
+    }
+    
+  }}}
+  
   @since SproutCore 1.0
 */
 SC.StaticLayout = {
 
   /**
-    Walk like a duck
+    Walk like a duck.  Used to determine that this mixin has been applied.  
+    Note that a view that hasStaticLayout still may not actually use static
+    layout unless useStaticLayout is also set to YES.
+    
+    @type {Boolean}
   */
   hasStaticLayout: YES,
   
@@ -45,6 +74,8 @@ SC.StaticLayout = {
     Activates use of brower's static layout.  You can apply this mixin and
     still use absolute positioning.  To activate static positioning, set this
     property to YES.
+
+    @type {Boolean}
   */
   useStaticLayout: NO,
   

data/frameworks/sproutcore/frameworks/foundation/mixins/string.js

@@ -5,6 +5,8 @@
 // License:   Licened under MIT license (see license.js)
 // ==========================================================================
 
+sc_require('system/locale');
+
 // These are basic enhancements to the string class used throughout 
 // SproutCore.
 SC.STRING_TITLEIZE_REGEXP = (/([\s|\-|\_|\n])([^\s|\-|\_|\n]?)/g);
@@ -224,10 +226,22 @@ SC.String = {
     return this.replace(/^\s+|\s+$/g,"");
   },
   
-  /** Splits the string into words, separated by spaces.  */
-  w: function() { return this.split(' '); }
+  /**
+    Splits the string into words, separated by spaces. Empty strings are
+    removed from the results.
     
-} ;
+    @returns {Array} an array of non-empty strings
+  */
+  w: function() { 
+    var ary = [], ary2 = this.split(' '), len = ary2.length ;
+    for (var idx=0; idx<len; ++idx) {
+      var str = ary2[idx] ;
+      if (str.length !== 0) ary.push(str) ; // skip empty strings
+    }
+    return ary ;
+  }
+  
+};
 
 SC.String.strip = SC.String.trim; // convenience alias.
 

data/frameworks/sproutcore/frameworks/foundation/mixins/tree_item_content.js

@@ -0,0 +1,159 @@
+// ==========================================================================
+// 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)
+// ==========================================================================
+
+/**
+  @namespace
+
+  A tree item is a model object that acts as a node in a tree-like data 
+  structure such as a hierarchy of folders or outline of items.  This mixin 
+  can be applied to tree item model objects to customize the way the tree
+  information is extracted from the object.
+
+  h2. Basic Implementation
+  
+  If you add this mixin, you must implement the treeItemChildren property so
+  that it returns the current array of child tree items for the receiver.  If
+  you do not implement this property the tree item will not function.
+  
+  h2. Optimizing Branches
+  
+  The most common use of this mixin is to override the treeItemBranchIndexes
+  property to return an index set of child items that are themselves branches
+  in the tree.  Normally the TreeController will need to walk every item in
+  your list to determine these branch items.  However by implementing this 
+  method yourself, you can provide a result faster.
+  
+  If none of your child items are branches, override this property to return
+  null or an empty index set.
+  
+  @since SproutCore 1.0
+*/
+SC.TreeItemContent = {
+
+  /** Walk like a duck. */
+  isTreeItemContent: YES,
+  
+  /**
+    Property returns the children for this tree item.  The default simply 
+    returns null.  If you implement this mixin, you MUST implement this 
+    property to return the actual tree item children for the item.
+   
+    @property
+    @type {SC.Array}
+  */
+  treeItemChildren: null,
+
+  /**
+    The default property used to determine if the tree item is expanded.  You
+    can implement you model object to update this property or you can override
+    treeItemDisclosureState() to compute the disclosure state however you 
+    want.
+    
+    @property 
+    @type {Boolean}
+  */
+  treeItemIsExpanded: YES,
+  
+  /**
+    Indicates whether the tree item should be rendered as a group or not. 
+    This property is only useful on the root item in your tree.  Setting it to
+    YES on any other item will be ignored.
+    
+    @property
+    @type {Boolean}
+  */
+  treeItemIsGrouped: NO,
+  
+  /**
+    Returns the disclosure state for the tree item, which appears at the 
+    index of the parent's treeItemChildren array.  The response must be one of 
+    SC.BRANCH_OPEN, SC.BRANCH_CLOSED or SC.LEAF_NODE.
+     
+    If the parent parameter is null, then this item is part of the root 
+    children array.
+    
+    This method will only be called for tree items that have children.  Tree
+    items with no children are assumed to be leaf nodes.
+
+    The default implementation uses the treeItemIsExpanded property to 
+    determine if the item should be open or closed.
+    
+    @param {Object} parent the parent item containing this item
+    @param {Number} idx the index of the item in the parent
+    @returns {Number} branch state
+  */
+  treeItemDisclosureState: function(parent, idx) {
+    return this.get('treeItemIsExpanded') ? SC.BRANCH_OPEN : SC.BRANCH_CLOSED;
+  },
+  
+  /**
+    Collapse the tree item.  The default implementation will change the 
+    treeItemIsExpanded property, but you can override this method to handle
+    collapsing anyway you like.
+    
+    @param {Object} parent the parent item containing this item
+    @param {Number} idx the index of the item in the parent
+    @returns {void}
+  */
+  treeItemCollapse: function(parent, idx) {
+    this.setIfChanged('treeItemIsExpanded', NO);    
+  },
+
+  /**
+    Expand the tree item.  The default implementation will change the 
+    treeItemIsExpanded property, but you can override this method to handle
+    collapsing anyway you like.
+    
+    @param {Object} parent the parent item containing this item
+    @param {Number} idx the index of the item in the parent
+    @returns {void}
+  */
+  treeItemExpand: function(parent, idx) {
+    this.setIfChanged('treeItemIsExpanded', YES);    
+  },
+  
+  /**
+    Returns an index set containing the child indexes of the item that are 
+    themselves branches.  This will only be called on tree items with a branch
+    disclosure state.
+
+    If the passed parent and index are both null, then the receiver is the 
+    root node in the tree.
+    
+    The default implementation iterates over the item's children to get the
+    disclosure state of each one.  Child items with a branch disclosure state
+    will have their index added to the return index set.  
+    
+    You may want to override this method to provide a more efficient 
+    implementation if you are working with large data sets and can infer which
+    children are branches without iterating over each one.
+
+    If you know for sure that all of the child items for this item are leaf
+    nodes and not branches, simply override this method to return null.
+    
+    @param {Object} parent the parent item containing this item
+    @param {Number} index the index of the item in the parent
+    @param {SC.IndexSet} branch indexes
+  */
+  treeItemBranchIndexes: function(parent, index) {
+    var children = this.get('treeItemChildren'),
+        ret, lim, idx, item;
+        
+    if (!children) return null ; // nothing to do
+    
+    ret = SC.IndexSet.create();
+    lim = children.get('length');
+    for(idx=0;idx<lim;idx++) {
+      if (!(item = children.objectAt(idx))) continue;
+      if (!item.get('treeItemChildren')) continue;
+      if (item.treeItemDisclosureState(this,idx)!==SC.LEAF_NODE) ret.add(idx);
+    }
+
+    return ret.get('length')>0 ? ret : null;
+  }
+  
+};