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

data/lib/frameworks/sproutcore/frameworks/desktop/views/list.js

@@ -18,13 +18,13 @@ sc_require('mixins/collection_row_delegate');
   also should provide a default rowHeight.  Setting this value will allow 
   the ListView to optimize its rendering.
   
-  h2. Variable Row Heights
+  ## Variable Row Heights
 
   Normally you set the row height through the rowHeight property.  You can 
   also support custom row heights by implementing the 
   contentCustomRowHeightIndexes property to return an index set.
   
-  h2. Using ListView with Very Large Data Sets
+  ## Using ListView with Very Large Data Sets
   
   ListView implements incremental rendering, which means it will only render
   HTML for the items that are current visible on the screen.  You can use it
@@ -54,44 +54,58 @@ sc_require('mixins/collection_row_delegate');
   @extends SC.CollectionRowDelegate
   @since SproutCore 1.0
 */
-SC.ListView = SC.CollectionView.extend(
-  SC.CollectionRowDelegate,
+SC.ListView = SC.CollectionView.extend(SC.CollectionRowDelegate,
 /** @scope SC.ListView.prototype */ {
-  
+
+  /**
+    @type Array
+    @default ['sc-list-view']
+    @see SC.View#classNames
+  */
   classNames: ['sc-list-view'],
 
+  /**
+    @type Boolean
+    @default YES
+  */
   acceptsFirstResponder: YES,
   
   /**
-  * If set to YES, the default theme will show alternating rows
-  * for the views this ListView created through exampleView property.
-  *
-  * @property {Boolean} 
+    If set to YES, the default theme will show alternating rows
+    for the views this ListView created through exampleView property.
+    
+    @type Boolean
+    @default NO
   */
   showAlternatingRows: NO,
   
+  
   // ..........................................................
   // METHODS
   //
   
+  /** @private */
   render: function(context, firstTime) {
     context.setClass('alternating', this.get('showAlternatingRows'));
     
     return sc_super();
   },
 
+
   // ..........................................................
   // COLLECTION ROW DELEGATE SUPPORT
   // 
   
-  
   /**
-    Returns the current collectionRowDelegate.  This property will recompute
-    everytime the content changes.
+    @field
+    @type Object
+    @observes 'delegate'
+    @observes 'content'
   */
   rowDelegate: function() {
-    var del     = this.delegate,
+    var del = this.delegate,
         content = this.get('content');
+
     return this.delegateFor('isCollectionRowDelegate', del, content);
   }.property('delegate', 'content').cacheable(),
   
@@ -187,6 +201,7 @@ SC.ListView = SC.CollectionView.extend(
     return this ;
   },
   
+  
   // ..........................................................
   // ROW PROPERTIES
   // 
@@ -289,7 +304,7 @@ SC.ListView = SC.CollectionView.extend(
     @returns {SC.ListView} receiver
   */  
   rowHeightDidChangeForIndexes: function(indexes) {
-    var len     = this.get('length');
+    var len = this.get('length');
 
     // clear any cached offsets
     this._sclv_heightCache = this._sclv_offsetCache = null;
@@ -318,19 +333,20 @@ SC.ListView = SC.CollectionView.extend(
   },
   
   /**
-  
     Computes the layout for a specific content index by combining the current
     row heights.
-  
+    
+    @param {Number} contentIndex
+    @returns {Hash} layout hash for the index provided
   */
   layoutForContentIndex: function(contentIndex) {
     var del = this.get('rowDelegate');
     
     return {
-      top:    this.rowOffsetForContentIndex(contentIndex),
+      top: this.rowOffsetForContentIndex(contentIndex),
       height: this.rowHeightForContentIndex(contentIndex) - del.get('rowPadding') * 2,
-      left:   0, 
-      right:  0
+      left: 0,
+      right: 0
     };
   },
   
@@ -412,31 +428,32 @@ SC.ListView = SC.CollectionView.extend(
     return SC.IndexSet.create(start, end-start);
   },
   
+  
   // ..........................................................
   // DRAG AND ROP SUPPORT
   // 
   
-  
   /**
     Default view class used to draw an insertion point.  The default 
     view will show a vertical line.  Any view you create
     should expect an outlineLevel property set, which should impact your left
     offset.
     
-    @property 
-    @type {SC.View}
+    @field
+    @type SC.View
   */
   insertionPointView: SC.View.extend({
     classNames: 'sc-list-insertion-point',
     
+    /** @private */
     render: function(context, firstTime) {
       if (firstTime) context.push('<div class="anchor"></div>');
     }
-    
   }),
 
   /**
     Default implementation will show an insertion point
+    @see SC.CollectionView#showInsertionPoint
   */
   showInsertionPoint: function(itemView, dropOperation) {
     var view = this._insertionPointView;
@@ -488,6 +505,9 @@ SC.ListView = SC.CollectionView.extend(
     }
   },
   
+  /**
+    @see SC.CollectionView#hideInsertionPoint
+  */
   hideInsertionPoint: function() {
     if (this._lastDropOnView) {
       this._lastDropOnView.set('isSelected', NO);
@@ -504,15 +524,15 @@ SC.ListView = SC.CollectionView.extend(
     a point, relative to the top/left corner of the receiver view.  The return
     value is an index plus a dropOperation, which is computed as such:
     
-    - if outlining is not used and you are within 5px of an edge, DROP_BEFORE
-      the item after the edge.
-      
-    - if outlining is used and you are within 5px of an edge and the previous
-      item has a different outline level then the next item, then DROP_AFTER
-      the previous item if you are closer to that outline level.
-      
-    - if dropOperation = SC.DROP_ON and you are over the middle of a row, then
-      use DROP_ON.
+      - if outlining is not used and you are within 5px of an edge, DROP_BEFORE
+        the item after the edge.
+      - if outlining is used and you are within 5px of an edge and the previous
+        item has a different outline level then the next item, then DROP_AFTER
+        the previous item if you are closer to that outline level.
+      - if dropOperation = SC.DROP_ON and you are over the middle of a row, then
+        use DROP_ON.
+    
+    @see SC.CollectionView.insertionIndexForLocation
   */
   insertionIndexForLocation: function(loc, dropOperation) {
     var locRect = {x:loc.x, y:loc.y, width:1, height:1},
@@ -546,8 +566,6 @@ SC.ListView = SC.CollectionView.extend(
       }
     }
     
-    
-    
     // ok, now if we are in last 10px, go to next item.
     if ((index<len) && (loc.y >= max-10)) index++;
     
@@ -613,6 +631,7 @@ SC.ListView = SC.CollectionView.extend(
     return [index, dropOperation];
   },
   
+  /** @private */
   mouseWheel: function(evt) {
     // The following commits changes in a list item that is being edited,
     // if the list is scrolled.
@@ -629,6 +648,7 @@ SC.ListView = SC.CollectionView.extend(
   // INTERNAL SUPPORT
   // 
 
+  /** @private */
   init: function() {
     sc_super();
     this._sclv_rowDelegateDidChange();

data/lib/frameworks/sproutcore/frameworks/desktop/views/list_item.js

@@ -6,8 +6,22 @@
 // ==========================================================================
 
 
+/**
+  @static
+  @constant
+*/
 SC.LIST_ITEM_ACTION_CANCEL = 'sc-list-item-cancel-action';
+
+/**
+  @static
+  @constant
+*/
 SC.LIST_ITEM_ACTION_REFRESH = 'sc-list-item-cancel-refresh';
+
+/**
+  @static
+  @constant
+*/
 SC.LIST_ITEM_ACTION_EJECT = 'sc-list-item-cancel-eject';
 
 /**
@@ -27,20 +41,24 @@ SC.LIST_ITEM_ACTION_EJECT = 'sc-list-item-cancel-eject';
   @extends SC.StaticLayout
   @since SproutCore 1.0
 */
-SC.ListItemView = SC.View.extend(
-    SC.InlineEditable,
-    SC.Control,
+SC.ListItemView = SC.View.extend(SC.InlineEditable, SC.Control,
 /** @scope SC.ListItemView.prototype */ {
 
+  /**
+    @type Array
+    @default ['sc-list-item-view']
+    @see SC.View#classNames
+  */
   classNames: ['sc-list-item-view'],
 
+  /**
+    @type Array
+    @default ['disclosureState', 'escapeHTML']
+    @see SC.View#displayProperties
+  */
   displayProperties: ['disclosureState', 'escapeHTML'],
 
 
-  init: function() {
-    sc_super();
-  },
-
   // ..........................................................
   // KEY PROPERTIES
   //
@@ -49,6 +67,7 @@ SC.ListItemView = SC.View.extend(
     The content object the list item will display.
 
     @type SC.Object
+    @default null
   */
   content: null,
 
@@ -60,7 +79,8 @@ SC.ListItemView = SC.View.extend(
     in a ListView, this property would be 0.
 
     @type Number
-    @isReadOnly
+    @default null
+    @readOnly
   */
   contentIndex: null,
 
@@ -69,6 +89,9 @@ SC.ListItemView = SC.View.extend(
 
     If false, the icon on the list item view will be hidden.  Otherwise,
     space will be left for the icon next to the list item view.
+    
+    @type Boolean
+    @default NO
   */
   hasContentIcon: NO,
 
@@ -77,6 +100,9 @@ SC.ListItemView = SC.View.extend(
 
     If false, the icon on the list item view will be hidden.  Otherwise,
     space will be left for the icon next to the list item view.
+    
+    @type Boolean
+    @default NO
   */
   hasContentRightIcon: NO,
 
@@ -85,6 +111,9 @@ SC.ListItemView = SC.View.extend(
     arrow.
 
     If false, the space for the branch arrow will be collapsed.
+    
+    @type Boolean
+    @default NO
   */
   hasContentBranch: NO,
 
@@ -93,13 +122,17 @@ SC.ListItemView = SC.View.extend(
 
     The checkbox will only be visible if this key is not null.
 
-    @type {String}
+    @type String
+    @default null
   */
   contentCheckboxKey: null,
 
   /**
     The URL or CSS class name to use for the icon. This is only used if
     contentIconKey is null, or returns null from the delegate.
+    
+    @type String
+    @default null
   */
   icon: null,
 
@@ -108,12 +141,18 @@ SC.ListItemView = SC.View.extend(
 
     This property will be checked on the content object to determine the
     icon to display.  It must return either a URL or a CSS class name.
+    
+    @type String
+    @default NO
   */
   contentIconKey: null,
 
   /**
     The URL or CSS class name to use for the right icon. This is only used if
     contentRightIconKey is null, or returns null from the delegate.
+    
+    @type String
+    @default null
   */
   rightIcon: null,
 
@@ -122,6 +161,9 @@ SC.ListItemView = SC.View.extend(
 
     This property will be checked on the content object to determine the
     icon to display.  It must return either a URL or a CSS class name.
+    
+    @type String
+    @default null
   */
   contentRightIconKey: null,
 
@@ -129,6 +171,9 @@ SC.ListItemView = SC.View.extend(
     (displayDelegate) The name of the property used for label itself
 
     If null, then the content object itself will be used..
+    
+    @type String
+    @default null
   */
   contentValueKey: null,
 
@@ -137,6 +182,9 @@ SC.ListItemView = SC.View.extend(
     You should only disable this option if you are sure you will only
     display content that is already escaped and you need the added
     performance gain.
+    
+    @type Boolean
+    @default YES
   */
   escapeHTML: YES,
 
@@ -146,6 +194,9 @@ SC.ListItemView = SC.View.extend(
 
     The count will only be visible if this property is not null and the
     returned value is not 0.
+    
+    @type String
+    @default null
   */
   contentUnreadCountKey: null,
 
@@ -156,6 +207,9 @@ SC.ListItemView = SC.View.extend(
 
     If this is null, then the branch view will be completely hidden.
     Otherwise space will be allocated for it.
+    
+    @type String
+    @default null
   */
   contentIsBranchKey: null,
   
@@ -163,17 +217,30 @@ SC.ListItemView = SC.View.extend(
     Indent to use when rendering a list item with an outline level > 0.  The
     left edge of the list item will be indented by this amount for each
     outline level.
+    
+    @type Number
+    @default 16
   */
   outlineIndent: 16,
 
   /**
     Outline level for this list item.  Usually set by the collection view.
+    
+    @type Number
+    @default 0
   */
   outlineLevel: 0,
 
   /**
     Disclosure state for this list item.  Usually set by the collection view
-    when the list item is created.
+    when the list item is created. Possible values:
+    
+      - SC.LEAF_NODE
+      - SC.BRANCH_OPEN
+      - SC.BRANCH_CLOSED
+    
+    @type String
+    @default SC.LEAF_NODE
   */
   disclosureState: SC.LEAF_NODE,
 
@@ -183,6 +250,7 @@ SC.ListItemView = SC.View.extend(
   */
   validator: null,
 
+  /** @private */
   contentPropertyDidChange: function() {
     //if (this.get('isEditing')) this.discardEditing() ;
     if (this.get('contentIsEditable') !== this.contentIsEditable()) {
@@ -193,14 +261,22 @@ SC.ListItemView = SC.View.extend(
   },
 
   /**
-    Determines if content is editable or not.  Checkboxes and other related
+    Determines if content is editable or not. Checkboxes and other related
     components will render disabled if an item is not editable.
+    
+    @field
+    @type Boolean
+    @observes content
   */
   contentIsEditable: function() {
     var content = this.get('content');
     return content && (content.get ? content.get('isEditable')!==NO : NO);
   }.property('content').cacheable(),
   
+  /**
+    @type Object
+    @default SC.InlineTextFieldDelegate
+  */
   inlineEditorDelegate: SC.InlineTextFieldDelegate,
   
   /**
@@ -209,25 +285,13 @@ SC.ListItemView = SC.View.extend(
     selecting any label elements.   If you override renderLabel() you
     probably need to override this as well.
 
-    @returns {SC.CoreQuery} CQ object selecting label elements
+    @returns {jQuery} jQuery object selecting label elements
   */
   $label: function() {
-    return this.$('label') ;
+    return this.$('label');
   },
 
-  /**
-    Generates the html string used to represent the action item for your
-    list item.  override this to return your own custom HTML
-
-    @param {SC.RenderContext} context the render context
-    @param {String} actionClassName the name of the action item
-    @returns {void}
-  */
-  renderAction: function(context, actionClassName){
-    context.push('<img src="',SC.BLANK_IMAGE_URL,'" class="action" />');
-  },
-
-  /**
+  /** @private
     Determines if the event occured inside an element with the specified
     classname or not.
   */
@@ -275,11 +339,10 @@ SC.ListItemView = SC.View.extend(
   },
 
   /** @private
-  mouseDown is handled only for clicks on the checkbox view or or action
-  button.
+    mouseDown is handled only for clicks on the checkbox view or or action
+    button.
   */
   mouseDown: function(evt) {
-
     // if content is not editable, then always let collection view handle the
     // event.
     if (!this.get('contentIsEditable')) return NO ;
@@ -306,6 +369,7 @@ SC.ListItemView = SC.View.extend(
     return NO ; // let the collection view handle this event
   },
 
+  /** @private */
   mouseUp: function(evt) {
     var ret= NO, del, checkboxKey, content, state, idx, set;
 
@@ -366,6 +430,7 @@ SC.ListItemView = SC.View.extend(
     return ret ;
   },
 
+  /** @private */
   mouseMoved: function(evt) {
     if (this._isMouseDownOnCheckbox && this._isInsideCheckbox(evt)) {
       this._addCheckboxActiveState() ;
@@ -389,23 +454,28 @@ SC.ListItemView = SC.View.extend(
    return NO ;
   },
 
+  /** @private */
   touchStart: function(evt){
     return this.mouseDown(evt);
   },
 
+  /** @private */
   touchEnd: function(evt){
     return this.mouseUp(evt);
   },
 
+  /** @private */
   touchEntered: function(evt){
     return this.mouseEntered(evt);
   },
 
+  /** @private */
   touchExited: function(evt){
     return this.mouseExited(evt);
   },
 
 
+  /** @private */
   _addCheckboxActiveState: function() {
     if (this.get('isEnabled')) {
       if (this._checkboxRenderDelegate) {
@@ -421,6 +491,7 @@ SC.ListItemView = SC.View.extend(
     }
   },
 
+  /** @private */
   _removeCheckboxActiveState: function() {
     if (this._checkboxRenderer) {
       var source = this._checkboxRenderSource;
@@ -434,6 +505,7 @@ SC.ListItemView = SC.View.extend(
     }
   },
 
+  /** @private */
   _addDisclosureActiveState: function() {
     if (this.get('isEnabled')) {
       if (this._disclosureRenderDelegate) {
@@ -449,6 +521,7 @@ SC.ListItemView = SC.View.extend(
     }
   },
 
+  /** @private */
   _removeDisclosureActiveState: function() {
     if (this._disclosureRenderer) {
       var source = this._disclosureRenderSource;
@@ -461,15 +534,17 @@ SC.ListItemView = SC.View.extend(
     }
   },
 
+  /** @private */
   _addRightIconActiveState: function() {
    this.$('img.right-icon').setClass('active', YES);
   },
 
+  /** @private */
   _removeRightIconActiveState: function() {
    this.$('img.right-icon').removeClass('active');
   },
 
-  /**
+  /** @private
     Returns true if a click is on the label text itself to enable editing.
 
     Note that if you override renderLabel(), you probably need to override
@@ -499,14 +574,12 @@ SC.ListItemView = SC.View.extend(
   },
 
   /*
-  * @method
-  *
-  * Edits the label portion of the list item. If scrollIfNeeded is YES, will
-  * scroll to the item before editing it.
-  *
-  * @params {Boolean} if the parent scroll view should be scrolled to this item
-  * before editing begins
-  * @returns {Boolean} YES if successful
+    Edits the label portion of the list item. If scrollIfNeeded is YES, will
+    scroll to the item before editing it.
+    
+    @params {Boolean} if the parent scroll view should be scrolled to this item
+      before editing begins
+    @returns {Boolean} YES if successful
   */
   beginEditing: function(original, scrollIfNeeded) {
     var el        = this.$label(),
@@ -531,9 +604,7 @@ SC.ListItemView = SC.View.extend(
   }.enhance(),
 
   /*
-  * @method
-  *
-  * Configures the editor to overlay the label properly.
+    Configures the editor to overlay the label properly.
   */
   inlineEditorWillBeginEditing: function(editor, editable, value) {
     var content   = this.get('content'),
@@ -593,7 +664,7 @@ SC.ListItemView = SC.View.extend(
     Allow editing.
   */
   inlineEditorShouldBeginEditing: function(inlineEditor) {
-    return YES ;
+    return YES;
   },
 
   /** @private