UICollectionView Class Reference

Contents

UICollectionView Class Reference 4Overview 4

Collection Views and Layout Objects 5Creating Cells and Supplementary Views 5

Tasks 6Initializing a Collection View 6Configuring the Collection View 6Creating Collection View Cells 7Reloading Content 7Getting the State of the Collection View 7Inserting, Moving, and Deleting Items 8Inserting, Moving, and Deleting Sections 8Managing the Selection 8Locating Items in the Collection View 9Getting Layout Information 9Scrolling an Item Into View 9Animating Multiple Changes to the Collection View 9

Properties 9allowsMultipleSelection 9allowsSelection 10backgroundView 10collectionViewLayout 11dataSource 11delegate 12

Instance Methods 12cellForItemAtIndexPath: 12deleteItemsAtIndexPaths: 13deleteSections: 13dequeueReusableCellWithReuseIdentifier:forIndexPath: 14dequeueReusableSupplementaryViewOfKind:withReuseIdentifier:forIndexPath: 15deselectItemAtIndexPath:animated: 16indexPathForCell: 17indexPathForItemAtPoint: 17indexPathsForSelectedItems 18

2012-09-19 | Copyright © 2012 Apple Inc. All Rights Reserved.

2

indexPathsForVisibleItems 18initWithFrame:collectionViewLayout: 18insertItemsAtIndexPaths: 19insertSections: 20layoutAttributesForItemAtIndexPath: 20layoutAttributesForSupplementaryElementOfKind:atIndexPath: 21moveItemAtIndexPath:toIndexPath: 22moveSection:toSection: 22numberOfItemsInSection: 23numberOfSections 24performBatchUpdates:completion: 24registerClass:forCellWithReuseIdentifier: 25registerClass:forSupplementaryViewOfKind:withReuseIdentifier: 26registerNib:forCellWithReuseIdentifier: 27registerNib:forSupplementaryViewOfKind:withReuseIdentifier: 27reloadData 28reloadItemsAtIndexPaths: 29reloadSections: 29scrollToItemAtIndexPath:atScrollPosition:animated: 30selectItemAtIndexPath:animated:scrollPosition: 30setCollectionViewLayout:animated: 31visibleCells 32

Constants 32UICollectionViewScrollPosition 32

Document Revision History 35


3

Contents

Inherits from UIScrollView : UIView : UIResponder : NSObject

Conforms to NSCoding (UIScrollView)

NSCoding (UIView)

UIAppearance (UIView)

UIAppearanceContainer (UIView)

NSObject (NSObject)

Framework /System/Library/Frameworks/UIKit.framework

Availability Available in iOS 6.0 and later.

Declared in UICollectionView.h

Related sample code CollectionView-Simple

iAdSuite

iAdSuite with Storyboards

OverviewThe UICollectionView class manages an ordered collection of data items and presents them usingcustomizable layouts. Collection views provide the same general function as table views except that a collectionview is able to support more than just single-column layouts. Collection views support customizable layoutsthat can be used to implement multi-column grids, tiled layouts, circular layouts, and many more. You caneven change the layout of a collection view dynamically if you want.

When adding a collection view to your user interface, your app’s main job is to manage the data associatedwith that collection view. The collection view gets its data from the data source object, which is an object thatconforms to the UICollectionViewDataSourceprotocol and is provided by your app. Data in the collectionview is organized into individual items, which can then be grouped into sections for presentation. An item isthe smallest unit of data you want to present. For example, in a photos app, an item might be a single image.The collection view presents items onscreen using a cell, which is an instance of the UICollectionViewCellclass that your data source configures and provides.


4

UICollectionView Class Reference

In addition to its cells, a collection view can present data using other types of views too. These supplementaryviews can be things like section headers and footers that are separate from the individual cells but still conveysome sort of information. Support for supplementary views is optional and defined by the collection view’slayout object, which is also responsible for defining the placement of those views.

Besides embedding it in your user interface, you use the methods of UICollectionView object to ensurethat the visual presentation of items matches the order in your data source object. Thus, whenever you add,delete, or rearrange data in your collection, you use the methods of this class to insert, delete, and rearrangethe corresponding cells. You also use the collection view object to manage the selected items, although forthis behavior the collection view works with its associated delegate (page 12) object.

Collection Views and Layout ObjectsA very important object associated with a collection view is the layout object, which is a subclass of theUICollectionViewLayout class. The layout object is responsible for defining the organization and locationof all cells and supplementary views inside the collection view. Although it defines their locations, the layoutobject does not actually apply that information to the corresponding views. Because the creation of cells andsupplementary views involves coordination between the collection view and your data source object, thecollection view actually applies layout information to the views. Thus, in a sense, the layout object is like anotherdata source, only providing visual information instead of item data.

