Mixin: SC.CollectionViewDelegate

A Collection View Delegate is consulted by a SC.CollectionView to make policy decisions about certain behaviors such as selection control and drag and drop. If you need to control other aspects of your data, you may also want to add the SC.CollectionContent mixin.

To act as a Collection Delegate, just apply this mixin to your class. You must then set the "delegate" property on the CollectionView to your object.

Alternatively, if no delegate is set on a CollectionView, but the content implements this mixin, the content object will be used as the delegate instead.

If you set an ArrayController or its arrangedObjects property as the content of a CollectionView, the ArrayController will automatically act as the delegate for the view.

Defined in: collection_view_delegate.js

Since:
SproutCore 1.0

Field Summary

Class Methods

Field Detail

SC.CollectionViewDelegate.ghostActsLikeCursor Boolean

Allows the ghost view created in collectionViewDragViewFor to be displayed like a cursor instead of the default implementation. This sets the view origin to be the location of the mouse cursor.

Default value:
NO
SC.CollectionViewDelegate.isCollectionViewDelegate Boolean
Walk like a duck. Used to detect the mixin by SC.CollectionView.
Default value:
YES

Class Method Detail

collectionViewComputeDragOperations(view, drag, proposedDragOperations)

Called once during a drag the first time view is entered. Return all possible drag operations OR'd together.

Parameters:
view SC.CollectionView
the collection view that initiated the drag
drag SC.Drag
the drag object
proposedDragOperations Number
proposed logical OR of allowed drag operations.
Returns:
Number
the allowed drag operations. Defaults to op
collectionViewDeleteContent(view, indexes, indexes)

Called by the collection view to actually delete the selected items.

The default behavior will use standard array operators to delete the indexes from the array. You can implement this method to provide your own deletion method.

If you simply want to control the items to be deleted, you should instead implement collectionViewShouldDeleteItems(). This method will only be called if canDeleteContent is YES and collectionViewShouldDeleteIndexes() returns a non-empty index set

Parameters:
view SC.CollectionView
collection view
indexes SC.IndexSet
the items to delete
indexes
Returns:
Boolean
YES if the deletion was a success.
collectionViewDragDataForType(view, dataType, drag)

Called by a collection view when a drag concludes to give you the option to provide the drag data for the drop.

This method should be implemented essentially as you would implement the dragDataForType() if you were a drag data source. You will never be asked to provide drag data for a reorder event, only for other types of data.

The default implementation returns null.

Parameters:
view
{SC.CollectionView} the collection view that initiated the drag
dataType
{String} the data type to provide
drag
{SC.Drag} the drag object
Returns:
Object
the data object or null if the data could not be provided.
collectionViewDragDataTypes(view)

Called by the collection view just before it starts a drag so that you can provide the data types you would like to support in the data.

You can implement this method to return an array of the data types you will provide for the drag data.

If you return null or an empty array, can you have set canReorderContent to YES on the CollectionView, then the drag will go ahead but only reordering will be allowed. If canReorderContent is NO, then the drag will not be allowed to start.

If you simply want to control whether a drag is allowed or not, you should instead implement collectionViewShouldBeginDrag().

The default returns an empty array.

Parameters:
view SC.CollectionView
the collection view to begin dragging.
Returns:
Array
array of supported data types.
collectionViewDragViewFor(view, dragContent)

Renders a drag view for the passed content indexes. If you return null from this, then a default drag view will be generated for you.

The default implementation returns null.

Parameters:
view SC.CollectionView
dragContent SC.IndexSet
Returns:
SC.View
view or null
collectionViewPerformDragOperation(view, drag, op, proposedInsertionIndex, proposedDropOperation)

