The visual representation for a single data element in a collection view.
SDK
- macOS 10.5+
Framework
- App
Kit
Declaration
@interface NSCollectionViewItem : NSView Controller
Overview
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
NSCollection
.View Data Source
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 reload
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 NSCollection
.
Configuring an Item’s Views
You configure the views of an item in one of two ways:
Subclass
NSCollection
and create any custom views programmatically.View Item Create a nib file containing a single top-level
NSCollection
object. Embed any custom views in the root view of the item.View Item
When creating the views programmatically, you typically override the item’s load
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 NSCollection
object if your item contains only an image or text field. For more complex item content, subclass NSCollection
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.
Registering Items
Before you can ask the collection view to create items, you must register those items using one of the following methods:
Use the
register
method when yourClass: for Item With Identifier: NSCollection
subclass handles the creation of its own views.View Item Use the
register
method when you store the item’s views in a nib file.Nib: for Item With Identifier:
Note
A single collection view can support multiple item types, each with its own distinct appearance, and you can mix and match item types in the same collection view if you want.
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 make
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 NSCollection
. For information about how the data source object creates and configures items, see NSCollection
.
Legacy Item Support
For apps built before OS X 10.11, you created a template item and assigned it to the item
property of your collection view. To create new instances of the item, you called the collection view’s new
method. For more information about how to support older collection view configurations, see Collection View Programming Guide for macOS.