You normally specify a layout object when creating a collection view but you can also change the layout of acollection view dynamically. The layout object is stored in the collectionViewLayout (page 11) property.Setting this property directly updates the layout immediately, without animating the changes. If you want toanimate the changes, you must call the setCollectionViewLayout:animated: (page 31) method instead.

Creating Cells and Supplementary ViewsThe collection view’s data source object provides both the content for items and the views used to presentthat content. When the collection view first loads its content, it asks its data source to provide a view for eachvisible item. To simplify the creation process for your code, the collection view requires that you always dequeueviews, rather than create them explicitly in your code. There are two methods for dequeueing views. The oneyou use depends on which type of view has been requested:

● Use the dequeueReusableCellWithReuseIdentifier:forIndexPath: (page 14) to get a cell for an itemin the collection view.

● Use the dequeueReusableSupplementaryViewOfKind:withReuseIdentifier:forIndexPath: (page 15)method to get a supplementary view requested by the layout object.

UICollectionView Class ReferenceOverview


5

Before you call either of these methods, you must tell the collection view how to create the correspondingview if one does not already exist. For this, you must register either a class or a nib file with the collection view.For example, when registering cells, you use the registerClass:forCellWithReuseIdentifier: (page 25)or registerNib:forCellWithReuseIdentifier: (page 27) method. As part of the registration process, youspecify the reuse identifier that identifies the purpose of the view. This is the same string you use whendequeueing the view later.

After dequeueing the appropriate view in your delegate method, configure its content and return it to thecollection view for use. After getting the layout information from the layout object, the collection view appliesit to the view and displays it.

For more information about implementing the data source methods to create and configure views, seeUICollectionViewDataSource Protocol Reference .

Tasks

Initializing a Collection View

– initWithFrame:collectionViewLayout: (page 18)Initializes and returns a newly allocated collection view object with the specified frame and layout.

Configuring the Collection View

collectionViewLayout (page 11) propertyThe layout used to organize the collected view’s items.

– setCollectionViewLayout:animated: (page 31)Assigns a new layout object to the collection view and optionally animates the change.

delegate (page 12) propertyThe object that acts as the delegate of the collection view.

dataSource (page 11) propertyThe object that provides the data for the collection view.

backgroundView (page 10) propertyThe view that provides the background appearance.

UICollectionView Class ReferenceTasks


6

Creating Collection View Cells

– registerClass:forCellWithReuseIdentifier: (page 25)Register a class for use in creating new collection view cells.

– registerNib:forCellWithReuseIdentifier: (page 27)Register a nib file for use in creating new collection view cells.

– registerClass:forSupplementaryViewOfKind:withReuseIdentifier: (page 26)Registers a class for use in creating supplementary views for the collection view.

– registerNib:forSupplementaryViewOfKind:withReuseIdentifier: (page 27)Registers a nib file for use in creating supplementary views for the collection view.

– dequeueReusableCellWithReuseIdentifier:forIndexPath: (page 14)Returns a reusable cell object located by its identifier

– dequeueReusableSupplementaryViewOfKind:withReuseIdentifier:forIndexPath: (page 15)Returns a reusable supplementary view located by its identifier and kind.

Reloading Content

– reloadData (page 28)Reloads all of the data for the collection view.

– reloadSections: (page 29)Reloads the data in the specified sections of the collection view.

– reloadItemsAtIndexPaths: (page 29)Reloads just the items at the specified index paths.

Getting the State of the Collection View

– numberOfSections (page 24)Returns the number of sections displayed by the collection view.

– numberOfItemsInSection: (page 23)Returns the number of items in the specified section.

– visibleCells (page 32)Returns an array of visible cells currently displayed by the collection view.



7

Inserting, Moving, and Deleting Items

– insertItemsAtIndexPaths: (page 19)Inserts new items at the specified index paths.

– moveItemAtIndexPath:toIndexPath: (page 22)Moves an item from one location to another in the collection view.

– deleteItemsAtIndexPaths: (page 13)Deletes the items at the specified index paths.

Inserting, Moving, and Deleting Sections

– insertSections: (page 20)Inserts new sections at the specified indexes.

– moveSection:toSection: (page 22)Moves a section from one location to another in the collection view.

– deleteSections: (page 13)Deletes the sections at the specified indexes.

Managing the Selection

allowsSelection (page 10) propertyA Boolean value that indicates whether users can select items in the collection view.

allowsMultipleSelection (page 9) propertyA Boolean value that determines whether users can select more than one item in the collection view.

– indexPathsForSelectedItems (page 18)Returns the index paths for the selected items.

– selectItemAtIndexPath:animated:scrollPosition: (page 30)Selects the item at the specified index path and optionally scrolls it into view.

– deselectItemAtIndexPath:animated: (page 16)Deselects the item at the specified index.



