The UIKit.UICollectionView is a container view that allows the application developer to lay out multiple items on the screen with more flexibility than is provided by a UIKit.UITableView. It is a subtype of UIKit.UIScrollView, so the layouts can span multiple pages. The layout used by the UIKit.UICollectionView is controlled by it's UICollectionView.CollectionViewLayout property.

A UIKit.UICollectionView must have a UIKit.UICollectionViewLayout. The most commonly-used UIKit.UICollectionViewLayout is UIKit.UICollectionViewFlowLayout, which lays out its content views either horizontally or vertically until it reaches the bounds and then wraps around.

These grid-like layouts are very flexible and customizable, but because UIKit.UICollectionView and UIKit.UICollectionViewLayout are independent, simply providing a different UIKit.UICollectionViewLayout can easily change the presentation style of the UIKit.UICollectionView. The application developer can create custom layouts to support whatever layout can be imagined.

The patterns for providing data to a UIKit.UICollectionView to create items and interact with those items follow the same delegation and data source patterns commonly used in iOS development.

Collection Views are more powerful than UIKit.UITableViews, which are limited to a single column, but are also more complex. UIKit.UITableView has certain built-in behaviors such as an editing mode, row animations, and easy-to-use headers and footers. If a UIKit.UITableView satisfies the application's UI requirements, the application developer should prefer to use the UIKit.UITableView.

A UIKit.UICollectionView user interface involves a collaboration of different objects with different concerns:

Concern	Description	Types
Content Management	The overall contents of the user interface	UIKit.UICollectionView, UIKit.UICollectionViewController
Layout	Position and layout attributes of various component views	UIKit.UICollectionViewLayout, UIKit.UICollectionViewLayoutAttributes, UIKit.UICollectionViewUpdateItem
Data Management	Data and event-management	UIKit.UICollectionViewDataSource, UIKit.UICollectionViewDelegate
Reusable views	Define component elements of the overall UIKit.UICollectionView	UIKit.UICollectionViewCell, UIKit.UICollectionReusableView

UICollectionView Basics

A UIKit.UICollectionView is made up of three different types of UIKit.UIViews:

The relationship between these three types of views is shown in the following image, based on the "Introduction to Collection Views" article. The cells are the orange-and-white rectangles and are laid out in a line. An instance of a supplementary view with a UIView.BackgroundColor of UIColor.Yellow separates sections, while a single decoration view provides a background for the entire UIKit.UICollectionView.

