1 // ========================================================================== 2 // Project: SproutCore Costello - Property Observing Library 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 /** @namespace 9 The `SC.SparseArrayDelegateProtocol` protocol defines the properties and methods that you may 10 implement in your sparse array delegate objects. 11 12 An object that implements this protocol may act as a delegate that provides data for a sparse 13 array. The delegate is invoked by the sparse array to fetch data or to update the array content 14 as needed. 15 16 Your object does not need to implement all of these methods, but it should at least implement the `sparseArrayDidRequestIndex()` method. 17 18 *Note: Do not mix `SC.SparseArrayDelegateProtocol` into your classes. As a protocol, it exists 19 only for reference sake. You only need define any of the properties or methods listed below in 20 order to use this protocol.* 21 22 @since SproutCore 1.0 23 */ 24 SC.SparseArrayDelegateProtocol = { 25 26 /** 27 Invoked when an object requests the length of the sparse array and the 28 length has not yet been set. You can implement this method to update 29 the length property of the sparse array immediately or at a later time 30 by calling the provideLength() method on the sparse array. 31 32 This method will only be called once on your delegate unless you 33 subsequently call provideLength(null) on the array, which will effectively 34 "empty" the array and cause the array to invoke the delegate again the 35 next time its length is request. 36 37 If you do not set a length on the sparse array immediately, it will return 38 a length of 0 until you provide the length. 39 40 @param {SC.SparseArray} sparseArray the array that needs a length. 41 @returns {void} 42 */ 43 sparseArrayDidRequestLength: function(sparseArray) { 44 // Default does nothing. 45 }, 46 47 /** 48 Invoked when an object requests an index on the sparse array that has not 49 yet been set. You should implement this method to set the object at the 50 index using provideObjectAtIndex() or provideObjectsInRange() on the 51 sparse array. You can call these methods immediately during this handler 52 or you can wait and call them at a later time once you have loaded any 53 data. 54 55 This method will only be called when an index is requested on the sparse 56 array that has not yet been filled. If you have filled an index or range 57 and you would like to reset it, call the objectsDidChangeInRange() method 58 on the sparse array. 59 60 Note that if you implement the sparseArrayDidRequestRange() method, that 61 method will be invoked instead of this one whenever possible to allow you 62 to fill in the array with the most efficiency possible. 63 64 @param {SC.SparseArray} sparseArray the sparse array 65 @param {Number} index the requested index 66 @returns {void} 67 */ 68 sparseArrayDidRequestIndex: function(sparseArray, index) { 69 70 }, 71 72 /** 73 Alternative method invoked when an object requests an index on the 74 sparse array that has not yet been set. If you set the 75 rangeWindowSize property on the Sparse Array, then all object index 76 requests will be expanded to to nearest range window and then this 77 method will be called with that range. 78 79 You should fill in the passed range by calling the provideObjectsInRange() 80 method on the sparse array. 81 82 If you do not implement this method but set the rangeWindowSize anyway, 83 then the sparseArrayDidRequestIndex() method will be invoked instead. 84 85 Note that the passed range is a temporary object. Be sure to clone it if 86 you want to keep the range for later use. 87 88 @param {SC.SparseArray} sparseArray the sparse array 89 @param {Range} range read only range. 90 @returns {void} 91 */ 92 sparseArrayDidRequestRange: function(sparseArray, range) { 93 94 }, 95 96 /** 97 Optional delegate method you can use to determine the index of a 98 particular object. If you do not implement this method, then the 99 sparse array will just search the objects it has loaded already. 100 101 @param {SC.SparseArray} sparseArray the sparse array 102 @param {Object} object the object to find the index of 103 @return {Number} the index or -1 104 @returns {void} 105 */ 106 sparseArrayDidRequestIndexOf: function(sparseArray, object) { 107 108 }, 109 110 /** 111 Optional delegate method invoked whenever the sparse array attempts to 112 changes its contents. If you do not implement this method or if you 113 return NO from this method, then the edit will not be allowed. 114 115 @param {SC.SparseArray} sparseArray the sparse array 116 @param {Number} idx the starting index to replace 117 @param {Number} amt the number if items to replace 118 @param {Array} objects the array of objects to insert 119 @returns {Boolean} YES to allow replace, NO to deny 120 */ 121 sparseArrayShouldReplace: function(sparseArray, idx, amt, objects) { 122 return NO ; 123 }, 124 125 /** 126 Invoked whenever the sparse array is reset. Resetting a sparse array 127 will cause it to flush its content and go back to the delegate for all 128 property requests again. 129 130 @param {SC.SparseArray} sparseArray the sparse array 131 @returns {void} 132 */ 133 sparseArrayDidReset: function(sparseArray) { 134 } 135 }; 136