8

Locating Items in the Collection View

– indexPathForItemAtPoint: (page 17)Returns the index path of the item at the specified point in the collection view.

– indexPathsForVisibleItems (page 18)Returns an array of the visible items in the collection view.

– indexPathForCell: (page 17)Returns the index path of the specified cell.

– cellForItemAtIndexPath: (page 12)Returns the cell object at the specified index path.

Getting Layout Information

– layoutAttributesForItemAtIndexPath: (page 20)Returns the layout information for the item at the specified index path.

– layoutAttributesForSupplementaryElementOfKind:atIndexPath: (page 21)Returns the layout information for the specified supplementary view.

Scrolling an Item Into View

– scrollToItemAtIndexPath:atScrollPosition:animated: (page 30)Scrolls the collection view contents until the specified item is visible.

Animating Multiple Changes to the Collection View

– performBatchUpdates:completion: (page 24)Animates multiple insert, delete, reload, and move operations as a group.

Properties

allowsMultipleSelection

A Boolean value that determines whether users can select more than one item in the collection view.

UICollectionView Class ReferenceProperties


9

@property (nonatomic) BOOL allowsMultipleSelection

DiscussionThis property controls whether multiple items can be selected simultaneously. The default value of this propertyis NO.

When the value of this property is YES, tapping a cell adds it to the current selection (assuming the delegatepermits the cell to be selected). Tapping the cell again removes it from the selection.

AvailabilityAvailable in iOS 6.0 and later.

See Also @property allowsSelection (page 10)

Declared inUICollectionView.h

allowsSelection

A Boolean value that indicates whether users can select items in the collection view.

@property (nonatomic) BOOL allowsSelection

DiscussionIf the value of this property is YES (the default), users can select items. If you want more fine-grained controlover the selection of items, you must provide a delegate object and implement the appropriate methods ofthe UICollectionViewDelegate protocol.


See Also @property allowsMultipleSelection (page 9)


backgroundView

The view that provides the background appearance.



10

@property (nonatomic, retain) UIView *backgroundView;

DiscussionThe view (if any) in this property is positioned underneath all of the other content and sized automatically tofill the entire bounds of the collection view. The background view does not scroll with the collection view’sother content. The collection view maintains a strong reference to the background view object.

This property is nil by default, which displays the background color of the collection view.



collectionViewLayout

The layout used to organize the collected view’s items.

@property (nonatomic, retain) UICollectionViewLayout *collectionViewLayout;

DiscussionAssigning a new layout object to this property causes the new layout to be applied (without animations) tothe collection view’s items.



dataSource

The object that provides the data for the collection view.

@property (nonatomic, assign) id <UICollectionViewDataSource> dataSource;

DiscussionThe data source must adopt the UICollectionViewDataSource protocol. The collection view maintains aweak reference to the data source object.




11


delegate

The object that acts as the delegate of the collection view.

@property (nonatomic, assign) id <UICollectionViewDelegate> delegate;

DiscussionThe delegate must adopt the UICollectionViewDelegate protocol. The collection view maintains a weakreference to the delegate object.

The delegate object is responsible for managing selection behavior and interactions with individual items.



Instance Methods

cellForItemAtIndexPath:

Returns the cell object at the specified index path.

- (UICollectionViewCell *)cellForItemAtIndexPath:(NSIndexPath *)indexPath

ParametersindexPath

The index path that specifies the section and item number of the cell.

Return ValueThe cell object at the corresponding index path or nil if no cell was found at that location.



UICollectionView Class ReferenceInstance Methods


12

deleteItemsAtIndexPaths:

Deletes the items at the specified index paths.

- (void)deleteItemsAtIndexPaths:(NSArray *)indexPaths

ParametersindexPaths

An array of NSIndexPath objects, each of which contains a section index and item index for the itemyou want to delete from the collection view. This parameter must not be nil.

DiscussionUse this method to remove items from the collection view. You might do this when you remove the itemsfrom your data source object or in response to user interactions with the collection view. The collection viewupdates the layout of the remaining items to account for the deletions, animating the remaining items intoposition as needed.

You can also call this method from a block passed to the performBatchUpdates:completion: (page 24)method when you want to animate multiple separate changes into place at the same time. See the descriptionof that method for more information.



deleteSections:

Deletes the sections at the specified indexes.

- (void)deleteSections:(NSIndexSet *)sections

Parameterssections

The indexes of the sections you want to delete. This parameter must not be nil.

DiscussionUse this method to remove the sections and their items from the collection view. You might do this when youremove the sections from your data source object or in response to user interactions with the collection view.The collection view updates the layout of the remaining sections and items to account for the deletions,animating the remaining items into position as needed.



13




dequeueReusableCellWithReuseIdentifier:forIndexPath:

Returns a reusable cell object located by its identifier

- (id)dequeueReusableCellWithReuseIdentifier:(NSString *)identifierforIndexPath:(NSIndexPath*)indexPath

Parametersidentifier

The reuse identifier for the specified cell. This parameter must not be nil.

indexPathThe index path specifying the location of the cell. The data source receives this information when it isasked for the cell and should just pass it along. This method uses the index path to perform additionalconfiguration based on the cell’s position in the collection view.

Return ValueA valid UICollectionReusableView object.

DiscussionCall this method from your data source object when asked to provide a new cell for the collection view. Thismethod dequeues an existing cell if one is available or creates a new one based on the class or nib file youpreviously registered.

Important: You must register a class or nib file using theregisterClass:forCellWithReuseIdentifier:orregisterNib:forCellWithReuseIdentifier:method before calling this method.

If you registered a class for the specified identifier and a new cell must be created, this method initializesthe cell by calling its initWithFrame: method. For nib-based cells, this method loads the cell object fromthe provided nib file. If an existing cell was available for reuse, this method calls the cell’s prepareForReusemethod instead.



14


See Also– registerClass:forCellWithReuseIdentifier: (page 25)– registerNib:forCellWithReuseIdentifier: (page 27)

Related Sample CodeCollectionView-SimpleiAdSuiteiAdSuite with Storyboards


dequeueReusableSupplementaryViewOfKind:withReuseIdentifier:forIndexPath:

Returns a reusable supplementary view located by its identifier and kind.

- (id)dequeueReusableSupplementaryViewOfKind:(NSString*)elementKindwithReuseIdentifier:(NSString *)identifier forIndexPath:(NSIndexPath*)indexPath

ParameterselementKind

The kind of supplementary view to retrieve. This value is defined by the layout object. This parametermust not be nil.

identifierThe reuse identifier for the specified view. This parameter must not be nil.

indexPathThe index path specifying the location of the supplementary view in the collection view. The data sourcereceives this information when it is asked for the view and should just pass it along. This method usesthe information to perform additional configuration based on the view’s position in the collection view.

Return ValueA valid UICollectionReusableView object.

DiscussionCall this method from your data source object when asked to provide a new supplementary view for thecollection view. This method dequeues an existing view if one is available or creates a new one based on theclass or nib file you previously registered.



15

Important: You must register a class or nib file using theregisterClass:forSupplementaryViewOfKind:withReuseIdentifier: orregisterNib:forSupplementaryViewOfKind:withReuseIdentifier: method before calling thismethod. You can also register a set of default supplementary views with the layout object using theregisterClass:forDecorationViewOfKind: or registerNib:forDecorationViewOfKind:method.

If you registered a class for the specified identifier and a new cell must be created, this method initializesthe cell by calling its initWithFrame: method. For nib-based cells, this method loads the cell object fromthe provided nib file. If an existing cell was available for reuse, this method calls the cell’s prepareForReusemethod instead.



deselectItemAtIndexPath:animated:

Deselects the item at the specified index.

- (void)deselectItemAtIndexPath:(NSIndexPath *)indexPath animated:(BOOL)animated

ParametersindexPath

The index path of the item to select. Specifying nil for this parameter removes the current selection.

animatedSpecify YES to animate the change in the selection or NO to make the change without animating it.

DiscussionIf the allowsSelection (page 10) property is NO, calling this method has no effect.

This method does not cause any selection-related delegate methods to be called.





16

indexPathForCell:

Returns the index path of the specified cell.

- (NSIndexPath *)indexPathForCell:(UICollectionViewCell *)cell

Parameterscell

The cell object whose index path you want.

Return ValueThe index path of the cell or nil if the specified cell is not in the collection view.



indexPathForItemAtPoint:

Returns the index path of the item at the specified point in the collection view.

- (NSIndexPath *)indexPathForItemAtPoint:(CGPoint)point

Parameterspoint

A point in the collection view’s coordinate system.

Return ValueThe index path of the item at the specified point or nil if no item was found at the specified point.

DiscussionThis method relies on the layout information provided by the associated layout object to determine whichitem contains the point.





17

indexPathsForSelectedItems

Returns the index paths for the selected items.

- (NSArray *)indexPathsForSelectedItems

Return ValueAn array of NSIndexPath objects, each of which corresponds to a single selected item. If there are no selecteditems, this method returns an empty array.



indexPathsForVisibleItems

Returns an array of the visible items in the collection view.

- (NSArray *)indexPathsForVisibleItems

Return ValueAn array of NSIndexPath objects, each of which corresponds to a visible cell in the collection view. This arraydoes not include any supplementary views that are currently visible. If there are no visible items, this methodreturns an empty array.


See Also– visibleCells (page 32)


initWithFrame:collectionViewLayout:

Initializes and returns a newly allocated collection view object with the specified frame and layout.

- (id)initWithFrame:(CGRect)frame collectionViewLayout:(UICollectionViewLayout*)layout



18

Parametersframe

The frame rectangle for the collection view, measured in points. The origin of the frame is relative to thesuperview in which you plan to add it. This frame is passed to the superclass during initialization.

layoutThe layout object to use for organizing items. The collection view stores a strong reference to the specifiedobject. You may specify nil for this parameter.

Return ValueAn initialized collection view object or nil if the object could not be created.

DiscussionUse this method when initializing a collection view object programmatically. If you specify nil for the layoutparameter, you must assign a layout object to the collectionViewLayout (page 11) property before displayingthe collection view onscreen. If you do not, the collection view will be unable to present any items onscreen.

This method is the designated initializer.



insertItemsAtIndexPaths:

Inserts new items at the specified index paths.

- (void)insertItemsAtIndexPaths:(NSArray *)indexPaths


An array of NSIndexPath objects, each of which contains a section index and item index at which toinsert a new cell. This parameter must not be nil.

DiscussionCall this method to insert one or more new items into the collection view. You might do this when your datasource object receives data for new items or in response to user interactions with the collection view. Thecollection view gets the layout information for the new cells as part of calling this method. And if the layoutinformation indicates that the cells should appear onscreen, the collection view asks your data source to providethe appropriate views, animating them into position as needed.



19




insertSections:

Inserts new sections at the specified indexes.

- (void)insertSections:(NSIndexSet *)sections

Parameterssections

An array of NSIndexPath objects, each of which contains the index of a section you want to insert. Thisparameter must not be nil.

DiscussionUse this method to insert one or more sections into the collection view. This method adds the sections, andit is up to your data source to report the number of items in each section when asked for the information. Thecollection view then uses that information to get updated layout attributes for the newly inserted sectionsand items. If the insertions cause a change in the collection view’s visible content, those changes are animatedinto place.




layoutAttributesForItemAtIndexPath:

Returns the layout information for the item at the specified index path.



20

- (UICollectionViewLayoutAttributes *)layoutAttributesForItemAtIndexPath:(NSIndexPath*)indexPath

ParametersindexPath

The index path of the item.

Return ValueThe layout attributes for the item or nil if no item exists at the specified path.

DiscussionUse this method to retrieve the layout information for a particular item. You should always use this methodinstead of querying the layout object directly.



layoutAttributesForSupplementaryElementOfKind:atIndexPath:

Returns the layout information for the specified supplementary view.

- (UICollectionViewLayoutAttributes*)layoutAttributesForSupplementaryElementOfKind:(NSString *)kindatIndexPath:(NSIndexPath *)indexPath

Parameterskind

A string specifying the kind of supplementary view whose layout attributes you want. Layout classes areresponsible for defining the kinds of supplementary views they support.

indexPathThe index path of the supplementary view. The interpretation of this value depends on how the layoutimplements the view. For example, a view associated with a section might contain just a section value.

Return ValueThe layout attributes of the supplementary view or nil if the specified supplementary view does not exist.

DiscussionUse this method to retrieve the layout information for a particular supplementary view. You should always usethis method instead of querying the layout object directly.



21



moveItemAtIndexPath:toIndexPath:

Moves an item from one location to another in the collection view.

- (void)moveItemAtIndexPath:(NSIndexPath *)indexPath toIndexPath:(NSIndexPath*)newIndexPath

ParametersindexPath

The index path of the item you want to move. This parameter must not be nil.

newIndexPathThe index path of the item’s new location. This parameter must not be nil.

DiscussionUse this method to reorganize existing data items. You might do this when you rearrange the items withinyour data source object or in response to user interactions with the collection view. You can move itemsbetween sections or within the same section. The collection view updates the layout as needed to account forthe move, animating cells into position as needed.




moveSection:toSection:

Moves a section from one location to another in the collection view.

- (void)moveSection:(NSInteger)section toSection:(NSInteger)newSection



22

Parameterssection

The index path of the section you want to move. This parameter must not be nil.

newSectionThe index path of the section’s new location. This parameter must not be nil.

DiscussionUse this method to reorganize existing sections and their contained items. You might do this when yourearrange sections within your data source object or in response to user interactions with the collection view.The collection view updates the layout as needed to account for the move, animating new views into positionas needed.




numberOfItemsInSection:

Returns the number of items in the specified section.

- (NSInteger)numberOfItemsInSection:(NSInteger)section

Parameterssection

The index of the section for which you want a count of the items.

Return ValueThe number of items in the specified section.





23

numberOfSections

Returns the number of sections displayed by the collection view.

- (NSInteger)numberOfSections

Return ValueThe number of sections in the collection view.



