Mac Developer Library

Developer

AppKit Framework Reference NSCollectionViewDelegate Protocol Reference

Options
Deployment Target:

On This Page
Language:

NSCollectionViewDelegate

The NSCollectionViewDelegate protocol defines methods for managing the behavior of a collection view. You use the methods of this protocol to facilitate the user-initiated selection and highlighting of items, to track changes to the collection view’s visual elements, and to implement drag and drop support. The methods of this protocol are optional, but for some features, you must implement specific methods to support the feature.

Implement the methods of this protocol in an object that you use to manage your collection view. Typically, you implement delegate support in the view controller or window controller that manages the collection view itself, but you can implement these methods in another object if you prefer. Assign your delegate object to the collection view either programmatically (by setting the value of the collection view’s delegate property) or at design time in Interface Builder.

To implement drag and drop support in your collection view, implement the following methods:

For more information about handling drag and drop operations, see Drag and Drop Programming Topics.

Legacy Support

Before OS X 10.11, collection views supported only a single section of items organized in a grid layout. The drag and drop methods of this protocol include variants that take a single index or an NSIndexSet as a parameter. Although you can use those methods to implement your drag and drop support, it is recommended that you use the newer methods that take NSIndexPath objects instead.

  • Asks the delegate to approve the pending selection of items.

    Declaration

    Swift

    optional func collectionView(_ collectionView: NSCollectionView, shouldSelectItemsAtIndexPaths indexPaths: Set<NSIndexPath>) -> Set<NSIndexPath>

    Objective-C

    - (NSSet<NSIndexPath *> *)collectionView:(NSCollectionView *)collectionView shouldSelectItemsAtIndexPaths:(NSSet<NSIndexPath *> *)indexPaths

    Parameters

    collectionView

    The collection view making the request.

    indexPaths

    The set of NSIndexPath objects corresponding to the items selected by the user.

    Return Value

    The set of NSIndexPath objects corresponding to the items that you want to be selected. If you do not want any items selected, return an empty set.

    Discussion

    Use this method to approve or modify the items that the user tries to select. During interactive selection, the collection view calls this method whenever the user selects new items. Your implementation of the method can return the proposed set of index paths as-is or modify the set before returning it. You might modify the set to disallow the selection of specific items or specific combinations of items.

    This method is not called when you set the selection programmatically using the methods of the NSCollectionView class. If you do not implement this method, the collection view selects the items specified by the indexPaths parameter.

    Availability

    Available in OS X v10.11 and later.

  • Notifies the delegate object that one or more items were selected.

    Declaration

    Swift

    optional func collectionView(_ collectionView: NSCollectionView, didSelectItemsAtIndexPaths indexPaths: Set<NSIndexPath>)

    Objective-C

    - (void)collectionView:(NSCollectionView *)collectionView didSelectItemsAtIndexPaths:(NSSet<NSIndexPath *> *)indexPaths

    Parameters

    collectionView

    The collection view notifying you of the selection change.

    indexPaths

    The set of NSIndexPath objects corresponding to the items that are now selected.

    Discussion

    After the user successfully selects one or more items, the collection view calls this method to let you know that the selection has been made. Use this method to respond to the selection change and to make any necessary adjustments to your content or the collection view.

    This method is not called when you set the selection programmatically using the methods of the NSCollectionView class.

    Availability

    Available in OS X v10.11 and later.

  • Asks the delegate object to approve the pending deselection of items.

    Declaration

    Swift

    optional func collectionView(_ collectionView: NSCollectionView, shouldDeselectItemsAtIndexPaths indexPaths: Set<NSIndexPath>) -> Set<NSIndexPath>

    Objective-C

    - (NSSet<NSIndexPath *> *)collectionView:(NSCollectionView *)collectionView shouldDeselectItemsAtIndexPaths:(NSSet<NSIndexPath *> *)indexPaths

    Parameters

    collectionView

    The collection view making the request.

    indexPaths

    The set of NSIndexPath objects corresponding to the items deselected by the user.

    Return Value

    The set of NSIndexPath objects corresponding to the items that you want to be selected. If you do not want any items selected return an empty set.

    Discussion

    Use this method to approve or modify the items that the user tries to deselect. During interactive selection, the collection view calls this method whenever the user deselects items. Your implementation of the method can return the proposed set of index paths as-is or modify the set before returning it. You might modify the set to disallow the deselection of specific items.

    This method is not called when you set the selection programmatically using the methods of the NSCollectionView class. If you do not implement this method, the collection view deselects the items specified by the indexPaths parameter.

    Availability

    Available in OS X v10.11 and later.

  • Notifies the delegate object that one or more items were deselected.

    Declaration

    Swift

    optional func collectionView(_ collectionView: NSCollectionView, didDeselectItemsAtIndexPaths indexPaths: Set<NSIndexPath>)

    Objective-C

    - (void)collectionView:(NSCollectionView *)collectionView didDeselectItemsAtIndexPaths:(NSSet<NSIndexPath *> *)indexPaths

    Parameters

    collectionView

    The collection view notifying you of the selection change.

    indexPaths

    The set of NSIndexPath objects corresponding to the items that were deselected.

    Discussion

    After the user successfully deselects one or more items, the collection view calls this method to let you know that the items are no longer selected. Use this method to respond to the selection change and to make any necessary adjustments to your content or the collection view.

    This method is not called when you set the selection programmatically using the methods of the NSCollectionView class.

    Availability

    Available in OS X v10.11 and later.

  • Asks the delegate to approve the pending highlighting of the specified items.

    Declaration

    Swift

    optional func collectionView(_ collectionView: NSCollectionView, shouldChangeItemsAtIndexPaths indexPaths: Set<NSIndexPath>, toHighlightState highlightState: NSCollectionViewItemHighlightState) -> Set<NSIndexPath>

    Objective-C

    - (NSSet<NSIndexPath *> *)collectionView:(NSCollectionView *)collectionView shouldChangeItemsAtIndexPaths:(NSSet<NSIndexPath *> *)indexPaths toHighlightState:(NSCollectionViewItemHighlightState)highlightState

    Parameters

    collectionView

    The collection view making the request.

    indexPaths

    The set of NSIndexPath objects corresponding to the items being highlighted.

    highlightState

    The new highlight state for the items.

    Return Value

    The set of NSIndexPath objects corresponding to the items that you want to receive the specified highlight. If you do not want any items to receive the specified highlight state, return an empty set.

    Discussion

    Use this method to approve or modify the set of items targeted to receive the specified highlight state. During interactive selection or dragging, the collection view calls this method when actions occur that would affect the highlight state of items. Your implementation of the method can return the proposed set of index paths as-is or modify the set and disallow the highlighting of some or all of the items. Removing items from the set suppresses the corresponding actions, such as selecting the item or showing its eligibility as a drop target.

    If you do not implement this method, the collection view updates the highlight state for the items specified by the indexPaths parameter.

    Availability

    Available in OS X v10.11 and later.

  • Notifies the delegate that the highlight state of the specified items changed.

    Declaration

    Swift

    optional func collectionView(_ collectionView: NSCollectionView, didChangeItemsAtIndexPaths indexPaths: Set<NSIndexPath>, toHighlightState highlightState: NSCollectionViewItemHighlightState)

    Objective-C

    - (void)collectionView:(NSCollectionView *)collectionView didChangeItemsAtIndexPaths:(NSSet<NSIndexPath *> *)indexPaths toHighlightState:(NSCollectionViewItemHighlightState)highlightState

    Parameters

    collectionView

    The collection view notifying you of the highlight change.

    indexPaths

    The set of NSIndexPath objects corresponding to the items whose highlight state changed.

    highlightState

    The new highlight state of the items.

    Discussion

    After the highlight state of one or more items changes successfully, the collection view calls this method to report the change. Use this method to respond to the change and to make any necessary adjustments to your content or the collection view.

    Availability

    Available in OS X v10.11 and later.

  • Returns the transition layout object to use when performing an animated change between different layouts.

    Declaration

    Swift

    optional func collectionView(_ collectionView: NSCollectionView, transitionLayoutForOldLayout fromLayout: NSCollectionViewLayout, newLayout toLayout: NSCollectionViewLayout) -> NSCollectionViewTransitionLayout

    Objective-C

    - (NSCollectionViewTransitionLayout *)collectionView:(NSCollectionView *)collectionView transitionLayoutForOldLayout:(NSCollectionViewLayout *)fromLayout newLayout:(NSCollectionViewLayout *)toLayout

    Parameters

    collectionView

    The collection view whose layout object is changing.

    fromLayout

    The current layout object of the collection view. This is the starting point for the transition.

    toLayout

    The new layout for the collection view.

    Return Value

    The collection view transition layout object to use to perform the transition.

    Discussion

    When changing layouts for a collection view, you can use this method to customize the transition layout object used to make the change. A transition layout object lets you customize the behavior of collection view elements when transitioning from one layout to the next. Normally, transitioning between layouts causes the assorted items and views to animate from their current locations directly to their new locations. By returning a custom transition object, you could have those elements follow a nonlinear path, use a different timing algorithm, or move items in response to touch events.

    If you do not implement this method in your delegate object, the collection view uses a standard UICollectionViewTransitionLayout object for the transition.

    Special Considerations

    In OS X 10.11, this method is never called by the collection view.

    Availability

    Available in OS X v10.11 and later.

  • Returns a Boolean indicating whether a drag operation involving the specified items can begin.

    Declaration

    Swift

    optional func collectionView(_ collectionView: NSCollectionView, canDragItemsAtIndexPaths indexPaths: Set<NSIndexPath>, withEvent event: NSEvent) -> Bool

    Objective-C

    - (BOOL)collectionView:(NSCollectionView *)collectionView canDragItemsAtIndexPaths:(NSSet<NSIndexPath *> *)indexPaths withEvent:(NSEvent *)event

    Parameters

    collectionView

    The collection view making the request.

    indexPaths

    The index paths of the items about to be dragged.

    event

    The mouse-down event that began the drag operation.

    Return Value

    YEStrue if the drag operation can begin or NOfalse if it cannot.

    Discussion

    If you do not implement this method and your collection view has only one section, the collection view calls the legacy collectionView:canDragItemsAtIndexes:withEvent: method. If you do not implement either method, the collection view assumes a return value of YEStrue.

    Availability

    Available in OS X v10.11 and later.

  • Provides the pasteboard writer for the item at the specified index path.

    Declaration

    Swift

    optional func collectionView(_ collectionView: NSCollectionView, pasteboardWriterForItemAtIndexPath indexPath: NSIndexPath) -> NSPasteboardWriting?

    Objective-C

    - (id<NSPasteboardWriting>)collectionView:(NSCollectionView *)collectionView pasteboardWriterForItemAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    collectionView

    The collection view making the request.

    indexPath

    The index path of the item requiring a pasteboard writer.

    Return Value

    The pasteboard writer object to use for managing the item data. Return nil to prevent the collection view from dragging the item.

    Discussion

    You must implement this method or the collectionView:writeItemsAtIndexPaths:toPasteboard: method to support drag operations. The collection view calls this method in preference over the collectionView:writeItemsAtIndexPaths:toPasteboard: method if both are implemented. If your app supports multi-image drag and drop, you must implement this method.

    The collection view calls this method for each item involved in the drag operation after it has determined that a drag should begin but before the drag operation has started. Your implementation of this method should create and return the pasteboard writer—an object conforming to the NSPasteboardWriting protocol—to use for providing the item’s data. Using the object you provide, the collection view creates an NSDraggingItem object for you and configures its draggingFrame and imageComponents properties for you using information from the item at the specified index path.

    If you implement this method, the collection view does not call the collectionView:draggingImageForItemsAtIndexPaths:withEvent:offset: of your delegate or the draggingImageForItemsAtIndexPaths:withEvent:offset: method of NSCollectionView.

    Availability

    Available in OS X v10.11 and later.

  • Places the data for the drag operation on the pasteboard.

    Declaration

    Swift

    optional func collectionView(_ collectionView: NSCollectionView, writeItemsAtIndexPaths indexPaths: Set<NSIndexPath>, toPasteboard pasteboard: NSPasteboard) -> Bool

    Objective-C

    - (BOOL)collectionView:(NSCollectionView *)collectionView writeItemsAtIndexPaths:(NSSet<NSIndexPath *> *)indexPaths toPasteboard:(NSPasteboard *)pasteboard

    Parameters

    collectionView

    The collection view making the request.

    indexPaths

    The index paths of the items being dragged.

    pasteboard

    The pasteboard on which to place the drag data.

    Return Value

    YEStrue if the drag operation can continue or NOfalse if you want to refuse the drag.

    Discussion

    You must implement this method or the collectionView:pasteboardWriterForItemAtIndexPath: method to support drag operations. The collection view calls the collectionView:pasteboardWriterForItemAtIndexPath: method in preference to this one if both are implemented. If your app supports multi-image drag and drop, you must implement the collectionView:pasteboardWriterForItemAtIndexPath: method.

    The collection view calls this method after it has determined that a drag should begin but before the drag operation has started. Your implementation of this method should do the following:

    1. Declare the pasteboard types you support using the declareTypes:owner: method of the provided pasteboard object.

    2. Write data to the pasteboard for each type you declare.

    3. Return YEStrue from this method.

    Availability

    Available in OS X v10.11 and later.

  • Returns the names of the promised files that you created for a drag operation.

    Declaration

    Swift

    optional func collectionView(_ collectionView: NSCollectionView, namesOfPromisedFilesDroppedAtDestination dropURL: NSURL, forDraggedItemsAtIndexPaths indexPaths: Set<NSIndexPath>) -> [String]

    Objective-C

    - (NSArray<NSString *> *)collectionView:(NSCollectionView *)collectionView namesOfPromisedFilesDroppedAtDestination:(NSURL *)dropURL forDraggedItemsAtIndexPaths:(NSSet<NSIndexPath *> *)indexPaths

    Parameters

    collectionView

    The collection view asking you to provide the list of filenames.

    dropURL

    The URL at which to create the promised files.

    indexPaths

    The index paths of the dragged items.

    Return Value

    An array of strings containing the filenames you created, or intend to create, at the specified URL.

    Discussion

    At the start of a drag operation, your app must provide the data that constitutes the items being dragged. If you specify a file promise, instead of the data itself, use this method to specify the names of the files you promised. If the files already exist, move them to the directory specified by the dropURL parameter. If you must create the files first, use this method to specify the names of the files you intend to provide and begin creating those files asynchronously on a background thread.

    The filenames you return are made available from the namesOfPromisedFilesDroppedAtDestination: method of the NSDraggingInfo object passed around during the drag operation.

    For more information about how to use file promises when dragging content, see Drag and Drop Programming Topics.

    Availability

    Available in OS X v10.11 and later.

  • Creates and returns a drag image to represent the specified items during a drag.

    Declaration

    Swift

    optional func collectionView(_ collectionView: NSCollectionView, draggingImageForItemsAtIndexPaths indexPaths: Set<NSIndexPath>, withEvent event: NSEvent, offset dragImageOffset: NSPointPointer) -> NSImage

    Objective-C

    - (NSImage *)collectionView:(NSCollectionView *)collectionView draggingImageForItemsAtIndexPaths:(NSSet<NSIndexPath *> *)indexPaths withEvent:(NSEvent *)event offset:(NSPointPointer)dragImageOffset

    Parameters

    collectionView

    The collection view making the request.

    indexPaths

    The index paths of the items being dragged.

    event

    The mouse-down event that began the drag operation. You can use the mouse location when determining what value to return in the dragImageOffset parameter.

    dragImageOffset

    The offset value to use when positioning the image. On input, the point is NSZeroPoint, which centers the returned image under the mouse. Your method can return a different point that repositions the drag image by the specified offset values.

    Return Value

    The image to use for the dragged items.

    Discussion

    Your implementation of this method should create an appropriate image to use during the drag operation. The collection view places the center of your image at the current mouse location. Update the value in the dragImageOffset parameter to shift the position of your image by the specified amount.

    If you do not implement this method, the collection view uses the drag image returned by the draggingImageForItemsAtIndexPaths:withEvent:offset: method instead.

    Availability

    Available in OS X v10.11 and later.

  • Notifies your delegate that a drag session is about to begin.

    Declaration

    Swift

    optional func collectionView(_ collectionView: NSCollectionView, draggingSession session: NSDraggingSession, willBeginAtPoint screenPoint: NSPoint, forItemsAtIndexPaths indexPaths: Set<NSIndexPath>)

    Objective-C

    - (void)collectionView:(NSCollectionView *)collectionView draggingSession:(NSDraggingSession *)session willBeginAtPoint:(NSPoint)screenPoint forItemsAtIndexPaths:(NSSet<NSIndexPath *> *)indexPaths

    Parameters

    collectionView

    The collection view notifying your delegate object.

    session

    The dragging session that is about to begin.

    screenPoint

    The starting point (in screen coordinates) for the drag operation.

    indexPaths

    The index paths of the items being dragged.

    Discussion

    You can use this method to modify the dragging session or to perform other tasks related to the beginning of a drag session.

    Availability

    Available in OS X v10.11 and later.

  • Notifies your delegate that a drag session ended.

    Declaration

    Swift

    optional func collectionView(_ collectionView: NSCollectionView, draggingSession session: NSDraggingSession, endedAtPoint screenPoint: NSPoint, dragOperation operation: NSDragOperation)

    Objective-C

    - (void)collectionView:(NSCollectionView *)collectionView draggingSession:(NSDraggingSession *)session endedAtPoint:(NSPoint)screenPoint dragOperation:(NSDragOperation)operation

    Parameters

    collectionView

    The collection view notifying your delegate object.

    session

    The dragging session that ended.

    screenPoint

    The end point (in screen coordinates) for the drag operation.

    operation

    The operation that was performed. Use this value to determine how the operation ended. For example, for content that was dragged to the trash, the operation type would be NSDragOperationDelete.

    Discussion

    You can use this method to perform tasks related to the ending of a drag session.

    Availability

    Available in OS X v10.7 and later.

  • Asks your delegate to update the dragging items during a drag operation.

    Declaration

    Swift

    optional func collectionView(_ collectionView: NSCollectionView, updateDraggingItemsForDrag draggingInfo: NSDraggingInfo)

    Objective-C

    - (void)collectionView:(NSCollectionView *)collectionView updateDraggingItemsForDrag:(id<NSDraggingInfo>)draggingInfo

    Parameters

    collectionView

    The collection view asking you to update the dragging items.

    draggingInfo

    The current information for the drag operation. Use this object to iterate over the dragging items.

    Discussion

    You can use this method to update the current drag items while a drag is in progress. Updating the drag items is optional, but you might use this method to change the image for an item. For example, you might change the image when the mouse hovers over a particular part of the collection view. Use the enumerateDraggingItemsWithOptions:forView:classes:searchOptions:usingBlock: method of the draggingInfo parameter to iterate over the drag items and update them as appropriate.

    Availability

    Available in OS X v10.7 and later.

  • Validates whether a drop operation is possible at the specified location.

    Declaration

    Swift

    optional func collectionView(_ collectionView: NSCollectionView, validateDrop draggingInfo: NSDraggingInfo, proposedIndexPath proposedDropIndexPath: AutoreleasingUnsafeMutablePointer<NSIndexPath?>, dropOperation proposedDropOperation: UnsafeMutablePointer<NSCollectionViewDropOperation>) -> NSDragOperation

    Objective-C

    - (NSDragOperation)collectionView:(NSCollectionView *)collectionView validateDrop:(id<NSDraggingInfo>)draggingInfo proposedIndexPath:(NSIndexPath * _Nonnull *)proposedDropIndexPath dropOperation:(NSCollectionViewDropOperation *)proposedDropOperation

    Parameters

    collectionView

    The collection view asking you to validate the drop operation.

    draggingInfo

    The information about the drag operation.

    proposedDropIndexPath

    The index path at which the drop would occur. This parameter is passed by-reference and can be modified to change the proposed index path.

    proposedDropOperation

    The type of drop operation being proposed. This parameter is passed by-reference and can be modified to change the drop operation type.

    Return Value

    A value that indicates which dragging operation to perform. Return NSDragOperationNone to disallow a drop at the proposed location.

    Discussion

    Although implementation of this method is optional, you must implement it to support drops onto the associated collection view. You must also call the collection view’s registerForDraggedTypes: method to register the types of drops it supports. If you do not perform both of these actions, the collection view does not accept drops.

    When an interactive drag operation occurs, the collection view calls this method to determine whether the current mouse location is a valid place to drop the content. This method may be called many times during the course of the drag operation. Your implementation should look at the proposed location and return a constant that reflects how the drop would be handled.

    While validating the drop location, you can suggest a better drop location by updating the values in the proposedDropIndexPath and proposedDropOperation parameters. For example, you might suggest dropping the content before the specified item instead of on it. The collection view sets the proposedDropOperation parameter to NSCollectionViewDropOn when the mouse is closer to the middle of an item than to its edges; otherwise, it sets the parameter to NSCollectionViewDropBefore.

    Availability

    Available in OS X v10.11 and later.

  • Incorporates the dropped content into the collection view.

    Declaration

    Swift

    optional func collectionView(_ collectionView: NSCollectionView, acceptDrop draggingInfo: NSDraggingInfo, indexPath indexPath: NSIndexPath, dropOperation dropOperation: NSCollectionViewDropOperation) -> Bool

    Objective-C

    - (BOOL)collectionView:(NSCollectionView *)collectionView acceptDrop:(id<NSDraggingInfo>)draggingInfo indexPath:(NSIndexPath *)indexPath dropOperation:(NSCollectionViewDropOperation)dropOperation

    Parameters

    collectionView

    The collection view receiving the dropped content.

    draggingInfo

    The information about the drag operation.

    indexPath

    The index path at which the drop occurred. Use this location as the insertion point for the content.

    dropOperation

    The type of drop operation to perform.

    Return Value

    YEStrue if the drop operation should be accepted or NOfalse if it should be rejected.

    Discussion

    The collection view calls this method when the user releases the mouse button while it is over a valid drop target. This method is called after the collectionView:validateDrop:proposedIndexPath:dropOperation: method validates that dropping the content at the specified location is possible. You must implement this method to accept the dropped content and incorporate it into the collection view.

    In your implementation, use the information in the draggingInfo parameter to retrieve the data, update your data source object, and insert the appropriate items into the collection view. The dropped data is stored in the draggingPasteboard property of the dragging information object.

    If the animatesToDestination property of the dragging information is YEStrue, update the image and frame for each dragged item to its new location in the collection view. You can enumerate the list of dragged items using the enumerateDraggingItemsWithOptions:forView:classes:searchOptions:usingBlock: method of the dragging information object.

    Availability

    Available in OS X v10.11 and later.

These methods are called only on a collection view that has only one section. They are not called for collection views with two or more sections.