NSCollectionViewItem

Item objects are view controllers, and you use their view hierarchies to display your content. The default implementation of this class supports the creation of a simple item that displays a single image or string. If the appearance or layout of your items is more sophisticated, you can subclass and configure the view hierarchy based on your needs.

Items are the most common types of elements displayed by a collection view, and every collection view must have at least one type of item. You use items to represent the main content of your collection view interface. For example, a photo browser app would use items to display individual photos. Remember that items are only the visual interpretation of your app’s underlying data. The actual data is always managed by your app and exposed to the collection view through the data source object, which uses the data to configure the items that are displayed.

The use of items with a collection view requires doing the following:

• Define the visual appearance of your items by specifying what views they contain and how those views are arranged.

• When your interface is first loaded, register your items with the collection view. (You must register your items before the collection view tries to display any content.)

• In your data source object, create and configure items when the collection view asks for them; see NSCollectionViewDataSource.

At runtime, items merely present the data they are given. Your app’s data structures are always the original source of content, and the item contains only a copy of that data to present to the user. When the underlying data associated with an item changes, the data source should invalidate the item by calling the reloadItemsAtIndexPaths: method of the collection view. Invalidating an item forces the collection view to dispose of it so that the collection view can create a new one with the updated content.

For information about how the collection view displays items to the user, see NSCollectionView.

You configure the views of an item in one of two ways:

• Subclass NSCollectionViewItem and create any custom views programmatically.

• Create a nib file containing a single top-level NSCollectionViewItem object. Embed any custom views in the root view of the item.

When creating the views programmatically, you typically override the item’s loadView method as you would for any view controller. In your implementation, create the views and add them as subviews to the view controller’s root view. Add accessor properties to your subclass so that you can access the views later and configure them.

When using a nib file, you can use a generic NSCollectionViewItem object if your item contains only an image or text field. For more complex item content, subclass NSCollectionViewItem and add outlets for any views you need to access later. In Interface Builder, connect your outlets to the views you add to the nib file.

Before you can ask the collection view to create items, you must register those items using one of the following methods:

• Use the registerClass:forItemWithIdentifier: method when your NSCollectionViewItem subclass handles the creation of its own views.

• Use the registerNib:forItemWithIdentifier: method when you store the item’s views in a nib file.

You must register at least one item type before trying to display content from your collection view. The collection view’s data source uses the makeItemWithIdentifier:forIndexPath: method to fetch an empty item for configuration. During the initial configuration of the collection view, that method creates all items using the registered classes and nib files you provided. Later on, the method may return a recycled item that can be repurposed with new data.

For more information about how how to register items, see NSCollectionView. For information about how the data source object creates and configures items, see NSCollectionViewDataSource.

For apps built before OS X 10.11, you created a template item and assigned it to the itemPrototype property of your collection view. To create new instances of the item, you called the collection view’s newItemForRepresentedObject: method. For more information about how to support older collection view configurations, see Collection View Programming Guide for macOS.