performBatchUpdates:completion:

Animates multiple insert, delete, reload, and move operations as a group.

- (void)performBatchUpdates:(void (^)(void))updates completion:(void (^)(BOOLfinished))completion

Parametersupdates

The block that performs the relevant insert, delete, reload, or move operations.

completionA completion handler block to execute when all of the operations are finished. This block takes a singleBoolean parameter that contains the value YES if all of the related animations completed successfully orNO if they were interrupted. This parameter may be nil.

DiscussionYou can use this method in cases where you want to insert, delete, reload or move cells around the collectionview in one single animated operation, as opposed to in several separate animations. Use the blocked passedin the updates parameter to specify all of the operations you want to perform.

When you group operations to insert, delete, reload, or move sections inside a single batch job, all operationsare performed based on the current indexes of the collection view. This is unlike modifying a mutable arraywhere the insertion or deletion of items affects the indexes of successive operations. Therefore, you do nothave to remember which items or sections were inserted, deleted, or moved and adjust the indexes of all otheroperations accordingly.



24


See Also– insertItemsAtIndexPaths: (page 19)– moveItemAtIndexPath:toIndexPath: (page 22)– deleteItemsAtIndexPaths: (page 13)– insertSections: (page 20)– moveSection:toSection: (page 22)– deleteSections: (page 13)


registerClass:forCellWithReuseIdentifier:

Register a class for use in creating new collection view cells.

- (void)registerClass:(Class)cellClass forCellWithReuseIdentifier:(NSString*)identifier

ParameterscellClass

The class of a cell that you want to use in the collection view.

identifierThe reuse identifier to associate with the specified class. This parameter must not be nil and must notbe an empty string.

DiscussionPrior to calling thedequeueReusableCellWithReuseIdentifier:forIndexPath:method of the collectionview, you must use this method or the registerNib:forCellWithReuseIdentifier: method to tell thecollection view how to create a new cell of the given type. If a cell of the specified type is not currently in areuse queue, the collection view uses the provided information to create a new cell object automatically.

If you previously registered a class or nib file with the same reuse identifier, the class you specify in thecellClass parameter replaces the old entry. You may specify nil for cellClass if you want to unregisterthe class from the specified reuse identifier.




25

See Also– registerNib:forCellWithReuseIdentifier: (page 27)– dequeueReusableCellWithReuseIdentifier:forIndexPath: (page 14)


registerClass:forSupplementaryViewOfKind:withReuseIdentifier:

Registers a class for use in creating supplementary views for the collection view.

- (void)registerClass:(Class)viewClass forSupplementaryViewOfKind:(NSString*)elementKind withReuseIdentifier:(NSString *)identifier

ParametersviewClass

The class to use for the supplementary view.

elementKindThe kind of supplementary view to create. This value is defined by the layout object. This parameter mustnot be nil.

identifierThe reuse identifier to associate with the specified class. This parameter must not be nil and must notbe an empty string.

DiscussionPrior to calling thedequeueReusableSupplementaryViewOfKind:withReuseIdentifier:forIndexPath: method ofthe collection view, you must use this method or theregisterNib:forSupplementaryViewOfKind:withReuseIdentifier: method to tell the collectionview how to create a supplementary view of the given type. If a view of the specified type is not currently ina reuse queue, the collection view uses the provided information to create a view object automatically.

If you previously registered a class or nib file with the same element kind and reuse identifier, the class youspecify in the viewClass parameter replaces the old entry. You may specify nil for viewClass if you wantto unregister the class from the specified element kind and reuse identifier.


See Also– registerNib:forSupplementaryViewOfKind:withReuseIdentifier: (page 27)



26

– dequeueReusableSupplementaryViewOfKind:withReuseIdentifier:forIndexPath: (page 15)


registerNib:forCellWithReuseIdentifier:

Register a nib file for use in creating new collection view cells.

- (void)registerNib:(UINib *)nib forCellWithReuseIdentifier:(NSString *)identifier

Parametersnib

The nib object containing the cell object. The nib file must contain only one top-level object and thatobject must be of the type UICollectionViewCell.

identifierThe reuse identifier to associate with the specified nib file. This parameter must not be nil and mustnot be an empty string.

DiscussionPrior to calling thedequeueReusableCellWithReuseIdentifier:forIndexPath:method of the collectionview, you must use this method or the registerClass:forCellWithReuseIdentifier: method to tellthe collection view how to create a new cell of the given type. If a cell of the specified type is not currently ina reuse queue, the collection view uses the provided information to create a new cell object automatically.

If you previously registered a class or nib file with the same reuse identifier, the object you specify in the nibparameter replaces the old entry. You may specify nil for nib if you want to unregister the nib file from thespecified reuse identifier.