Called by the collection view to actually accept a drop. This method will only be invoked AFTER your `validateDrop method has been called to determine if you want to even allow the drag operation to go through.

You should actually make changes to the data model if needed here and then return the actual drag operation that was performed. If you return SC.DRAG_NONE and the dragOperation was SC.DRAG_REORDER, then the default reorder behavior will be provided by the collection view.

Parameters:
view SC.CollectionView
drag SC.Drag
the current drag object
op Number
proposed logical OR of allowed drag operations.
proposedInsertionIndex Number
an index into the content array representing the proposed insertion point.
proposedDropOperation String
the proposed drop operation. Will be one of SC.DROP_ON, SC.DROP_BEFORE, or SC.DROP_ANY.
Returns:
the allowed drag operation. Defaults to proposedDragOperation
collectionViewSelectionForProposedSelection(view, sel)

This method will be called anytime the collection view is about to change the selection in response to user mouse clicks or keyboard events.

You can use this method to adjust the proposed selection, eliminating any selected objects that cannot be selected. The default implementation of this method simply returns the proposed selection.

Parameters:
view SC.CollectionView
the collection view
sel SC.IndexSet
Proposed array of selected objects.
Returns:
SC.IndexSet
Actual allow selection index set
collectionViewShouldBeginDrag(view)

Called by the collection view just before it starts a drag to give you an opportunity to decide if the drag should be allowed.

You can use this method to implement fine-grained control over when a drag will be allowed and when it will not be allowed. For example, you may enable content reordering but then implement this method to prevent reordering of certain items in the view.

The default implementation always returns YES.

Parameters:
view SC.CollectionView
the collection view
Returns:
Boolean
YES to allow, NO to prevent it
collectionViewShouldDeleteIndexes(view, indexes)

Called by the collection view whenever the deleteSelection() method is called. You can implement this method to get fine-grained control over which items can be deleted. To prevent deletion, return null.

This method is only called if canDeleteContent is YES on the collection view.

Parameters:
view SC.CollectionView
the collection view
indexes SC.IndexSet
proposed index set of items to delete.
Returns:
SC.IndexSet
index set allowed to delete or null.
collectionViewShouldDeselectIndexes(view, indexes)

Called by the collection when attempting to deselect an item. Return the actual indexes you want to allow to be deselected. Return null to disallow the change. The default allows all selection.

Note that you should not modify the passed in IndexSet. clone it instead.

Parameters:
view SC.CollectionView
the view collection view
indexes SC.IndexSet
the indexes to be selected
Returns:
SC.IndexSet
allowed index set
collectionViewShouldSelectIndexes(view, indexes, extend)

Called by the collection when attempting to select an item. Return the actual indexes you want to allow to be selected. Return null to disallow the change. The default allows all selection.

Parameters:
view SC.CollectionView
the view collection view
indexes SC.IndexSet
the indexes to be selected
extend Boolean
YES if the indexes will extend existing sel
Returns:
SC.IndexSet
allowed index set
collectionViewValidateDragOperation(view, drag, op, proposedInsertionIndex, proposedDropOperation)

Called by the collection view during a drag to let you determine the kind and location of a drop you might want to accept.

You can override this method to implement fine-grained control over how and when a dragged item is allowed to be dropped into a collection view.

This method will be called by the collection view both to determine in general which operations you might support and specifically the operations you would support if the user dropped an item over a specific location.

If the proposedDropOperation parameter is SC.DROP_ON or SC.DROP_BEFORE, then the proposedInsertionPoint will be a non-negative value and you should determine the specific operations you will support if the user dropped the drag item at that point.

If you do not like the proposed drop operation or insertion point, you can override these properties as well by setting the proposedDropOperation and proposedInsertionIndex properties on the collection view during this method. These properties are ignored all other times.

Parameters:
view SC.CollectionView
the collection view
drag SC.Drag
the current drag object
op Number
proposed logical OR of allowed drag operations.
proposedInsertionIndex Number
an index into the content array representing the proposed insertion point.
proposedDropOperation String
the proposed drop operation. Will be one of SC.DROP_ON, SC.DROP_BEFORE, or SC.DROP_ANY.
Returns:
the allowed drag operation. Defaults to op
Documentation generated by JsDoc Toolkit 2.4.0 on Wed Apr 08 2015 10:02:20 GMT-0600 (CST)