1 // ==========================================================================
  2 // Project:   SproutCore - JavaScript Application Framework
  3 // Copyright: ©2006-2011 Strobe Inc. and contributors.
  4 //            Portions ©2008-2011 Apple Inc. All rights reserved.
  5 // License:   Licensed under MIT license (see license.js)
  6 // ==========================================================================
  7 
  8 
  9 /**
 10   @namespace
 11 
 12   `CollectionRowDelegate`s are consulted by collection views, such as `SC.ListView`
 13   that lay out items in vertical or horizontal rows, in order to determine the
 14   height or width of each row.
 15 */
 16 SC.CollectionRowDelegate = {
 17 
 18   /**
 19     Walk like a duck.
 20 
 21     @type Boolean
 22     @default true
 23   */
 24   isCollectionRowDelegate: true,
 25 
 26   /** @deprecated Version 1.11. Please use the `rowSize` property instead.
 27     Size of an item without spacing or padding.
 28     Unless you implement custom row height or widths upport, this row height will be used for all items.
 29 
 30     @type Number
 31     @default 24
 32   */
 33   itemHeight: null,
 34 
 35   /**
 36     The height or width of a row before padding depending on whether the
 37     collection is laid out vertically or horizontally.
 38 
 39     Unless you implement custom row size support, this value will be used for
 40     all rows.
 41 
 42     @type Number
 43     @default 24
 44   */
 45   // This is a computed property in order to provide backwards compatibility for itemHeight.
 46   // When itemHeight is removed completely, this can become a simple `24` value.
 47   rowSize: function (key, value) {
 48     var itemHeight = this.get('itemHeight'),
 49       ret = 24;
 50 
 51     // Backwards compatibility support
 52     if (!SC.none(itemHeight)) {
 53       //@if(debug)
 54       SC.warn('Developer Warning: The itemHeight property of SC.CollectionRowDelegate has been renamed to rowSize.');
 55       //@endif
 56 
 57       return itemHeight;
 58     }
 59 
 60     if (!SC.none(value)) { ret = value; }
 61 
 62     return ret;
 63   }.property('itemHeight').cacheable(),
 64 
 65   /**
 66     The amount of space to leave between each row.
 67 
 68     This is useful when you need to leave space for borders.
 69 
 70     @type Number
 71     @default 0
 72   */
 73   rowSpacing: 0,
 74 
 75   /**
 76     Padding space added to the top and bottom of each row when laid out vertically,
 77     or to the left and right when laid out horizontally.
 78 
 79     This is useful if you are using a custom item view that needs to be padded.
 80 
 81     @type Number
 82     @default 0
 83   */
 84   rowPadding: 0,
 85 
 86   /** @deprecated Version 1.11. Please use a combination of rowSize and rowPadding to specify the total height or width of each row.
 87     Total row size used for calculation. Equal to `rowSize + (2 * rowPadding)`.
 88 
 89     @type Number
 90   */
 91   rowHeight: function (key, value) {
 92     var rowPadding = this.get('rowPadding'),
 93       rowSize = this.get('rowSize');
 94 
 95     if (value !== undefined) {
 96       this.set('rowSize', value - rowPadding * 2);
 97       return value;
 98     }
 99 
100     return rowSize + rowPadding * 2;
101   }.property('rowSize', 'rowPadding'),
102 
103   /** @private - Returns the total row size based on rowSize and rowPadding for convenience. */
104   _sc_totalRowSize: function () {
105     // Backwards compatibility in case the rowHeight property is set directly.
106     return this.get('rowHeight');
107   }.property('rowHeight'),
108 
109   /** @deprecated Version 1.11. Please use the `customRowSizeIndexes` property instead.
110     Index set of rows that should have a custom row height. If you need
111     certain rows to have a custom row height, then set this property to a
112     non-null value.  Otherwise leave it blank to disable custom row heights.
113 
114     @type SC.IndexSet
115   */
116   customRowHeightIndexes: null,
117 
118   /**
119     Index set of rows that should have a custom row height. If you need
120     certain rows to have a custom row height, then set this property to a
121     non-null value.  Otherwise leave it blank to disable custom row heights.
122 
123     @type SC.IndexSet
124   */
125   // This is a computed property in order to provide backwards compatibility for customRowHeightIndexes.
126   // When customRowHeightIndexes is removed completely, this can become a simple `null` value.
127   customRowSizeIndexes: function (key, value) {
128     var customRowHeightIndexes = this.get('customRowHeightIndexes'),
129       ret = null;
130 
131     // Backwards compatibility support.
132     if (!SC.none(customRowHeightIndexes)) {
133       //@if(debug)
134       SC.warn('Developer Warning: The customRowHeightIndexes property of SC.CollectionRowDelegate has been renamed to customRowSizeIndexes.');
135       //@endif
136 
137       return customRowHeightIndexes;
138     }
139 
140     if (!SC.none(value)) { ret = value; }
141 
142     return ret;
143   }.property('customRowHeightIndexes').cacheable(),
144 
145   /** @deprecated Version 1.11. Please use the `contentIndexRowSize()` function instead.
146     Called for each index in the `customRowSizeIndexes` set to get the
147     actual row height for the index.  This method should return the default
148     rowSize if you don't want the row to have a custom height.
149 
150     The default implementation just returns the default rowSize.
151 
152     @param {SC.CollectionView} view the calling view
153     @param {Object} content the content array
154     @param {Number} contentIndex the index
155     @returns {Number} row height
156   */
157   contentIndexRowHeight: function (view, content, contentIndex) {
158     return this.get('_sc_totalRowSize');
159   },
160 
161   /**
162     Called for each index in the `customRowSizeIndexes` set to get the
163     actual row size for the index.  This method should return the default
164     rowSize if you don't want the row to have a custom size.
165 
166     The default implementation just returns the default rowSize plus rowPadding.
167 
168     @param {SC.CollectionView} view the calling view
169     @param {Object} content the content array
170     @param {Number} contentIndex the index
171     @returns {Number} row size
172   */
173   contentIndexRowSize: function (view, content, contentIndex) {
174     // Backwards compatibility in case the contentIndexRowHeight function is overridden.
175     return this.contentIndexRowHeight(view, content, contentIndex);
176   }
177 
178 };
179