See Also– registerClass:forCellWithReuseIdentifier: (page 25)– dequeueReusableCellWithReuseIdentifier:forIndexPath: (page 14)


registerNib:forSupplementaryViewOfKind:withReuseIdentifier:

Registers a nib file for use in creating supplementary views for the collection view.



27

- (void)registerNib:(UINib *)nib forSupplementaryViewOfKind:(NSString *)kindwithReuseIdentifier:(NSString *)identifier

Parametersnib

The nib object containing the view object. The nib file must contain only one top-level object and thatobject must be of the type UICollectionViewCell.

kindThe kind of supplementary view to create. This value is defined by the layout object. This parameter mustnot be nil.

identifierThe reuse identifier to associate with the specified nib file. This parameter must not be nil and mustnot be an empty string.

DiscussionPrior to calling thedequeueReusableSupplementaryViewOfKind:withReuseIdentifier:forIndexPath: method ofthe collection view, you must use this method or theregisterClass:forSupplementaryViewOfKind:withReuseIdentifier:method to tell the collectionview how to create a supplementary view of the given type. If a view of the specified type is not currently ina reuse queue, the collection view uses the provided information to create a view object automatically.

If you previously registered a class or nib file with the same element kind and reuse identifier, the class youspecify in the viewClass parameter replaces the old entry. You may specify nil for nib if you want tounregister the class from the specified element kind and reuse identifier.


See Also– registerClass:forSupplementaryViewOfKind:withReuseIdentifier: (page 26)– dequeueReusableSupplementaryViewOfKind:withReuseIdentifier:forIndexPath: (page 15)


reloadData

Reloads all of the data for the collection view.

- (void)reloadData



28

DiscussionCall this method to reload all of the items in the collection view. This causes the collection view to discard anycurrently visible items and redisplay them. For efficiency, the collection view only displays those cells andsupplementary views that are visible. If the collection data shrinks as a result of the reload, the collection viewadjusts its scrolling offsets accordingly.

You should not call this method in the middle of animation blocks where items are being inserted or deleted.Insertions and deletions automatically cause the table’s data to be updated appropriately.



reloadItemsAtIndexPaths:

Reloads just the items at the specified index paths.

- (void)reloadItemsAtIndexPaths:(NSArray *)indexPaths


An array of NSIndexPath objects identifying the items you want to update.

DiscussionCall this method to selectively reload only the specified items. This causes the collection view to discard anycells associated with those items and redisplay them.



reloadSections:

Reloads the data in the specified sections of the collection view.

- (void)reloadSections:(NSIndexSet *)sections



29

Parameterssections

The indexes of the sections to reload.

DiscussionCall this method to selectively reload only the items in the specified sections. This causes the collection viewto discard any cells associated with those items and redisplay them.



scrollToItemAtIndexPath:atScrollPosition:animated:

Scrolls the collection view contents until the specified item is visible.

- (void)scrollToItemAtIndexPath:(NSIndexPath *)indexPathatScrollPosition:(UICollectionViewScrollPosition)scrollPositionanimated:(BOOL)animated

ParametersindexPath

The index path of the item to scroll into view.

scrollPositionAn option that specifies where the item should be positioned when scrolling finishes. For a list of possiblevalues, see “UICollectionViewScrollPosition” (page 32).

animatedSpecify YES to animate the scrolling behavior or NO to adjust the scroll view’s visible content immediately.



selectItemAtIndexPath:animated:scrollPosition:

Selects the item at the specified index path and optionally scrolls it into view.



30

- (void)selectItemAtIndexPath:(NSIndexPath *)indexPath animated:(BOOL)animatedscrollPosition:(UICollectionViewScrollPosition)scrollPosition

ParametersindexPath

The index path of the item to select. Specifying nil for this parameter clears the current selection.

animatedSpecify YES to animate the change in the selection or NO to make the change without animating it.

scrollPositionAn option that specifies where the item should be positioned when scrolling finishes. For a list of possiblevalues, see “UICollectionViewScrollPosition” (page 32).

DiscussionIf the allowsSelection (page 10) property is NO, calling this method has no effect. If there is an existingselection with a different index path and the allowsMultipleSelection (page 9) property is NO, calling thismethod replaces the previous selection.

This method does not cause any selection-related delegate methods to be called.



setCollectionViewLayout:animated:

Assigns a new layout object to the collection view and optionally animates the change.

- (void)setCollectionViewLayout:(UICollectionViewLayout *)layoutanimated:(BOOL)animated

Parameterslayout

The new layout object to use to organize the collected views.

animatedSpecify YES if you want to animate changes from the current layout to the new layout specified by thelayout parameter. Specify NO to make the change without animations.

DiscussionWhen animating layout changes, the animation timing and parameters are controlled by the collection view.



31



visibleCells

Returns an array of visible cells currently displayed by the collection view.

