UICollectionViewDelegate Protocol Reference

Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 6.0 and later.
Declared in
UICollectionView.h

Overview

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.

Tasks

Managing the Selected Cells

Managing Cell Highlighting

Tracking the Removal of Views

Providing a Transition Layout

Managing Actions for Cells

Instance Methods

collectionView:canPerformAction:forItemAtIndexPath:withSender:

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

- (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

YES if the command corresponding to action should appear in the editing menu or NO 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 NO to prevent the display of the relevant command.

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

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionView.h

collectionView:didDeselectItemAtIndexPath:

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

- (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.
Declared In
UICollectionView.h

collectionView:didEndDisplayingCell:forItemAtIndexPath:

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

- (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 appears or disappears.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionView.h

collectionView:didEndDisplayingSupplementaryView:forElementOfKind:atIndexPath:

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

- (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.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionView.h

collectionView:didHighlightItemAtIndexPath:

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

- (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.
Declared In
UICollectionView.h

collectionView:didSelectItemAtIndexPath:

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

- (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.
Declared In
UICollectionView.h

collectionView:didUnhighlightItemAtIndexPath:

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

- (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.
Declared In
UICollectionView.h

collectionView:performAction:forItemAtIndexPath:withSender:

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

- (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.
Declared In
UICollectionView.h

collectionView:shouldDeselectItemAtIndexPath:

Asks the delegate if the specified item should be deselected.

- (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

YES if the item should be deselected or NO 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 YES.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionView.h

collectionView:shouldHighlightItemAtIndexPath:

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

- (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

YES if the item should be highlighted or NO 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 YES.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionView.h

collectionView:shouldSelectItemAtIndexPath:

Asks the delegate if the specified item should be selected.

- (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

YES if the item should be selected or NO 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 YES.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionView.h

collectionView:shouldShowMenuForItemAtIndexPath:

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

- (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

YES if the editing menu should be shown positioned near the item and pointing to it or NO 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 YES if you want to permit the editing menu to be displayed. Return NO if the editing menu shouldn’t be shown—for example, you might return NO 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 NO.

Availability
  • Available in iOS 6.0 and later.
Declared In
UICollectionView.h

collectionView:transitionLayoutForOldLayout:newLayout:

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

- (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.
Declared In
UICollectionView.h