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