Protocol: SC.SparseArrayDelegateProtocol

The SC.SparseArrayDelegateProtocol protocol defines the properties and methods that you may implement in your sparse array delegate objects.

An object that implements this protocol may act as a delegate that provides data for a sparse array. The delegate is invoked by the sparse array to fetch data or to update the array content as needed.

Your object does not need to implement all of these methods, but it should at least implement the sparseArrayDidRequestIndex() method. Note: Do not mix SC.SparseArrayDelegateProtocol into your classes. As a protocol, it exists only for reference sake. You only need define any of the properties or methods listed below in order to use this protocol.*

Defined in: sparse_array_delegate_protocol.js

Since:
SproutCore 1.0

Class Methods

Class Method Detail

sparseArrayDidRequestIndex(sparseArray, index)

Invoked when an object requests an index on the sparse array that has not yet been set. You should implement this method to set the object at the index using provideObjectAtIndex() or provideObjectsInRange() on the sparse array. You can call these methods immediately during this handler or you can wait and call them at a later time once you have loaded any data.

This method will only be called when an index is requested on the sparse array that has not yet been filled. If you have filled an index or range and you would like to reset it, call the objectsDidChangeInRange() method on the sparse array.

Note that if you implement the sparseArrayDidRequestRange() method, that method will be invoked instead of this one whenever possible to allow you to fill in the array with the most efficiency possible.

Parameters:
sparseArray SC.SparseArray
the sparse array
index Number
the requested index
Returns:
void
sparseArrayDidRequestIndexOf(sparseArray, object)

Optional delegate method you can use to determine the index of a particular object. If you do not implement this method, then the sparse array will just search the objects it has loaded already.

Parameters:
sparseArray SC.SparseArray
the sparse array
object Object
the object to find the index of
Returns:
Number
the index or -1
void
sparseArrayDidRequestLength(sparseArray)

Invoked when an object requests the length of the sparse array and the length has not yet been set. You can implement this method to update the length property of the sparse array immediately or at a later time by calling the provideLength() method on the sparse array.

This method will only be called once on your delegate unless you subsequently call provideLength(null) on the array, which will effectively "empty" the array and cause the array to invoke the delegate again the next time its length is request.

If you do not set a length on the sparse array immediately, it will return a length of 0 until you provide the length.

Parameters:
sparseArray SC.SparseArray
the array that needs a length.
Returns:
void
sparseArrayDidRequestRange(sparseArray, range)

Alternative method invoked when an object requests an index on the sparse array that has not yet been set. If you set the rangeWindowSize property on the Sparse Array, then all object index requests will be expanded to to nearest range window and then this method will be called with that range.

You should fill in the passed range by calling the provideObjectsInRange() method on the sparse array.

If you do not implement this method but set the rangeWindowSize anyway, then the sparseArrayDidRequestIndex() method will be invoked instead.

Note that the passed range is a temporary object. Be sure to clone it if you want to keep the range for later use.

Parameters:
sparseArray SC.SparseArray
the sparse array
range Range
read only range.
Returns:
void
sparseArrayDidReset(sparseArray)

Invoked whenever the sparse array is reset. Resetting a sparse array will cause it to flush its content and go back to the delegate for all property requests again.

Parameters:
sparseArray SC.SparseArray
the sparse array
Returns:
void
sparseArrayShouldReplace(sparseArray, idx, amt, objects)

Optional delegate method invoked whenever the sparse array attempts to changes its contents. If you do not implement this method or if you return NO from this method, then the edit will not be allowed.

Parameters:
sparseArray SC.SparseArray
the sparse array
idx Number
the starting index to replace
amt Number
the number if items to replace
objects Array
the array of objects to insert
Returns:
Boolean
YES to allow replace, NO to deny
Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:21 GMT-0600 (CST)