- (NSArray *)visibleCells

Return ValueAn array of UICollectionViewCell objects. If no cells are visible, this method returns an empty array.

DiscussionThis method returns the complete list of visible cells displayed by the collection view.


See Also– indexPathsForVisibleItems (page 18)


Constants

UICollectionViewScrollPosition

Constants that indicate how to scroll an item into the visible portion of the collection view.

enum {UICollectionViewScrollPositionNone = 0,UICollectionViewScrollPositionTop = 1 << 0,UICollectionViewScrollPositionCenteredVertically = 1 << 1,UICollectionViewScrollPositionBottom = 1 << 2,

UICollectionViewScrollPositionLeft = 1 << 3,UICollectionViewScrollPositionCenteredHorizontally = 1 << 4,

UICollectionView Class ReferenceConstants


32

UICollectionViewScrollPositionRight = 1 << 5};typedef NSUInteger UICollectionViewScrollPosition;

ConstantsUICollectionViewScrollPositionNone

Do not scroll the item into view.

Available in iOS 6.0 and later.

Declared in UICollectionView.h.

UICollectionViewScrollPositionTopScroll so that the item is positioned at the top of the collection view’s bounds. This option is mutuallyexclusive with the UICollectionViewScrollPositionCenteredVertically andUICollectionViewScrollPositionBottom options.



UICollectionViewScrollPositionCenteredVerticallyScroll so that the item is centered vertically in the collection view. This option is mutually exclusive withthe UICollectionViewScrollPositionTop and UICollectionViewScrollPositionBottomoptions.



UICollectionViewScrollPositionBottomScroll so that the item is positioned at the bottom of the collection view’s bounds. This option is mutuallyexclusive with the UICollectionViewScrollPositionTop andUICollectionViewScrollPositionCenteredVertically options.



UICollectionViewScrollPositionLeftScroll so that the item is positioned at the left edge of the collection view’s bounds. This option is mutuallyexclusive with the UICollectionViewScrollPositionCenteredHorizontally andUICollectionViewScrollPositionRight options.





33

UICollectionViewScrollPositionCenteredHorizontallyScroll so that the item is centered horizontally in the collection view. This option is mutually exclusivewith theUICollectionViewScrollPositionLeft andUICollectionViewScrollPositionRightoptions.



UICollectionViewScrollPositionRightScroll so that the item is positioned at the right edge of the collection view’s bounds. This option ismutually exclusive with the UICollectionViewScrollPositionLeft andUICollectionViewScrollPositionCenteredHorizontally options.





34

This table describes the changes to UICollectionView Class Reference .

NotesDate

New document that describes a collection of views that displays contentin a grid.

2012-09-19


35

Document Revision History

Apple Inc.Copyright © 2012 Apple Inc.All rights reserved.

No part of this publication may be reproduced,stored in a retrieval system, or transmitted, in anyform or by any means, mechanical, electronic,photocopying, recording, or otherwise, withoutprior written permission of Apple Inc., with thefollowing exceptions: Any person is herebyauthorized to store documentation on a singlecomputer for personal use only and to printcopies of documentation for personal useprovided that the documentation containsApple’s copyright notice.

No licenses, express or implied, are granted withrespect to any of the technology described in thisdocument. Apple retains all intellectual propertyrights associated with the technology describedin this document. This document is intended toassist application developers to developapplications only for Apple-labeled computers.

Apple Inc.1 Infinite LoopCupertino, CA 95014408-996-1010

Apple and the Apple logo are trademarks ofApple Inc., registered in the U.S. and othercountries.

iAd is a service mark of Apple Inc., registered inthe U.S. and other countries.

iOS is a trademark or registered trademark ofCisco in the U.S. and other countries and is usedunder license.

Even though Apple has reviewed this document,APPLE MAKES NO WARRANTY OR REPRESENTATION,EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THISDOCUMENT, ITS QUALITY, ACCURACY,MERCHANTABILITY, OR FITNESS FOR A PARTICULARPURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED“AS IS,” AND YOU, THE READER, ARE ASSUMING THEENTIRE RISK AS TO ITS QUALITY AND ACCURACY.

IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIALDAMAGES RESULTING FROM ANY DEFECT ORINACCURACY IN THIS DOCUMENT, even if advised ofthe possibility of such damages.

THE WARRANTY AND REMEDIES SET FORTH ABOVEARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORALOR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer,agent, or employee is authorized to make anymodification, extension, or addition to this warranty.

Some states do not allow the exclusion or limitationof implied warranties or liability for incidental orconsequential damages, so the above limitation orexclusion may not apply to you. This warranty givesyou specific legal rights, and you may also have otherrights which vary from state to state.

UICollectionView Class Reference

Documents

Transcript of UICollectionView Class Reference