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