Mac Developer Library

Developer

AppKit Framework Reference NSCollectionViewItem Class Reference

Options
Deployment Target:

On This Page
Language:

NSCollectionViewItem

An NSCollectionViewItem object provides the visual representation for a single data element in a collection view. 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 Protocol Reference.

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 Class Reference.

Configuring an Item’s Views

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.

Registering Items

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

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 Class Reference. For information about how the data source object creates and configures items, see NSCollectionViewDataSource Protocol Reference.

Legacy Item Support

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 OS X.

  • An image view outlet that you can use to display images.

    Declaration

    Swift

    @IBOutlet unowned(unsafe) var imageView: NSImageView?

    Objective-C

    @property(assign) IBOutlet NSImageView *imageView

    Discussion

    This is a convenience property for accessing an image view in your item’s view hierarchy. Normally, you configure this property in Interface Builder by connecting it to one of your item’s image views.

    Availability

    Available in OS X v10.7 and later.

    See Also

    textField

  • A text field outlet that you can use to display a string.

    Declaration

    Swift

    @IBOutlet unowned(unsafe) var textField: NSTextField?

    Objective-C

    @property(assign) IBOutlet NSTextField *textField

    Discussion

    This is a convenience property for accessing a text field in your item’s view hierarchy. Normally, you configure this property in Interface Builder by connecting it to one of your item’s text fields.

    Availability

    Available in OS X v10.7 and later.

    See Also

    imageView

  • The collection view that owns the item. (read-only)

    Declaration

    Swift

    var collectionView: NSCollectionView { get }

    Objective-C

    @property(readonly) NSCollectionView *collectionView

    Discussion

    Use this property as a convenient way to access the collection view that owns the item.

    Availability

    Available in OS X v10.5 and later.

  • Dragging images for multi-image drag and drop support. (read-only)

    Declaration

    Swift

    var draggingImageComponents: [NSDraggingImageComponent] { get }

    Objective-C

    @property(readonly) NSArray <NSDraggingImageComponent *> *draggingImageComponents

    Discussion

    The component frames are relative to a coordinate system that has its origin at the bottom left, so you need to take into account the flipped state of your view when computing the component frames.

    This methods can be subclassed and overridden to provide a custom set of NSDraggingImageComponent objects to create the drag image.

    The default implementation will return an array of up to two NSDraggingImageComponent instances -- one for the imageView and another for the textField (if not nil).

    Availability

    Available in OS X v10.7 and later.

  • Constants indicating the type of highlight applied to an item.

    Declaration

    Swift

    enum NSCollectionViewItemHighlightState : Int { case None case ForSelection case ForDeselection case AsDropTarget }

    Objective-C

    typedef NSCollectionViewItemHighlightState : NSInteger { NSCollectionViewItemHighlightNone = 0, NSCollectionViewItemHighlightForSelection = 1, NSCollectionViewItemHighlightForDeselection = 2, NSCollectionViewItemHighlightAsDropTarget = 3, } NSCollectionViewItemHighlightState;

    Constants

    • None

      NSCollectionViewItemHighlightNone

      No highlight state.

      Available in OS X v10.11 and later.

    • ForSelection

      NSCollectionViewItemHighlightForSelection

      The selected highlight state. This type of highlight is applied when an item is selected. During interactive highlighting, this state is also applied to indicate that the item will become highlighted.

      Available in OS X v10.11 and later.

    • ForDeselection

      NSCollectionViewItemHighlightForDeselection

      The deselection highlight state. During interactive selection, this state is used to indicate that the item will become deselected when interactions end. After interactions end, the highlight state returns to NSCollectionViewItemHighlightNone.

      Available in OS X v10.11 and later.

    • AsDropTarget

      NSCollectionViewItemHighlightAsDropTarget

      The drop target highlight state. This type of highlight is applied when the item is the target of a drop operation on the collection view. After the drop operation completes, the highlight state returns to NSCollectionViewItemHighlightNone.

      Available in OS X v10.11 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.11 and later.