iOS Developer Library

Developer

UIKit Framework Reference UICollectionViewDelegate Protocol Reference

Options
Deployment Target:

On This Page
Language:

UICollectionViewDelegate

Inheritance


Not Applicable

Conforms To


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 6.0 and later.

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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • Tells the delegate that the specified cell is about to be displayed in the collection view.

    Declaration

    Swift

    optional func collectionView(_ collectionView: UICollectionView, willDisplayCell cell: UICollectionViewCell, forItemAtIndexPath indexPath: NSIndexPath)

    Objective-C

    - (void)collectionView:(UICollectionView *)collectionView willDisplayCell:(UICollectionViewCell *)cell forItemAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    collectionView

    The collection view object that is adding the cell.

    cell

    The cell object being added.

    indexPath

    The index path of the data item that the cell represents.

    Discussion

    The collection view calls this method before adding a cell to its content. Use this method to detect cell additions, as opposed to monitoring the cell itself to see when it appears.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • Tells the delegate that the specified supplementary view is about to be displayed in the collection view.

    Declaration

    Swift

    optional func collectionView(_ collectionView: UICollectionView, willDisplaySupplementaryView view: UICollectionReusableView, forElementKind elementKind: String, atIndexPath indexPath: NSIndexPath)

    Objective-C

    - (void)collectionView:(UICollectionView *)collectionView willDisplaySupplementaryView:(UICollectionReusableView *)view forElementKind:(NSString *)elementKind atIndexPath:(NSIndexPath *)indexPath

    Parameters

    collectionView

    The collection view object that is adding the supplementary view.

    view

    The view being added.

    elementKind

    The type of the supplementary view. This string is defined by the layout that presents the view.

    indexPath

    The index path of the data item that the supplementary view represents.

    Discussion

    The collection view calls this method before adding a supplementary view to its content. Use this method to detect view additions, as opposed to monitoring the view itself to see when it appears.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • Tells the delegate that the specified cell was removed from the collection view.

    Declaration

    Swift

    optional func collectionView(_ collectionView: UICollectionView, didEndDisplayingCell cell: UICollectionViewCell, forItemAtIndexPath indexPath: NSIndexPath)

    Objective-C

    - (void)collectionView:(UICollectionView *)collectionView didEndDisplayingCell:(UICollectionViewCell *)cell forItemAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    collectionView

    The collection view object that removed the cell.

    cell

    The cell object that was removed.

    indexPath

    The index path of the data item that the cell represented.

    Discussion

    Use this method to detect when a cell is removed from a collection view, as opposed to monitoring the view itself to see when it disappears.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • Tells the delegate that the specified supplementary view was removed from the collection view.

    Declaration

    Swift

    optional func collectionView(_ collectionView: UICollectionView, didEndDisplayingSupplementaryView view: UICollectionReusableView, forElementOfKind elementKind: String, atIndexPath indexPath: NSIndexPath)

    Objective-C

    - (void)collectionView:(UICollectionView *)collectionView didEndDisplayingSupplementaryView:(UICollectionReusableView *)view forElementOfKind:(NSString *)elementKind atIndexPath:(NSIndexPath *)indexPath

    Parameters

    collectionView

    The collection view object that removed the supplementary view.

    view

    The view that was removed.

    elementKind

    The type of the supplementary view. This string is defined by the layout that presents the view.

    indexPath

    The index path of the data item that the supplementary view represented.

    Discussion

    Use this method to detect when a supplementary view is removed from a collection view, as opposed to monitoring the view itself to see when it appears or disappears.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.