(Background image by NASA, http://visibleearth.nasa.gov/)

Understanding the reuse queue

The UIKit.UICollectionView is designed to work with large datasets. The two major attributes of this design are the "reuse queue" for component views and the UIKit.UICollectionViewDataSource interface. The reuse queue is a system-managed collection of component views that minimizes memory consumption by only allocating those views that are on-screen and a handful of "next visible" screens. The following illustration, based on a variation of the code from the "Introduction to Collection Views" sample, shows how efficient this reuse queue is: 204 views are visible but the reuse queue only consists of 217 instances of the AnimalCell subtype of UIKit.UICollectionViewCell. The dataset numbers in the thousands, but the number of actually allocated view components is minimal.

Not only does the reuse queue only have a minimal number of component views, it reuses component views rather than allocating and releasing off-screen views. This helps greatly with performance, but has important consequences for the application developer:

• Component view types (or nibs) are registered with the UIKit.UICollectionView, which is responsible for their memory.
• Component view instances are reused and have their values re-assigned. Application developers must be cautious about assumptions made about references to such values, which will change as the application user scrolls.
• The application developer must write the functions that (re-)assign these values: UICollectionViewDataSource.GetCell and, if supplementary views are desired, UICollectionViewDataSource.GetViewForSupplementaryElement.

The following code, from the "Introduction to Collection Views" sample, shows how component view types are registered and reassigned. Each component role type has an Foundation.NSString identifier (for instance, the type AnimalCell, which is used for the cell role, has the identifier "AnimalCell", the others are not shown). The methods UICollectionView.RegisterClassForCell and UICollectionView.RegisterClassForSupplementaryView register the classes for the cell and supplementary view roles, while the method UICollectionViewLayout.RegisterClassForDecorationView registers the decoration view with the UIKit.UICollectionViewLayout that is the UIKit.UICollectionView's' UICollectionView.CollectionViewLayout property.

It is very important that you provide a constructor that takes a RectangleF argument in any subclasses that you register with UICollectionView. This is required because the classes are actually allocated by the Objective-C runtime, and you must initialize them. The following example shows the expected constructor that you should provide:

public class AnimalCell : UICollectionViewCell
{
[Export ("initWithFrame:")]
  public AnimalCell (RectangleF frame) : base (frame) {}
}

The overridden methods UICollectionViewDataSource.GetCell and UICollectionViewSource.GetViewForSupplementaryElement show the re-assignment code. The Foundation.NSIndexPath that is passed as the indexPath argument contains the Foundation.NSIndexPath.Section and Foundation.NSIndexPath.Item integers that allow the application developer to locate a specific data item and appropriately assign the cell's relevant visual elements. (Application developers familiar with UIKit.UITableView will note that Foundation.NSIndexPath.Item and Foundation.NSIndexPath.Row are the same value.)

Since these methods, particularly the UICollectionViewDataSource.GetCell method, are called many times during scrolling, the application developer should avoid unnecessary processing during these calls.

public class AnimalCell : UICollectionViewCell
{
  private static NSString classId = new NSString ("AnimalCell");
  public static NSString ClassId { get { return classId; } }

[Export ("initWithFrame:")]
  public AnimalCell (RectangleF frame) : base (frame) {}

//..etc...
}


public class SimpleCollectionViewController : UICollectionViewController
{
  public override void ViewDidLoad ()
  {
    Base.ViewDidLoad ();

    var cv = CollectionView;

    cv.RegisterClassForCell (typeof(AnimalCell), AnimalCell.ClassId);
    cv.RegisterClassForSupplementaryView (typeof(HeaderView), UICollectionElementKindSection.Header, HeaderView.ClassId);
    cv.CollectionViewLayout.RegisterClassForDecorationView (typeof(DecorationView), DecorationView.ClassId);
  }

  public override UICollectionViewCell GetCell (UICollectionView collectionView, Foundation.NSIndexPath indexPath)
  {
    var animalCell = (AnimalCell)collectionView.DequeueReusableCell (AnimalCell.ClassId, indexPath);
    var animal = animals [indexPath.Section * (animals.Count / SectionCount) + indexPath.Item];

    animalCell.Image = animal.Image;

    return animalCell;
  }


  public override UICollectionReusableView GetViewForSupplementaryElement (UICollectionView collectionView, NSString elementKind, NSIndexPath indexPath)
  {
    var headerView = (HeaderView)collectionView.DequeueReusableSupplementaryView (elementKind, HeaderView.ClassId, indexPath);
    headerView.Text = "Supplementary View Section " + indexPath.Section.ToString ();
    return headerView;
  }
  //...etc...
}
        

Rather than registering program classes, application developers may choose to register nibs defined with XCode's Interface Builder. The relevant methods are shown in the following table.

Role	Class Registration Method	Nib Registration Method
Cell	UICollectionView.RegisterClassForCell	UICollectionView.RegisterNibForCell
Supplementary View	UICollectionView.RegisterClassForSupplementaryView	UICollectionView.RegisterNibForSupplementaryView
Decoration View	UICollectionViewLayout.RegisterClassForDecorationView	UICollectionViewLayout.RegisterNibForDecorationView

Handling events

To handle events associated with a UIKit.UICollectionView, the application developer may subtype UIKit.UICollectionViewDelegate and assign an instance to the UICollectionView.Delegate property.

UIKit.UICollectionView is a subtype of UIKit.UIScrollView and UIKit.UIScrollViewDelegate contains many of the same methods as UIKit.UIScrollViewDelegate but is not a subtype of that class.

Selecting and highlighting in a UIKit.UICollectionView follows this sequence:

Deselecting a UIKit.UICollectionViewCell follows a similar sequence: