sproutcore 1.5.0.rc.1 → 1.5.0.rc.2

data/lib/frameworks/sproutcore/frameworks/desktop/core.js

@@ -12,7 +12,23 @@
   
   Usually it is best to leave this property set to NO in order to prever the
   user from inadvertantly losing data by pressing the backspace key.
-  
-  @property {Boolean}
+
+  @static
+  @type Boolean
+  @default NO
 */
 SC.allowsBackspaceToPreviousPage = NO;
+
+/**
+  @type String
+  @static
+  @constant
+*/
+SC.HORIZONTAL_ORIENTATION = 'horizontal';
+
+/**
+  @type String
+  @static
+  @constant
+*/
+SC.VERTICAL_ORIENTATION = 'vertical' ;

data/lib/frameworks/sproutcore/frameworks/desktop/mixins/border.js

@@ -15,6 +15,10 @@ SC.BORDER_NONE   = null ;
 
 /**
   @namespace
+  @deprecated
+
+  The SC.Border mixin has be deprecated in favour of applying border properties
+  to an SC.View's layout object. See {@link SC.View#layout}.
 
   The Border mixin can be applied to any view to give it a visual border.
   In addition to specifying the mixin itself, you should specify the border
@@ -28,20 +32,21 @@ SC.BORDER_NONE   = null ;
 
   SproutCore pre-defines several useful border styles including:
 
-- SC.BORDER_BEZEL  - displays an inlaid bezel
-- SC.BORDER_BLACK  - displays a black border
-- SC.BORDER_GRAY   - displays a gray border
-- SC.BORDER_TOP    - displays a border on the top only
-- SC.BORDER_BOTTOM - displays a border on the bottom only
-- SC.BORDER_NONE   - disables the border
+    - SC.BORDER_BEZEL  - displays an inlaid bezel
+    - SC.BORDER_BLACK  - displays a black border
+    - SC.BORDER_GRAY   - displays a gray border
+    - SC.BORDER_TOP    - displays a border on the top only
+    - SC.BORDER_BOTTOM - displays a border on the bottom only
+    - SC.BORDER_NONE   - disables the border
 
   @since SproutCore 1.0
 */
 SC.Border = {
+
   /**
     The thickness of the top border.
 
-    @property {Number}
+    @type Number
     @commonTask Border Dimensions
   */
   borderTop: 0,
@@ -49,7 +54,7 @@ SC.Border = {
   /**
     The thickness of the right border.
 
-    @property {Number}
+    @type Number
     @commonTask Border Dimensions
   */
   borderRight: 0,
@@ -57,7 +62,7 @@ SC.Border = {
   /**
     The thickness of the bottom border.
 
-    @property {Number}
+    @type Number
     @commonTask Border Dimensions
   */
   borderBottom: 0,
@@ -65,7 +70,7 @@ SC.Border = {
   /**
     The thickness of the left border.
 
-    @property {Number}
+    @type Number
     @commonTask Border Dimensions
   */
   borderLeft: 0,
@@ -73,12 +78,13 @@ SC.Border = {
   /**
     The style of the border. You may specify a color string (like 'red' or
     '#fff'), a CSS class name, or one of:
-- SC.BORDER_BEZEL
-- SC.BORDER_BLACK
-- SC.BORDER_GRAY
-- SC.BORDER_TOP
-- SC.BORDER_BOTTOM
-- SC.BORDER_NONE
+
+      - SC.BORDER_BEZEL
+      - SC.BORDER_BLACK
+      - SC.BORDER_GRAY
+      - SC.BORDER_TOP
+      - SC.BORDER_BOTTOM
+      - SC.BORDER_NONE
 
     If you specify a CSS class name, it must end in "-border".
   */
@@ -132,6 +138,7 @@ SC.Border = {
     }
   },
 
+  /** @private */
   _sc_border_borderDimensionsDidChange: function(){
     var borderTop     = this.get('borderTop'),
         borderRight   = this.get('borderRight'),

data/lib/frameworks/sproutcore/frameworks/desktop/mixins/collection_fast_path.js

@@ -4,11 +4,15 @@
 //            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
+
 /** 
+  @namespace
+  
   An experimental CollectionView mixin that makes it extremely fast under
   certain circumstances, including for mobile devices.
 */
 SC.CollectionFastPath = {
+
   //
   // ITEM VIEW CLASS/INSTANCE MANAGEMENT
   //
@@ -20,6 +24,8 @@ SC.CollectionFastPath = {
     Returns the pool for a given example view.
     
     The pool is calculated based on the guid for the example view class.
+    
+    @param {SC.View} exampleView
   */
   poolForExampleView: function(exampleView) {
     var poolKey = "_pool_" + SC.guidFor(exampleView);
@@ -30,6 +36,9 @@ SC.CollectionFastPath = {
   /**
     Creates an item view from a given example view, configuring it with basic settings
     and the supplied attributes.
+    
+    @param {SC.View} exampleView
+    @param {Hash} attrs
   */
   createItemViewFromExampleView: function(exampleView, attrs) {
     // create the example view
@@ -48,6 +57,10 @@ SC.CollectionFastPath = {
     return ret;
   },
   
+  /**
+    @param {SC.View} itemView
+    @param {Hash} attrs
+  */
   configureItemView: function(itemView, attrs) {
     // set settings. Self explanatory.
     itemView.beginPropertyChanges();
@@ -68,6 +81,9 @@ SC.CollectionFastPath = {
   
   /**
     Configures a pooled view, calling .awakeFromPool if it is defined.
+
+    @param {SC.View} itemView
+    @param {Hash} attrs
   */
   wakePooledView: function(itemView, attrs) {
     // configure
@@ -80,6 +96,9 @@ SC.CollectionFastPath = {
   /**
     Gets an item view from an example view, from a pool if possible, and otherwise
     by generating it.
+    
+    @param {SC.View} exampleView
+    @param {Hash} attrs
   */
   allocateItemView: function(exampleView, attrs) {
     // we will try to get it from a pool. This will fill ret. If ret is not
@@ -109,6 +128,8 @@ SC.CollectionFastPath = {
     This is called for one of two purposes: to release a view that is no longer displaying,
     or to release an older cached version of a view that needed to be replaced because the
     example view changed.
+
+    @param {SC.View} itemView
   */
   releaseItemView: function(itemView) {
     // if it is not poolable, there is not much we can do.
@@ -123,10 +144,8 @@ SC.CollectionFastPath = {
     if (itemView.hibernateInPool) itemView.hibernateInPool(pool, this);
   },
   
-  /**
+  /** @private
     Returns YES if the item at the index is a group.
-    
-    @private
   */
   contentIndexIsGroup: function(view, content, index) {
     var contentDelegate = this.get("contentDelegate");
@@ -142,8 +161,7 @@ SC.CollectionFastPath = {
     return isGroupView;
   },
   
-  /**
-    @private
+  /** @private
     Determines the example view for a content index. There are two optional parameters that will
     speed things up: contentObject and isGroupView. If you don't supply them, they must be computed.
   */
@@ -168,15 +186,12 @@ SC.CollectionFastPath = {
     return ExampleView;
   },
   
-  /**
+  /** @private
     This may seem somewhat awkward, but it is for memory performance: this fills in a hash
     YOU provide with the properties for the given content index.
     
     Properties include both the attributes given to the view and some CollectionView tracking
     properties, most importantly the exampleView.
-    
-    
-    @private
   */
   setAttributesForItem: function(item, index, attrs) {
     var del = this.get('contentDelegate'), 
@@ -204,15 +219,11 @@ SC.CollectionFastPath = {
     if (!attrs.layout) attrs.layout = ExampleView.prototype.layout;
   },
   
-  
-  
-  
   //
   // ITEM LOADING/DOM MANAGEMENT
   //
   
-  /**
-    @private
+  /** @private
     Returns mapped item views for the supplied item.
   */
   mappedViewsForItem: function(item, map) {
@@ -220,8 +231,7 @@ SC.CollectionFastPath = {
     return map[SC.guidFor(item)];
   },
   
-  /**
-    @private
+  /** @private
     Returns the mapped view for an item at the specified index. 
   */
   mappedViewForItem: function(item, idx, map) {
@@ -231,8 +241,7 @@ SC.CollectionFastPath = {
     return m[idx];
   },
   
-  /**
-    @private
+  /** @private
     Maps a view to an item/index combination.
   */
   mapView: function(item, index, view, map) {
@@ -249,7 +258,7 @@ SC.CollectionFastPath = {
     imap._length++;
   },
   
-  /**
+  /** @private
     Unmaps a view from an item/index combination.
   */
   unmapView: function(item, index, map) {
@@ -274,6 +283,8 @@ SC.CollectionFastPath = {
     Returns the item view for the given content index.
     NOTE: THIS WILL ADD THE VIEW TO DOM TEMPORARILY (it will be cleaned if
           it is not used). As such, use sparingly.
+
+    @param {Number} index
   */
   itemViewForContentIndex: function(index) {
     var content = this.get("content");
@@ -298,8 +309,7 @@ SC.CollectionFastPath = {
     return view;
   },
   
-  /**
-    @private
+  /** @private
     Returns the nearest item view index to the supplied index mapped to the item.
   */
   nearestMappedViewIndexForItem: function(item, index, map) {
@@ -326,8 +336,7 @@ SC.CollectionFastPath = {
     return nearest;
   },
   
-  /**
-    @private
+  /** @private
     Remaps the now showing views to their new indexes (if they have moved).
   */
   remapItemViews: function(nowShowing) {
@@ -394,6 +403,9 @@ SC.CollectionFastPath = {
   
   /**
     Reloads.
+
+    @param {SC.IndexSet} nowShowing
+    @param {Boolean} scrollOnly
   */
   reloadIfNeeded: function(nowShowing, scrollOnly) {
     var content = this.get("content"), invalid;
@@ -450,6 +462,8 @@ SC.CollectionFastPath = {
   
   /**
     Loops through remove queue and removes.
+
+    @param {Hash} oldMap
   */
   processRemovals: function(oldMap) {
     var content = this.get("content");
@@ -469,8 +483,7 @@ SC.CollectionFastPath = {
     }
   },
   
-  /**
-    @private
+  /** @private
     Loops through update queue and... updates.
   */
   processUpdates: function(invalid) {
@@ -485,8 +498,7 @@ SC.CollectionFastPath = {
     }, this);
   },
   
-  /**
-    @private
+  /** @private
     Loops through add queue and, well, adds.
   */
   processAdds: function() {
@@ -502,8 +514,7 @@ SC.CollectionFastPath = {
     }
   },
   
-  /**
-  @private
+  /** @private
     Clear all DOM pools.
   */
   clearDOMPools: function() {
@@ -513,10 +524,13 @@ SC.CollectionFastPath = {
     }
   },
   
+  /**
+    @type Number
+    @default 10
+  */
   domPoolSize: 10,
   
-  /**
-  @private
+  /** @private
     Clears a specific DOM pool.
   */
   clearDOMPool: function(pool) {
@@ -537,8 +551,7 @@ SC.CollectionFastPath = {
     pool.length = Math.min(pool.length, this.domPoolSize);
   },
   
-  /**
-  @private
+  /** @private
     Returns the DOM pool for the given exampleView.
   */
   domPoolForExampleView: function(exampleView) {
@@ -548,8 +561,7 @@ SC.CollectionFastPath = {
     return pool;
   },
   
-  /**
-  @private
+  /** @private
     Tries to find an item for the given example view in a dom pool.
     If one could not be found, returns null.
   */
@@ -561,8 +573,7 @@ SC.CollectionFastPath = {
     return view;
   },
   
-  /**
-    @private
+  /** @private
     Sends a view to a DOM pool.
   */
   sendToDOMPool: function(view) {
@@ -574,8 +585,7 @@ SC.CollectionFastPath = {
     if (view.sleepInDOMPool) view.sleepInDOMPool();
   },
   
-  /**
-  @private
+  /** @private
     Adds an item view (grabbing the actual item from one of the pools if possible).
   */
   addItemView: function(exampleView, object, index) {
@@ -616,8 +626,7 @@ SC.CollectionFastPath = {
     return view;
   },
   
-  /**
-  @private
+  /** @private
     Removes an item view.
   */
   removeItemView: function(current) {
@@ -653,17 +662,19 @@ SC.CollectionFastPath = {
   },
   
   
-  /**
+  /** @private
     Tells ScrollView that this should receive live updates during touch scrolling.
     We are so fast, aren't we?
   */
   _lastTopUpdate: 0,
+
+  /** @private */
   _lastLeftUpdate: 0,
+
+  /** @private */
   _tolerance: 100,
   
-  /**
-    The fast-path that computes a special 
-  */
+  /** @private */
   touchScrollDidChange: function(left, top) {
     // prevent getting too many in close succession.
     if (Date.now() - this._lastTouchScrollTime < 25) return;

data/lib/frameworks/sproutcore/frameworks/desktop/mixins/collection_group.js

@@ -8,8 +8,6 @@
 /**
   @namespace
 
-  TODO: Add full description of SC.CollectionGroup
-  
   Any view you want to use as a group view in a collection must include this
   mixin.
   
@@ -17,6 +15,11 @@
 */
 SC.CollectionGroup = {
   
+  /**
+    @type Array
+    @default ['sc-collection-group']
+    @see SC.View#classNames
+  */
   classNames: ['sc-collection-group']
   
 };

data/lib/frameworks/sproutcore/frameworks/desktop/mixins/collection_row_delegate.js

@@ -6,53 +6,55 @@
 // ==========================================================================
 
 
-
 /** 
   @namespace
   
-  CollectionRowDelegates are consulted by SC.ListView and SC.TableView to 
-  control the height of rows, including specifying custom heights for 
-  specific rows.  
-  
-  You can implement a custom row height in one of two ways.  
+  CollectionRowDelegates are consulted by SC.ListView and SC.TableView to
+  control the height of rows, including specifying custom heights for
+  specific rows.
   
+  You can implement a custom row height in one of two ways.
 */
 SC.CollectionRowDelegate = {
 
-  /** walk like a duck */
+  /**
+    Walk like a duck.
+  
+    @type Boolean
+    @default YES
+  */
   isCollectionRowDelegate: YES,
   
   /**
-    Default item height. Size of an item without spacing or padding. 
-    Unless you implement some custom row height 
+    Size of an item without spacing or padding.
+    Unless you implement some custom row height
     support, this row height will be used for all items.
     
-    @property
     @type Number
+    @default 18
   */
   itemHeight: 18,
   
   /**
-    Default row spacing. This inserts empty space between rows that you can use for borders.
+    This inserts empty space between rows that you can use for borders.
     
-    @property
     @type Number
+    @default 0
   */
   rowSpacing: 0,
   
   /**
-    Default row padding. This is useful if you are using a custom item view that needs to be padded.
+    This is useful if you are using a custom item view that needs to be padded.
     This value is added to the top and bottom of the itemHeight.
     
-    @property
     @type Number
+    @default 0
   */
   rowPadding: 0,
   
   /**
     Total row height used for calculation. Equal to itemHeight + twice rowPadding.
     
-    @property
     @type Number
   */
   rowHeight: function(key, value) {
@@ -68,11 +70,10 @@ SC.CollectionRowDelegate = {
   }.property('itemHeight', 'rowPadding'),
 
   /**
-    Index set of rows that should have a custom row height.  If you need 
-    certains rows to have a custom row height, then set this property to a 
+    Index set of rows that should have a custom row height. If you need
+    certains rows to have a custom row height, then set this property to a
     non-null value.  Otherwise leave it blank to disable custom row heights.
     
-    @property
     @type SC.IndexSet
   */
   customRowHeightIndexes: null,
@@ -90,6 +91,7 @@ SC.CollectionRowDelegate = {
     @returns {Number} row height
   */
   contentIndexRowHeight: function(view, content, contentIndex) {
-    return this.get('rowHeight');    
+    return this.get('rowHeight');
   }
+
 };