iOS Developer Library

Developer

UIKit Framework Reference UICollectionViewDelegate Protocol Reference

Options
Deployment Target:

On This Page
Language:

UICollectionViewDelegate

The UICollectionViewDelegate protocol defines methods that allow you to manage the selection and highlighting of items in a collection view and to perform actions on those items. The methods of this protocol are all optional.

Many methods of this protocol take NSIndexPath objects as parameters. To support collection views, UIKit declares a category on NSIndexPath that enables you to get the represented item index and section index, and to construct new index path objects from item and index values. Because items are located within their sections, you usually must evaluate the section index number before you can identify the item by its index number.

When configuring the collection view object, assign your delegate object to its delegate property. For more information, see UICollectionView Class Reference.

  • Asks the delegate if the specified item should be selected.

    Declaration

    Swift

    optional func collectionView(_ collectionView: UICollectionView, shouldSelectItemAtIndexPath indexPath: NSIndexPath) -> Bool

    Objective-C

    - (BOOL)collectionView:(UICollectionView *)collectionView shouldSelectItemAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    collectionView

    The collection view object that is asking whether the selection should change.

    indexPath

    The index path of the cell to be selected.

    Return Value

    YEStrue if the item should be selected or NOfalse if it should not.

    Discussion

    The collection view calls this method when the user tries to select an item in the collection view. It does not call this method when you programmatically set the selection.

    If you do not implement this method, the default return value is YEStrue.

    Availability

    Available in iOS 6.0 and later.

  • Tells the delegate that the item at the specified index path was selected.

    Declaration

    Swift

    optional func collectionView(_ collectionView: UICollectionView, didSelectItemAtIndexPath indexPath: NSIndexPath)

    Objective-C

    - (void)collectionView:(UICollectionView *)collectionView didSelectItemAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    collectionView

    The collection view object that is notifying you of the selection change.

    indexPath

    The index path of the cell that was selected.

    Discussion

    The collection view calls this method when the user successfully selects an item in the collection view. It does not call this method when you programmatically set the selection.

    Availability

    Available in iOS 6.0 and later.

  • Asks the delegate if the specified item should be deselected.

    Declaration

    Swift

    optional func collectionView(_ collectionView: UICollectionView, shouldDeselectItemAtIndexPath indexPath: NSIndexPath) -> Bool

    Objective-C

    - (BOOL)collectionView:(UICollectionView *)collectionView shouldDeselectItemAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    collectionView

    The collection view object that is asking whether the selection should change.

    indexPath

    The index path of the cell to be deselected.

    Return Value

    YEStrue if the item should be deselected or NOfalse if it should not.

    Discussion

    The collection view calls this method when the user tries to deselect an item in the collection view. It does not call this method when you programmatically deselect items.

    If you do not implement this method, the default return value is YEStrue.

    Availability

    Available in iOS 6.0 and later.

  • Tells the delegate that the item at the specified path was deselected.

    Declaration

    Swift

    optional func collectionView(_ collectionView: UICollectionView, didDeselectItemAtIndexPath indexPath: NSIndexPath)

    Objective-C

    - (void)collectionView:(UICollectionView *)collectionView didDeselectItemAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    collectionView

    The collection view object that is notifying you of the selection change.

    indexPath

    The index path of the cell that was deselected.

    Discussion

    The collection view calls this method when the user successfully deselects an item in the collection view. It does not call this method when you programmatically deselect items.

    Availability

    Available in iOS 6.0 and later.

  • Asks the delegate if the item should be highlighted during tracking.

    Declaration

    Swift

    optional func collectionView(_ collectionView: UICollectionView, shouldHighlightItemAtIndexPath indexPath: NSIndexPath) -> Bool

    Objective-C

    - (BOOL)collectionView:(UICollectionView *)collectionView shouldHighlightItemAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    collectionView

    The collection view object that is asking about the highlight change.

    indexPath

    The index path of the cell to be highlighted.

    Return Value

    YEStrue if the item should be highlighted or NOfalse if it should not.

    Discussion

    As touch events arrive, the collection view highlights items in anticipation of the user selecting them. As it processes those touch events, the collection view calls this method to ask your delegate if a given cell should be highlighted. It calls this method only in response to user interactions and does not call it if you programmatically set the highlighting on a cell.

    If you do not implement this method, the default return value is YEStrue.

    Availability

    Available in iOS 6.0 and later.

  • Tells the delegate that the item at the specified index path was highlighted.

    Declaration

    Swift

    optional func collectionView(_ collectionView: UICollectionView, didHighlightItemAtIndexPath indexPath: NSIndexPath)

    Objective-C

    - (void)collectionView:(UICollectionView *)collectionView didHighlightItemAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    collectionView

    The collection view object that is notifying you of the highlight change.

    indexPath

    The index path of the cell that was highlighted.

    Discussion

    The collection view calls this method only in response to user interactions and does not call it if you programmatically set the highlighting on a cell.

    Availability

    Available in iOS 6.0 and later.

  • Tells the delegate that the highlight was removed from the item at the specified index path.

    Declaration

    Swift

    optional func collectionView(_ collectionView: UICollectionView, didUnhighlightItemAtIndexPath indexPath: NSIndexPath)

    Objective-C

    - (void)collectionView:(UICollectionView *)collectionView didUnhighlightItemAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    collectionView

    The collection view object that is notifying you of the highlight change.

    indexPath

    The index path of the cell that had its highlight removed.

    Discussion

    The collection view calls this method only in response to user interactions and does not call it if you programmatically change the highlighting on a cell.

    Availability

    Available in iOS 6.0 and later.

  • Asks for the custom transition layout to use when moving between the specified layouts.

    Declaration

    Swift

    optional func collectionView(_ collectionView: UICollectionView, transitionLayoutForOldLayout fromLayout: UICollectionViewLayout, newLayout toLayout: UICollectionViewLayout) -> UICollectionViewTransitionLayout

    Objective-C

    - (UICollectionViewTransitionLayout *)collectionView:(UICollectionView *)collectionView transitionLayoutForOldLayout:(UICollectionViewLayout *)fromLayout newLayout:(UICollectionViewLayout *)toLayout

    Parameters

    collectionView

    The collection view whose layout object is changing.

    fromLayout

    The current layout 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

    Implement this method if you want to return a custom UICollectionViewTransitionLayout object for use during the transition. A transition layout object lets you customize the behavior of cells and decoration views when transitioning from one layout to the next. Normally, transitioning between layouts causes items to animate directly from their current locations to their new locations. With a transition layout object, you can have objects follow a non linear path, use a different timing algorithm, or move according to incoming touch events.

    If your delegate does not implement this method, the collection view creates a standard UICollectionViewTransitionLayout object and uses that object to manage the transition.

    Availability

    Available in iOS 7.0 and later.

  • Gives the delegate an opportunity to customize the content offset for layout changes and animated updates.

    Declaration

    Swift

    optional func collectionView(_ collectionView: UICollectionView, targetContentOffsetForProposedContentOffset proposedContentOffset: CGPoint) -> CGPoint

    Objective-C

    - (CGPoint)collectionView:(UICollectionView *)collectionView targetContentOffsetForProposedContentOffset:(CGPoint)proposedContentOffset

    Parameters

    collectionView

    The collection view making the request.

    proposedContentOffset

    The proposed point (in the coordinate space of the collection view’s content view) for the upper-left corner of the visible content. This represents the point that the collection view has calculated as the most likely value to use for the animations or layout update.

    Return Value

    The content offset that you want to use instead. If you do not implement this method, the collection view uses the value in the proposedContentOffset parameter.

    Discussion

    During layout updates, or when transitioning between layouts, the collection view calls this method to give you the opportunity to change the proposed content offset to use at the end of the animation. You might return a new value if the layout or animations might cause items to be positioned in a way that is not optimal for your design.

    This method is called after the layout object’s targetContentOffsetForProposedContentOffset: method. Implement this method in situations where you do not want to subclass your layout object to modify the content offset.

    Availability

    Available in iOS 9.0 and later.

  • Asks the delegate for the index path to use when moving an item.

    Declaration

    Swift

    optional func collectionView(_ collectionView: UICollectionView, targetIndexPathForMoveFromItemAtIndexPath originalIndexPath: NSIndexPath, toProposedIndexPath proposedIndexPath: NSIndexPath) -> NSIndexPath

    Objective-C

    - (NSIndexPath *)collectionView:(UICollectionView *)collectionView targetIndexPathForMoveFromItemAtIndexPath:(NSIndexPath *)originalIndexPath toProposedIndexPath:(NSIndexPath *)proposedIndexPath

    Parameters

    collectionView

    The collection view making the request.

    originalIndexPath

    The item’s original index path.

    proposedIndexPath

    The proposed index path of the item.

    Return Value

    The index path you want to use for the item. If you do not implement this method, the collection view uses the index path in the proposedIndexPath parameter.

    Discussion

    During the interactive moving of an item, the collection view calls this method to see if you want to provide a different index path than the proposed path. You might use this method to prevent the user from dropping the item in an invalid location. For example, you might prevent the user from dropping the item in a specific section.

    Availability

    Available in iOS 9.0 and later.

  • Asks the delegate if an action menu should be displayed for the specified item.

    Declaration

    Swift

    optional func collectionView(_ collectionView: UICollectionView, shouldShowMenuForItemAtIndexPath indexPath: NSIndexPath) -> Bool

    Objective-C

    - (BOOL)collectionView:(UICollectionView *)collectionView shouldShowMenuForItemAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    collectionView

    The collection view object that is making the request.

    indexPath

    The index path of the affected item.

    Return Value

    YEStrue if the editing menu should be shown positioned near the item and pointing to it or NOfalse if it should not.

    Discussion

    If the user tap-holds a certain item in the collection view, this method (if implemented) is invoked first. Return YEStrue if you want to permit the editing menu to be displayed. Return NOfalse if the editing menu shouldn’t be shown—for example, you might return NOfalse if the corresponding item contains data that should not be copied or pasted over.

    If you do not implement this method, the default return value is NOfalse.

    Availability

    Available in iOS 6.0 and later.

  • Asks the delegate if it can perform the specified action on an item in the collection view.

    Declaration

    Swift

    optional func collectionView(_ collectionView: UICollectionView, canPerformAction action: Selector, forItemAtIndexPath indexPath: NSIndexPath, withSender sender: AnyObject?) -> Bool

    Objective-C

    - (BOOL)collectionView:(UICollectionView *)collectionView canPerformAction:(SEL)action forItemAtIndexPath:(NSIndexPath *)indexPath withSender:(id)sender

    Parameters

    collectionView

    The collection view object that is making the request.

    action

    The selector identifying the action to be performed.

    indexPath

    The index path of the affected item.

    sender

    The object that wants to initiate the action.

    Return Value

    YEStrue if the command corresponding to action should appear in the editing menu or NOfalse if it should not.

    Discussion

    This method is invoked after the collectionView:shouldShowMenuForItemAtIndexPath: method. It gives you the opportunity to exclude commands from the editing menu. For example, the user might have copied some content from one item and wants to paste it into another item that cannot accept the content. In such a case, your method could return NOfalse to prevent the display of the relevant command.

    If you do not implement this method, the default return value is NOfalse.

    Availability

    Available in iOS 6.0 and later.

  • Tells the delegate to perform the specified action on an item in the collection view.

    Declaration

    Swift

    optional func collectionView(_ collectionView: UICollectionView, performAction action: Selector, forItemAtIndexPath indexPath: NSIndexPath, withSender sender: AnyObject?)

    Objective-C

    - (void)collectionView:(UICollectionView *)collectionView performAction:(SEL)action forItemAtIndexPath:(NSIndexPath *)indexPath withSender:(id)sender

    Parameters

    collectionView

    The collection view object that is making the request.

    action

    The selector representing the action to be performed.

    indexPath

    The index path of the affected item.

    sender

    The object that initiated the action.

    Discussion

    If the user taps an action in the editing menu, the collection view calls this method. Your implementation of this method should do whatever is appropriate for the action. For example, for a copy action, it should extract the relevant item content and write it to the general pasteboard or an application (private) pasteboard.

    For information about how to perform pasteboard-related operations, see UIPasteboard Class Reference.

    Availability

    Available in iOS 6.0 and later.

  • Asks the delegate whether the item at the specified index path can be focused.

    Declaration

    Swift

    optional func collectionView(_ collectionView: UICollectionView, canFocusItemAtIndexPath indexPath: NSIndexPath) -> Bool

    Objective-C

    - (BOOL)collectionView:(UICollectionView *)collectionView canFocusItemAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    collectionView

    The collection view object requesting this information.

    indexPath

    The index path of an item in the collection view.

    Return Value

    YEStrue if the item can receive be focused or NOfalse if it can not.

    Discussion

    You can use this method, or a cell’s canBecomeFocused method, to control which items in the collection view can receive focus. The focus engine calls the cell’s canBecomeFocused method first, the default implementation of which defers to the collection view and this delegate method.

    If you do not implement this method, the ability to focus on items depends on whether the collection view’s items are selectable. When the items are selectable, they can also be focused as if this method had returned YEStrue; otherwise, they do not receive focus.

    Availability

    Available in iOS 9.0 and later.

    See Also

    allowsSelection

  • Asks the delegate for the index path of the cell that should be focused.

    Declaration

    Swift

    optional func indexPathForPreferredFocusedViewInCollectionView(_ collectionView: UICollectionView) -> NSIndexPath?

    Objective-C

    - (NSIndexPath *)indexPathForPreferredFocusedViewInCollectionView:(UICollectionView *)collectionView

    Parameters

    collectionView

    The collection view object requesting this information.

    Return Value

    The index path of the preferred cell. The index path you specify must correspond go a valid cell in the collection view.

    Discussion

    When focus is about to change to a collection view, the collection view must pick which of its subviews should receive that focus. If the collection view’s remembersLastFocusedIndexPath property is set to YEStrue, the collection view returns the index path of the cell that was last focused. If the remembersLastFocusedIndexPath property is NOfalse, the collection view calls this method so that you can specify which cell should receive focus. If you do not implement this method, the collection view returns an appropriate cell.

    If you subclass UICollectionView, you can also implement the same behavior by overriding the preferredFocusedView property, which is defined by the UIFocusEnvironment protocol and adopted by all views.

    Availability

    Available in iOS 9.0 and later.

    See Also

    preferredFocusedView (UIFocusEnvironment)

  • Asks the delegate whether a change in focus should occur.

    Declaration

    Swift

    optional func collectionView(_ collectionView: UICollectionView, shouldUpdateFocusInContext context: UICollectionViewFocusUpdateContext) -> Bool

    Objective-C

    - (BOOL)collectionView:(UICollectionView *)collectionView shouldUpdateFocusInContext:(UICollectionViewFocusUpdateContext *)context

    Parameters

    collectionView

    The collection view object requesting this information.

    context

    The context object containing metadata associated with the focus change. This object contains the index path of the previously focused item and the item targeted to receive focus next. Use this information to determine if the focus change should occur.

    Return Value

    YEStrue if the focus change should occur or NOfalse if it should not.

    Discussion

    Before a focus change can occur, the focus engine asks all affected views if such a change should occur. In response, the collection view calls this method to give you the opportunity to allow or prevent the change. Return this method to prevent changes that should not occur. For example, you might use it to ensure that the navigation between cells occurs in a specific order.

    If you do not implement this method, the collection view assumes a return value of YEStrue.

    If you subclass UICollectionView, you can also implement the same behavior by overriding the shouldUpdateFocusInContext: method, which is defined by the UIFocusEnvironment protocol and adopted by all views.

    Availability

    Available in iOS 9.0 and later.

    See Also

    – shouldUpdateFocusInContext: (UIFocusEnvironment)

  • Tells the delegate that a focus update occurred.

    Declaration

    Swift

    optional func collectionView(_ collectionView: UICollectionView, didUpdateFocusInContext context: UICollectionViewFocusUpdateContext, withAnimationCoordinator coordinator: UIFocusAnimationCoordinator)

    Objective-C

    - (void)collectionView:(UICollectionView *)collectionView didUpdateFocusInContext:(UICollectionViewFocusUpdateContext *)context withAnimationCoordinator:(UIFocusAnimationCoordinator *)coordinator

    Parameters

    collectionView

    The collection view object notifying you of the focus change.

    context

    The context object containing metadata associated with the focus change. This object contains the index path of the previously focused item and the currently focused item.

    coordinator

    The animation coordinator to use when creating any additional animations.

    Discussion

    The collection view calls this method when a focus-related change occurs. You can use this method to update your app’s state information or to animate changes to your app’s visual appearance.

    If you subclass UICollectionView, you can also implement the same behavior by overriding the didUpdateFocusInContext:withAnimationCoordinator: method, which is defined by the UIFocusEnvironment protocol and adopted by all views.

    Availability

    Available in iOS 9.0 and later.