Mac Developer Library

Developer

AppKit Framework Reference NSCollectionView Class Reference

Options
Deployment Target:

On This Page
Language:

NSCollectionView

An NSCollectionView object displays an ordered collection of data items using a customizable layout. The simplest type of collection view displays its items in a grid, but you can define layouts to arrange items however you like. For example, you might create a layout where items are arranged in a circle. You can also change layouts dynamically at runtime whenever you need to present items differently.

You can add collection views to your interface using Interface Builder or create them programmatically in your view controller or window controller code. It is recommended that you configure your collection view with a data source object, which is an object that conforms to the NSCollectionViewDataSource protocol. Data sources support multiple sections and the modern layout architecture and are the preferred way for specifying your data.

In addition to displaying items, collection views support the display of supplementary and decoration views. Support for supplementary and decoration views is defined by the current layout object, but both types of views add to the visual presentation of your content. Supplementary views are associated with a specific section and can be used to create header and footer views for a related group of items. Decoration views are purely visual adornments and can be used to implement dynamic backgrounds or other types of configurable visual content.

The layout of a collection view can be changed dynamically by assigning a new layout object to the collectionViewLayout property. Changing the layout object updates the appearance of the collection view without animating the changes.

The Objects of a Collection View Interface

An NSCollectionView object itself is a facilitator, taking information from disparate sources and merging them together to create an overall interface:

  • The data source object provides both the data and the views used to display that data. You define the data source object by implementing the methods of the NSCollectionViewDataSource protocol in one of your app’s objects.

  • The visual representation of items is provided by the NSCollectionViewItem class. Item objects are view controllers and you use their views to display your app’s data. The data source creates items on demand and returns them to the collection view for display.

  • The collection view delegate makes decisions about behaviors. The delegate also coordinates the dragging and dropping of items. You define the delegate by implementing the methods of the NSCollectionViewDelegate protocol in one of your app’s objects.

  • The layout object specifies the position and appearance of items onscreen. AppKit defines layout objects that you can use as-is, but you can also define custom layouts by subclassing NSCollectionViewLayout.

Figure 1 illustrates how the collection view works with its other objects to create its final appearance. The collection view obtains the views for items and supplementary views from its data source, which creates the views and fills them with data. The layout object provides the layout attributes needed to position those items and supplementary views onscreen. The collection view merges the two sets of information to create the final appearance that the user sees onscreen.

Figure 1Merging content and layout to create the final appearance image: ../Art/cv_objects_2x.png

There are other helper classes and protocols that you can use to customize the layout behavior and other aspects of the collection view interface. For example, when using a flow layout object (NSCollectionViewFlowLayout), you can modify the flow layout’s behavior using the methods of the NSCollectionViewDelegateFlowLayout protocol. When implementing a custom layout, you might also work with NSCollectionViewUpdateItem and NSCollectionViewLayoutInvalidationContext objects, which help the layout object manage updates.

Managing the Collection View’s Content

Data for the collection view is managed by the data source object—that is an object that adopts the methods of the NSCollectionViewDataSource protocol. You are responsible for defining the data source used by your collection view. The data source provides information about the number of sections and items in the collection view and it provides the visual representation of that data. Every data source object is required to implement the following methods:

The NSCollectionViewItem class defines the visual appearance of items in the collection view. Your data source object vends items from its collectionView:itemForRepresentedObjectAtIndexPath: method, creating and configuring the item in one step. Each item is essentially a snapshot of the data it represents. Items are often short-lived because they can be recycled by the collection view and reused to display new data. As a result, never store references to items in your app.

Supplementary views are another way to display data in your interface. Each layout object defines the supplementary views it supports, and different layouts can define supplementary views for different purposes. For example, an NSCollectionViewFlowLayout object lets you add header and footer views to each section. Your data source must know enough about the layout to know which supplementary views are supported by the layout object and how those views are displayed. The data source can then provide supplementary views when asked for them.

When your content changes in a way that requires you to update what the collection view displays, call the reloadData, reloadSections:, or reloadItemsAtIndexPaths: method to perform that update. These methods cause the collection view to discard the views currently being used to display your content and ask for new ones. Never try to modify the views associated with your items directly. The collection view does not maintain views for all items, only those that are currently being displayed. Reloading the items ensures that the views are updated correctly.

For more information on defining your data source object, see NSCollectionViewDataSource Protocol Reference.

Inserting, Deleting, and Moving Content

The collection view includes methods for inserting, deleting, and moving items and sections. All of these methods affect only what the collection view displays onscreen; they do not change the data in the associated data source object. As a result, when updating your collection view’s content, always do the following:

  1. Update the internal structures of your data source object first.

  2. Call the NSCollectionView methods to insert, delete, or move items and sections.

When you call methods like insertItemsAtIndexPaths: or deleteSections:, the collection view fetches any new data from your data source object and then updates the layout. When inserting, moving, or deleting items, the collection view updates the layout for all affected items, which might include items not directly affected by the operation. For example, inserting one item might require adjusting the onscreen position of many other items. When the layout attributes for any visible items changes, the collection view animates those changes into place automatically.

The layout object determines how inserted and deleted items are animated into position. Because newly inserted items are not onscreen initially, the layout object provides the initial layout attributes for those items. Similarly, the layout object provides the final layout attributes for any items that are being deleted. For example, the layout object might specify final layout attributes that are offscreen so that a deleted item animates out of the visible rectangle.

Because individual methods for inserting, deleting, and moving content animate their changes right away, you must use the performBatchUpdates:completionHandler: method when you want to animate multiple changes together. The performBatchUpdates:completionHandler: method takes a block containing all of the insert, delete, move, and reload method calls you need to update the collection view. All of those operations are captured and performed as a single animated sequence.

Interface Builder Configuration Options

Xcode lets you configure information about your collection view in your storyboard and nib files. Table 1 lists the basic collection view attributes. Additional attributes are available based on the selected value for the Layout attribute.

Table 1Collection view basic attributes

Attribute

Description

Layout

The type of layout object to use. The Flow, Grid, and Custom options are preferred because they enable the modern collection view behavior.

Colors

The option to specify alternating colors for the collection view’s background.

Primary

The primary color to use with the collection view.

Secondary

The secondary color to use with the collection view.

Selection

The options for selecting items. Use these options to enable or disable selections altogether and to specify whether the collection view supports the selection of multiple items or no items.

Table 2 lists the attributes you can configure when you set the Layout attribute to Flow.

Table 2Flow layout attributes

Attribute

Description

Scroll Direction

The scrolling direction for content. The flow layout allows scrolling in one dimension only. The other dimension is pinned to the size of the collection view itself. For example, when vertical scrolling is selected, the width of the content area is set to the width of the collection view.

Item Size

The default size of newly created items. The collection view’s delegate can override the default size values and specify different values for each item.

Header Size

The default size of header views. The layout object uses only the dimension that does not match the current scrolling direction. For example, for a vertically scrolling collection view, the layout sets only the width of the footer to the specified value. The collection view’s delegate can override the default size values.

Footer Size

The default size of footer views. The layout object uses only the dimension that does not match the current scrolling direction. For example, for a vertically scrolling collection view, the layout sets only the width of the footer to the specified value. The collection view’s delegate can override the default size values using methods of the NSCollectionViewDelegateFlowLayout protocol.

Min Spacing

The minimum spacing between items and lines. The item spacing is the minimum amount of space for items in the same row or column (depending on the scroll direction). The line spacing is the minimum space between rows or columns. The actual amount of space used between items and lines may be greater than the minimum.

Section Inset

The margins imposed on each section. Margins set the distance between the header view and the items, between the sides of the collection view and the items, and between the items and the footer view.

Table 3 lists the attributes you can configure when you set the Layout attribute to Grid.

Table 3Grid layout attributes

Attribute

Description

Dimensions

The number of rows and columns to display. Use these attributes to configure the grid dimensions.

Min Item Size

The minimum width and height for items.

Max Item Size

The maximum width and height for items.

Table 4 lists the attributes you can configure when you set the Layout attribute to Custom.

Table 4Custom layout attributes

Attribute

Description

Class

The name of the NSCollectionViewLayout subclass you want to use.

Module

The Swift module containing the class. Leave this attribute blank for classes in the current module.

Table 5 lists the attributes you can configure when you set the Layout attribute to Content Array (Legacy).

Table 5Content Array (Legacy) attributes

Attribute

Description

Dimensions

The number of rows and columns to display. Use these attributes to configure the grid dimensions.

Legacy Collection View Support

Prior to OS X 10.11, the collection view always displayed its contents in a grid structure that could not be changed. The data for the collection view was stored in the content property, which was often populated with data using bindings. You specified the visual appearance for the collection view’s data by creating an NSCollectionViewItem object and assigning it to the itemPrototype property. That item object acted as a template and was used to create all of the items in the collection view.

You are encouraged to use the modern collection view architecture when configuring collection views in OS X 10.11 and later. Use the legacy architecture only for apps that must run in earlier versions of OS X.

For more information about how to configure a collection view using the legacy architecture, see Collection View Programming Guide for OS X.

  • An object that provides data for the collection view.

    Declaration

    Swift

    weak var dataSource: NSCollectionViewDataSource?

    Objective-C

    @property(weak) id< NSCollectionViewDataSource > dataSource

    Discussion

    The data source object manages the data in the collection view. Use this object to specify how many items are in the collection view and to create the visual representation of those items. The object you specify must adopt the NSCollectionViewDataSource protocol.

    To specify the data for your collection view, assign a value to this property or to the content property, but not both. If you specify a value for this property, the collection view ignores the content property and the content binding.

    Availability

    Available in OS X v10.11 and later.

  • An array that provides data for the collection view.

    Declaration

    Swift

    var content: [AnyObject]

    Objective-C

    @property(copy) NSArray <id> *content

    Discussion

    The content object manages the data in the collection view. Use this object to specify an array of items directly. This property is observable using key-value observing. The collection view also exposes a content binding value so that you can specify the array of items using an ArrayController object in Interface Builder.

    To specify the data for your collection view, assign a value to this property or to the dataSource property, but not both. If you specify a value for the dataSource property, the collection view ignores the value in this property.

    Availability

    Available in OS X v10.5 and later.

  • The collection view’s delegate object.

    Declaration

    Swift

    unowned(unsafe) var delegate: NSCollectionViewDelegate?

    Objective-C

    @property(assign) id< NSCollectionViewDelegate > delegate

    Discussion

    Use the delegate object to manage the selection and highlighting of items, track the addition and removal of items, and manage drag and drop operations. The object you assign to this property must conform to the NSCollectionViewDelegate Protocol protocol. The default value of this property is nil.

    Availability

    Available in OS X v10.6 and later.

  • The background view placed behind all items and supplementary views.

    Declaration

    Swift

    var backgroundView: NSView?

    Objective-C

    @property(strong) NSView *backgroundView

    Discussion

    The view you assign to this property is positioned underneath all other content and sized automatically to match the enclosing clip view’s frame. The view itself does not scroll with the rest of the collection view content. The view’s layer redraw policy is also changed to NSViewLayerContentsRedrawNever.

    When a background view is specified, the collection view does not draw any background colors.

    Availability

    Available in OS X v10.11 and later.

    See Also

    backgroundColors

  • An array containing the collection view’s background colors.

    Declaration

    Swift

    var backgroundColors: [NSColor]!

    Objective-C

    @property(copy) NSArray <NSColor *> *backgroundColors

    Discussion

    This property contains an array of NSColor objects, representing the colors to use when drawing the background grid. Specifying an empty array or nil causes the collection view to use the default colors returned by the controlAlternatingRowBackgroundColors method.

    When a background view is specified for the collection view, the colors in this property are ignored.

    Availability

    Available in OS X v10.5 and later.

    See Also

    backgroundView

  • Creates or returns a reusable item object of the specified type.

    Declaration

    Swift

    func makeItemWithIdentifier(_ identifier: String, forIndexPath indexPath: NSIndexPath) -> NSCollectionViewItem

    Objective-C

    - (__kindofNSCollectionViewItem *)makeItemWithIdentifier:(NSString *)identifier forIndexPath:(NSIndexPath *)indexPath

    Parameters

    identifier

    The reuse identifier for the specified item. This is the identifier you specified when registering the item. This parameter must not be nil.

    indexPath

    The index path specifying the location of the item. The data source object receives this information in its collectionView:itemForRepresentedObjectAtIndexPath: method and you should just pass it along.

    Return Value

    A valid NSCollectionViewItem object.

    Discussion

    This method looks for a recycled item object of the specified type and returns it if one exists. If one does not exist, it creates it using one of the following techniques:

    Availability

    Available in OS X v10.11 and later.

  • Creates or returns a reusable supplementary view of the specified type.

    Declaration

    Swift

    func makeSupplementaryViewOfKind(_ elementKind: String, withIdentifier identifier: String, forIndexPath indexPath: NSIndexPath) -> NSView

    Objective-C

    - (__kindofNSView *)makeSupplementaryViewOfKind:(NSString *)elementKind withIdentifier:(NSString *)identifier forIndexPath:(NSIndexPath *)indexPath

    Parameters

    elementKind

    The kind of supplementary view to create. This value is defined by the layout object. This parameter must not be an empty string or nil.

    identifier

    The reuse identifier for the specified item. This is the identifier you specified when registering the supplementary view. This parameter must not be nil.

    indexPath

    The index path specifying the location of the supplementary view. The data source object receives this information in its collectionView:viewForSupplementaryElementOfKind:atIndexPath: method and you should just pass it along.

    Return Value

    A view that adopts the NSCollectionViewElement protocol.

    Discussion

    This method looks for a recycled supplementary view of the specified type and returns it if one exists. If one does not exist, it creates it using one of the following techniques:

    Availability

    Available in OS X v10.11 and later.

  • Registers a class to use when creating new items in the collection view.

    Declaration

    Swift

    func registerClass(_ itemClass: AnyClass?, forItemWithIdentifier identifier: String)

    Objective-C

    - (void)registerClass:(Class)itemClass forItemWithIdentifier:(NSString *)identifier

    Parameters

    itemClass

    A class to use for creating items. The class must be descended from NSCollectionViewItem. Specify nil to unregister a previously registered class or nib file.

    identifier

    The string that identifies the type of item. You use this string later when requesting new items and it must be unique among the other registered item and view classes of this collection view. This parameter must not be an empty string or nil.

    Discussion

    Use this method to register the classes that represent items in your collection view. When you request an item using the makeItemWithIdentifier:forIndexPath: method, the collection view recycles an existing item with the same identifier or creates a new one by instantiating your class and calling the init method of the resulting object.

    Because items are recycled to improve performance, it is recommended that your custom classes conform to the NSCollectionViewElement protocol. You can use the methods of that protocol to prepare your classes for reuse.

    Typically, you register your items when initializing your collection view interface. Although you can register new items at any time, you must not call the makeItemWithIdentifier:forIndexPath: method until after you register the corresponding item.

    Availability

    Available in OS X v10.11 and later.

  • Registers a class to use when creating new supplementary views in the collection view.

    Declaration

    Swift

    func registerClass(_ viewClass: AnyClass?, forSupplementaryViewOfKind kind: String, withIdentifier identifier: String)

    Objective-C

    - (void)registerClass:(Class)viewClass forSupplementaryViewOfKind:(NSString *)kind withIdentifier:(NSString *)identifier

    Parameters

    viewClass

    The view class to use for the supplementary view. This class must be descended from NSView and must conform to the NSCollectionViewElement protocol. Specify nil to unregister a previously registered class or nib file.

    kind

    The kind of the supplementary view. Layout objects define the kinds of supplementary views they support and are responsible for providing appropriate strings that you can pass for this parameter. This parameter must not be an empty string or nil.

    identifier

    The string that identifies the type of supplementary view. You use this string later when requesting new views and it must be unique among the other registered item and view classes of this collection view. This parameter must not be an empty string or nil.

    Discussion

    Use this method to register the classes that represent the supplementary views in your collection view. When you request a view using the makeSupplementaryViewOfKind:withIdentifier:forIndexPath: method, the collection view recycles an existing view with the same identifier and kind values or creates a new one by instantiating your class and calling the initWithFrame: method of the resulting object.

    The layout object is responsible for defining the kind of supplementary views it supports and how those views are used. For example, the flow layout (NSCollectionViewFlowLayout class) lets you specify supplementary views to act as headers and footers for each section.

    Typically, you register your supplementary views when initializing your collection view interface. Although you can register new views at any time, you must not call the makeSupplementaryViewOfKind:withIdentifier:forIndexPath: method until after you register the corresponding view.

    Availability

    Available in OS X v10.11 and later.

  • Registers a nib file to use when creating items in the collection view.

    Declaration

    Swift

    func registerNib(_ nib: NSNib?, forItemWithIdentifier identifier: String)

    Objective-C

    - (void)registerNib:(NSNib *)nib forItemWithIdentifier:(NSString *)identifier

    Parameters

    nib

    The nib object containing the item’s definition. The nib file must contain exactly one NSCollectionViewItem object at the top level. You may use a custom subclass when configuring the object in the nib file. Specify nil to unregister a previously registered class or nib file.

    identifier

    The string that identifies the type of item. You use this string later when requesting new items and it must be unique among the other registered item and view classes of this collection view. This parameter must not be an empty string or nil.

    Discussion

    Use this method to register nib files containing prototype items to use in your collection view. When you request an item using the makeItemWithIdentifier:forIndexPath: method, the collection view recycles an existing item with the same identifier or creates a new one by loading the contents of your nib file.

    Because items are recycled to improve performance, it is recommended that your custom item classes conform to the NSCollectionViewElement protocol. You can use the methods of that protocol to prepare your classes for reuse.

    Typically, you register your items when initializing your collection view interface. Although you can register new items at any time, you must not call the makeItemWithIdentifier:forIndexPath: method until after you register the corresponding item.

    Availability

    Available in OS X v10.11 and later.

  • Registers a nib file to use when creating supplementary views in the collection view.

    Declaration

    Swift

    func registerNib(_ nib: NSNib?, forSupplementaryViewOfKind kind: String, withIdentifier identifier: String)

    Objective-C

    - (void)registerNib:(NSNib *)nib forSupplementaryViewOfKind:(NSString *)kind withIdentifier:(NSString *)identifier

    Parameters

    nib

    The nib object containing the supplementary view’s definition. The nib file must contain exactly one NSView object at the top level and that view must conform to the NSCollectionViewElement protocol. Specify nil to unregister a previously registered class or nib file.

    kind

    The kind of the supplementary view. Layout objects define the kinds of supplementary views they support and are responsible for providing appropriate strings that you can pass for this parameter. This parameter must not be an empty string or nil.

    identifier

    The string that identifies the type of supplementary view. You use this string later when requesting new views and it must be unique among the other registered item and view classes of this collection view. This parameter must not be an empty string or nil.

    Discussion

    Use this method to register nib files containing prototype supplementary views in your collection view. When you request a view using the makeSupplementaryViewOfKind:withIdentifier:forIndexPath: method, the collection view recycles an existing view with the same identifier and kind values or creates a new one by loading the contents of your nib file.

    The layout object is responsible for defining the kind of supplementary views it supports and how those views are used. For example, the flow layout (NSCollectionViewFlowLayout class) lets you specify supplementary views to act as headers and footers for each section.

    Typically, you register your supplementary views when initializing your collection view interface. Although you can register new views at any time, you must not call the makeSupplementaryViewOfKind:withIdentifier:forIndexPath: method until after you register the corresponding view.

    Availability

    Available in OS X v10.11 and later.

  • The layout object used to organize the collection view’s content.

    Declaration

    Swift

    var collectionViewLayout: NSCollectionViewLayout?

    Objective-C

    @property(strong) NSCollectionViewLayout *collectionViewLayout

    Discussion

    Typically, you specify the layout object at design time in Interface Builder. The layout object works with your data source object to generate the needed items and views to display. In OS X 10.11 and later, using a data source object is recommended, but you may specify nil for this property if your collection view does not use a data source object. The collection view uses the NSCollectionViewGridLayout object by default.

    Assigning a new value to this property changes the layout object and causes the collection view to update its contents immediately and without animations. If you want to animate a layout change, use an animator object to set the layout object as follows:

    1. [[collectionView animator] setCollectionViewLayout:myLayout];

    You can use the completion handler of the associated NSAnimationContext object to perform additional tasks when the animations finish.

    Availability

    Available in OS X v10.11 and later.

  • Reloads all of the data for the collection view.

    Declaration

    Swift

    func reloadData()

    Objective-C

    - (void)reloadData

    Discussion

    Call this method when the data in your data source object changes or when you want to force the collection view to update its contents. When you call this method, the collection view discards any currently visible items and views and redisplays them. For efficiency, the collection view displays only the items and supplementary views that are visible after reloading the data. If the collection view’s size changes as a result of reloading the data, the collection view adjusts its scrolling offsets accordingly.

    Do not call this method in the middle of animation blocks where items are being inserted or deleted. The methods used to insert and delete items automatically update the collection view’s contents.

    Availability

    Available in OS X v10.11 and later.

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

    Declaration

    Swift

    func reloadSections(_ sections: NSIndexSet)

    Objective-C

    - (void)reloadSections:(NSIndexSet *)sections

    Parameters

    sections

    The indexes of the sections that you want to reload. Specifying nil for this parameter raises an exception.

    Discussion

    Call this method when the data for the specified sections changes or when you want to force the appearance of those sections to be updated. When you call this method, the collection view discards visible elements in the section along with any cached attributes for those elements. For efficiency, it then asks the layout object to provide fresh attributes for only the visible items and views and requests new views for those elements.

    Do not call this method in the middle of animation blocks where items are being inserted or deleted. The methods used to insert and delete items automatically update the collection view’s contents.

    Availability

    Available in OS X v10.11 and later.

  • Reloads only the specified items.

    Declaration

    Swift

    func reloadItemsAtIndexPaths(_ indexPaths: Set<NSIndexPath>)

    Objective-C

    - (void)reloadItemsAtIndexPaths:(NSSet<NSIndexPath *> *)indexPaths

    Parameters

    indexPaths

    The index paths of the specific items that you want to reload. Specifying nil for this parameter raises an exception.

    Discussion

    Call this method to update specific items in your collection view. You call this method when the underlying data for those items changes and you want to update the visual appearance of those items. When you call this method, the collection view discards the specified items and asks your data source to provide new ones. For efficiency, the collection view requests only the items that are visible.

    Availability

    Available in OS X v10.11 and later.

  • The number of sections in the collection view. (read-only)

    Declaration

    Swift

    var numberOfSections: Int { get }

    Objective-C

    @property(readonly) NSInteger numberOfSections

    Discussion

    This property contains the number of sections reported by the data source object. If the collection view does not use a data source object, the value in this property is 1.

    Availability

    Available in OS X v10.11 and later.

  • Returns the number of items in the specified section.

    Declaration

    Swift

    func numberOfItemsInSection(_ section: Int) -> Int

    Objective-C

    - (NSInteger)numberOfItemsInSection:(NSInteger)section

    Parameters

    section

    The index of the section whose item count you want. This index is 0-based.

    Return Value

    The number of items in the section.

    Discussion

    Use this method to get the number of items currently displayed by the collection view for the specified section. Do not call the methods of the data source to get this information.

    Availability

    Available in OS X v10.11 and later.

  • Inserts new items into the collection view at the specified locations.

    Declaration

    Swift

    func insertItemsAtIndexPaths(_ indexPaths: Set<NSIndexPath>)

    Objective-C

    - (void)insertItemsAtIndexPaths:(NSSet<NSIndexPath *> *)indexPaths

    Parameters

    indexPaths

    A set of NSIndexPath objects, each of which includes a section and item index corresponding to the insertion point of a single item. Specifying nil for this parameter raises an exception.

    Discussion

    After adding new items to your data source object, use this method to synchronize those changes with the collection view. Calling this method lets the collection view know that it must update its internal data structures and possibly update its visual appearance. In response, the collection view asks the layout object for information about the new objects. If the layout object indicates that the new items should appear onscreen, the collection view asks the data source to provide the appropriate content, animating that content into position as needed.

    When inserting or deleting multiple sections and items, you can animate all of your changes at once using the performBatchUpdates:completionHandler: method.

    Availability

    Available in OS X v10.11 and later.

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

    Declaration

    Swift

    func moveItemAtIndexPath(_ indexPath: NSIndexPath, toIndexPath newIndexPath: NSIndexPath)

    Objective-C

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

    Parameters

    indexPath

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

    newIndexPath

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

    Discussion

    Use rearranging items in your data source object, use this method to synchronize those changes with the collection view. Calling this method lets the collection view know that it must update its internal data structures and possibly update its visual appearance. You can move the item to a different section or to a new location in the same section. The collection view updates the layout as needed to account for the move, animating cells into position in response.

    When inserting or deleting multiple sections and items, you can animate all of your changes at once using the performBatchUpdates:completionHandler: method.

    Availability

    Available in OS X v10.11 and later.

  • Deletes the items at the specified index paths.

    Declaration

    Swift

    func deleteItemsAtIndexPaths(_ indexPaths: Set<NSIndexPath>)

    Objective-C

    - (void)deleteItemsAtIndexPaths:(NSSet<NSIndexPath *> *)indexPaths

    Parameters

    indexPaths

    A set of NSIndexPath objects, each of which includes a section and item index corresponding to the insertion point of a single item. Specifying nil for this parameter raises an exception.

    Discussion

    After removing items from your data source object, use this method to synchronize those changes with the collection view. Calling this method lets the collection view know that it must update its internal data structures and possibly update its visual appearance. In response, the collection view asks the layout object to update the positions of the remaining objects. If the layout object indicates that there are changes to the visible items, the collection view animates the affected items into place.

    When inserting or deleting multiple sections and items, you can animate all of your changes at once using the performBatchUpdates:completionHandler: method.

    Availability

    Available in OS X v10.11 and later.

  • Inserts new sections at the specified indexes.

    Declaration

    Swift

    func insertSections(_ sections: NSIndexSet)

    Objective-C

    - (void)insertSections:(NSIndexSet *)sections

    Parameters

    sections

    An index set containing the indexes at which you want to insert new sections. This parameter must not be nil.

    Discussion

    This method tells the collection view to insert the specified sections and update itself. Always update your data source object before calling this method. Calling this method kicks off an update (and possible animations) to add the new sections. Specifically, the collection view asks the layout object for any updated layout attributes related to the new sections or any existing sections. If the layout attributes of any visible items changed, those changes are animated into place.

    When inserting or deleting multiple sections and items, you can animate all of your changes at once using the performBatchUpdates:completionHandler: method.

    Availability

    Available in OS X v10.11 and later.

  • Moves a section from its current location to a new location.

    Declaration

    Swift

    func moveSection(_ section: Int, toSection newSection: Int)

    Objective-C

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

    Parameters

    section

    The index of the section that you want to move.

    newSection

    The new index at which to insert the section.

    Discussion

    Use this method to reorganize sections and their contained items. Always update your data source object before calling this method. Calling this method kicks off an update (and possible animations) to move the specified section to its new location. Specifically, the collection view asks the layout object for any updated layout attributes related to the new sections or any existing sections. If the layout attributes of any visible items changed, those changes are animated into place.

    When inserting or deleting multiple sections and items, you can animate all of your changes at once using the performBatchUpdates:completionHandler: method.

    Availability

    Available in OS X v10.11 and later.

  • Deletes the specified sections and their contained items.

    Declaration

    Swift

    func deleteSections(_ sections: NSIndexSet)

    Objective-C

    - (void)deleteSections:(NSIndexSet *)sections

    Parameters

    sections

    An index set containing the indexes of the sections that you want to delete. This parameter must not be nil.

    Discussion

    Use this method to delete entire sections and their contained items. Always update your data source object before calling this method. Calling this method kicks off an update (and possible animations) to delete the specified sections. Specifically, the collection view asks the layout object for the final layout attributes for any deleted sections and may also ask for updated layout attributes for any remaining sections. If the layout attributes of any visible items changed, those changes are animated into place.

    When inserting or deleting multiple sections and items, you can animate all of your changes at once using the performBatchUpdates:completionHandler: method.

    Availability

    Available in OS X v10.11 and later.

  • A Boolean value that indicates whether the user may select items in the collection view.

    Declaration

    Swift

    var selectable: Bool

    Objective-C

    @property(getter=isSelectable) BOOL selectable

    Discussion

    The value of this property is YEStrue when the collection view allows the user to select items, or NOfalse when it does not. You can set selections programmatically regardless of this setting.

    The default value of this property is NOfalse. Changing the value from YEStrue to NOfalse removes the current selection if there is one.

    Availability

    Available in OS X v10.5 and later.

  • A Boolean value that indicates whether the user may select more than one item in the collection view.

    Declaration

    Swift

    var allowsMultipleSelection: Bool

    Objective-C

    @property BOOL allowsMultipleSelection

    Discussion

    The value of this property is YEStrue if the collection view supports the selection of more than one item at a time. The default value of this property is NOfalse. Changing the value from YEStrue to NOfalse reduces the current selection to the first item in the selected group.

    Availability

    Available in OS X v10.5 and later.

  • A Boolean value indicating whether the collection view may have no selected items.

    Declaration

    Swift

    var allowsEmptySelection: Bool

    Objective-C

    @property BOOL allowsEmptySelection

    Discussion

    The default value of this property is YEStrue, which allows the collection view to have no selected items. Setting this property to NOfalse causes the collection view to always leave at least one item selected.

    Availability

    Available in OS X v10.11 and later.

  • The set of index paths representing the currently selected items.

    Declaration

    Swift

    var selectionIndexPaths: Set<NSIndexPath>

    Objective-C

    @property(copy) NSSet <NSIndexPath *> *selectionIndexPaths

    Discussion

    This property reflects the index paths of the currently selected items, where each index path contains a section number and an index number for the item in that section. This property is updated automatically when the user selects items interactively. You can also change the selection programmatically by assigning a new value to this property. To animate changes to the selection, call this method on the collection view’s animator proxy object instead.

    It is a programmer error to specify an index path that does not refer to a valid item in the data source. If you specify an invalid index path, this method raises an exception.

    This property is key-value observable. Other methods that modify the selection automatically update this property.

    Availability

    Available in OS X v10.11 and later.

  • Selects all items in the collection view, if doing so is possible.

    Declaration

    Swift

    @IBAction func selectAll(_ sender: AnyObject?)

    Objective-C

    - (IBAction)selectAll:(id)sender

    Parameters

    sender

    The object that requested the action. You may specify nil for this property.

    Discussion

    This method works only when the selectable and allowsMultipleSelection properties are both YEStrue. If either property is set to NOfalse, this method quietly does nothing and any connected menu item is disabled.

    This method consults the delegate object regarding the selection. Specifically, it calls the delegate’s collectionView:shouldSelectItemsAtIndexPaths: method to see if the items should be selected. For any items that are selected, it calls the collectionView:didSelectItemsAtIndexPaths: method.

    Availability

    Available in OS X v10.11 and later.

  • Deselects all items in the collection view.

    Declaration

    Swift

    @IBAction func deselectAll(_ sender: AnyObject?)

    Objective-C

    - (IBAction)deselectAll:(id)sender

    Parameters

    sender

    The object that requested the action. You may specify nil for this property.

    Discussion

    This method works only when the selectable and allowsEmptySelection properties are both true YEStrue. If either property is set to NOfalse, this method quietly does nothing and any connected menu item is disabled.

    This method consults the delegate object regarding the selection. Specifically, it calls the delegate’s collectionView:shouldDeselectItemsAtIndexPaths: method to see if the items should be selected. For any items that are selected, it calls the collectionView:didDeselectItemsAtIndexPaths: method.

    Availability

    Available in OS X v10.11 and later.

  • Adds the specified items to the current selection and optionally scrolls the items into position.

    Declaration

    Swift

    func selectItemsAtIndexPaths(_ indexPaths: Set<NSIndexPath>, scrollPosition scrollPosition: NSCollectionViewScrollPosition)

    Objective-C

    - (void)selectItemsAtIndexPaths:(NSSet<NSIndexPath *> *)indexPaths scrollPosition:(NSCollectionViewScrollPosition)scrollPosition

    Parameters

    indexPaths

    The index paths of the items you want to select.

    scrollPosition

    The options for scrolling the newly selected items into view. You may combine one vertical and one horizontal scrolling option when calling this method. Specifying more than one option for either the vertical or horizontal directions raises an exception.

    Discussion

    Use this method to extend the current selection. If you want to animate the selection of the new items, call this method on the collection view’s animator proxy object instead. This method does not call any methods of the delegate object when making the selection.

    Availability

    Available in OS X v10.11 and later.

  • Removes the specified items from the current selection.

    Declaration

    Swift

    func deselectItemsAtIndexPaths(_ indexPaths: Set<NSIndexPath>)

    Objective-C

    - (void)deselectItemsAtIndexPaths:(NSSet<NSIndexPath *> *)indexPaths

    Parameters

    indexPaths

    The index paths of the items you want to deselect.

    Discussion

    Use this method to reduce the current selection. If you want to animate the deselection of the new items, call this method on the collection view’s animator proxy object instead. This method does not call any methods of the delegate object when making the selection.

    Availability

    Available in OS X v10.11 and later.

  • Returns an array of the actively managed items in the collection view.

    Declaration

    Swift

    func visibleItems() -> [NSCollectionViewItem]

    Objective-C

    - (NSArray<NSCollectionViewItem *> *)visibleItems

    Return Value

    An array of NSCollectionViewItem objects. The returned array may be empty.

    Discussion

    The items returned by this method represent the ones that are active and currently being managed by the collection view. This array may contain items that are outside of the collection view’s actual visible rectangle. For example, it may contain items that were recently visible but have since been scrolled out of view. To test whether an item is actually visible, check to see if its frame rectangle intersects the visibleRect of the collection view.

    Availability

    Available in OS X v10.11 and later.

  • Returns the index paths of the currently active items.

    Declaration

    Swift

    func indexPathsForVisibleItems() -> Set<NSIndexPath>

    Objective-C

    - (NSSet<NSIndexPath *> *)indexPathsForVisibleItems

    Return Value

    The set of NSIndexPath objects corresponding to the currently visible items.

    Discussion

    The index paths returned by this method belong to items that are active and currently being managed by the collection view. As a result, the returned set may include index paths for items that are outside of the collection view’s actual visible rectangle. For example, it may contain index paths for items that were recently visible but have since been scrolled out of view. To test whether an item is visible, check to see if its frame rectangle intersects the visibleRect of the collection view.

    Availability

    Available in OS X v10.11 and later.

  • Returns an array of the actively managed supplementary views in the collection view.

    Declaration

    Swift

    func visibleSupplementaryViewsOfKind(_ elementKind: String) -> [NSView]

    Objective-C

    - (NSArray<NSView<NSCollectionViewElement> *> *)visibleSupplementaryViewsOfKind:(NSString *)elementKind

    Parameters

    elementKind

    The kind of the supplementary views you want returned. The layout object defines the kinds of supplementary views it supports. This parameter must not be nil.

    Return Value

    An array of view objects. The returned array may be empty.

    Discussion

    The views returned by this method represent the ones that are active and are currently being managed by the collection view. The array may contain supplementary views that are outside of the collection view’s actual visible rectangle. For example, it might contain views that were recently visible but have since been scrolled out of the visible rectangle. To test whether a view is actually visible, check to see if its frame rectangle intersects the visibleRect of the collection view.

    Availability

    Available in OS X v10.11 and later.

  • Returns the index paths of the currently active supplementary views.

    Declaration

    Swift

    func indexPathsForVisibleSupplementaryElementsOfKind(_ elementKind: String) -> Set<NSIndexPath>

    Objective-C

    - (NSSet<NSIndexPath *> *)indexPathsForVisibleSupplementaryElementsOfKind:(NSString *)elementKind

    Parameters

    elementKind

    The kind of the supplementary views you want returned. The layout object defines the kinds of supplementary views it supports. This parameter must not be nil.

    Return Value

    The set of NSIndexPath objects. The returned array may be empty.

    Discussion

    The index paths returned by this method correspond to supplementary views that are active and currently being managed by the collection view. The set may include index paths for views that are outside of the collection view’s actual visible rectangle. For example, it might contain index paths for views that were recently visible but have since been scrolled out of the visible rectangle. To test whether a view is actually visible, check to see if its frame rectangle intersects the visibleRect of the collection view.

    Availability

    Available in OS X v10.11 and later.

  • Returns the index path of the specified item.

    Declaration

    Swift

    func indexPathForItem(_ item: NSCollectionViewItem) -> NSIndexPath?

    Objective-C

    - (NSIndexPath *)indexPathForItem:(NSCollectionViewItem *)item

    Parameters

    item

    The item whose index path you want to know.

    Return Value

    The item’s index path or nil if the item is not in the collection view.

    Availability

    Available in OS X v10.11 and later.

  • Returns the index path of the item at the specified point.

    Declaration

    Swift

    func indexPathForItemAtPoint(_ point: NSPoint) -> NSIndexPath?

    Objective-C

    - (NSIndexPath *)indexPathForItemAtPoint:(NSPoint)point

    Parameters

    point

    The point in the collection view’s bounds that you want to test.

    Return Value

    The item at the specified point or nil if no item was found at that point.

    Discussion

    This method uses the available layout attributes to determine which item is at the specified point. If more than one item is at the point, this method returns only the top-most item. This method ignores the opacity of the item, so items that are fully transparent are still returned by this method. Hidden items are never returned.

    Availability

    Available in OS X v10.11 and later.

  • Returns the item associated with the specified index path.

    Declaration

    Swift

    func itemAtIndexPath(_ indexPath: NSIndexPath) -> NSCollectionViewItem?

    Objective-C

    - (NSCollectionViewItem *)itemAtIndexPath:(NSIndexPath *)indexPath

    Parameters

    indexPath

    The index path whose item you want.

    Return Value

    The item for the specified index path or nil if no item is available.

    Discussion

    For efficiency, the collection view does not create items until they are needed, and usually it creates them only when they need to be displayed onscreen. If the collection view does not currently have an item for the specified index path, because that item would be positioned offscreen, this method returns nil.

    Availability

    Available in OS X v10.11 and later.

  • Returns the supplementary view associated with the specified index path.

    Declaration

    Swift

    func supplementaryViewForElementKind(_ elementKind: String, atIndexPath indexPath: NSIndexPath) -> NSView?

    Objective-C

    - (NSView<NSCollectionViewElement> *)supplementaryViewForElementKind:(NSString *)elementKind atIndexPath:(NSIndexPath *)indexPath

    Parameters

    elementKind

    The kind of the supplementary views you want returned. The layout object defines the kinds of supplementary views it supports. This parameter must not be nil.

    indexPath

    The index path whose supplementary view you want.

    Return Value

    The view for the specified index path or nil if no view is available.

    Discussion

    For efficiency, the collection view does not create supplementary views until they are needed. Typically, views are created only when they need to be displayed onscreen. If the collection view does not currently have a supplementary view for the specified index path, because that view would be positioned offscreen, this method returns nil.

    Availability

    Available in OS X v10.11 and later.

  • Scrolls the collection view contents until the specified items are visible.

    Declaration

    Swift

    func scrollToItemsAtIndexPaths(_ indexPaths: Set<NSIndexPath>, scrollPosition scrollPosition: NSCollectionViewScrollPosition)

    Objective-C

    - (void)scrollToItemsAtIndexPaths:(NSSet<NSIndexPath *> *)indexPaths scrollPosition:(NSCollectionViewScrollPosition)scrollPosition

    Parameters

    indexPaths

    The index paths of the items. The layout attributes of these items define the bounding box that needs to be scrolled onscreen.

    scrollPosition

    The options for scrolling the bounding box of the specified items into view. You may combine one vertical and one horizontal scrolling option when calling this method. Specifying more than one option for either the vertical or horizontal directions raises an exception.

    Discussion

    To animate the scrolling operation, call this method on the collection view’s animator proxy object instead.

    Availability

    Available in OS X v10.11 and later.

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

    Declaration

    Swift

    func layoutAttributesForItemAtIndexPath(_ indexPath: NSIndexPath) -> NSCollectionViewLayoutAttributes?

    Objective-C

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

    Parameters

    indexPath

    The index path of the item.

    Return Value

    The layout attributes of the item or nil if no item exists at the specified path.

    Discussion

    This method updates the layout information as needed before returning the specified attributes. Always use this method to retrieve the layout attributes for items in the collection view. Do not query the layout object directly.

    Availability

    Available in OS X v10.11 and later.

  • Returns the layout information for the supplementary view at the specified index path.

    Declaration

    Swift

    func layoutAttributesForSupplementaryElementOfKind(_ kind: String, atIndexPath indexPath: NSIndexPath) -> NSCollectionViewLayoutAttributes?

    Objective-C

    - (NSCollectionViewLayoutAttributes *)layoutAttributesForSupplementaryElementOfKind:(NSString *)kind atIndexPath:(NSIndexPath *)indexPath

    Parameters

    kind

    The kind of the supplementary view whose attributes you want. The layout object defines the kinds of supplementary views it supports. This parameter must not be nil.

    indexPath

    The index path of the supplementary view. Normally, this path

    Return Value

    The layout attributes of the supplementary view or nil if no item exists at the specified path.

    Discussion

    This method updates the layout information as needed before returning the specified attributes. Always use this method to retrieve the layout attributes for supplementary views in the collection view. Do not query the layout object directly.

    Availability

    Available in OS X v10.11 and later.

  • Encapsulates multiple insert, delete, reload, and move operations into a single animated operation.

    Declaration

    Swift

    func performBatchUpdates(_ updates: (() -> Void)?, completionHandler completionHandler: ((Bool) -> Void)?)

    Objective-C

    - (void)performBatchUpdates:(void (^)(void))updates completionHandler:(void (^)(BOOL finished))completionHandler

    Parameters

    updates

    The block that performs the needed inset, delete, reload, or move operations. This parameter may be nil.

    completionHandler

    A completion handler block to execute when the changes made in the updates block have finished animating. This parameter may be nil. This block takes the following parameters:

    finished

    A Boolean value indicating whether the animations completed successfully. The value of this parameter is YEStrue if the animations ran to completion or NOfalse if they were interrupted.

    Discussion

    Use this method to make multiple changes to the collection view in one single animated operation. Normally, when you insert, delete, reload, or move items, the collection view animates each change separately. Making those same changes inside the updates block causes them to be animated at the same time. This method updates the current layout information as needed before and after performing the operations in the updates block.

    The order in which you make calls to insert, delete, or otherwise modify the collection view is ignored. When executing your updates block, this method gathers information about the operations you requested without performing those operations. After it gathers that information, the method reorders the operations and performs all deletion operations first, followed by all insertion operations and then all move operations. (Reloading an item is treated as a delete operation followed by an insert operation at the same location.) As a result, the indexes you specify for each set of operations must reflect the changes made by any preceding operations.

    You may call this method from inside your updates or completionHandler blocks.

    Availability

    Available in OS X v10.11 and later.

  • A Boolean value indicating whether the collection view is the first responder. (read-only)

    Declaration

    Swift

    var firstResponder: Bool { get }

    Objective-C

    @property(getter=isFirstResponder, readonly) BOOL firstResponder

    Discussion

    The value of this property is YEStrue when the collection view is the first responder. This property is fully key-value observing compliant.

    Availability

    Available in OS X v10.5 and later.

  • Returns an image to use for dragging the specified items.

    Declaration

    Swift

    func draggingImageForItemsAtIndexPaths(_ indexPaths: Set<NSIndexPath>, withEvent event: NSEvent, offset dragImageOffset: NSPointPointer) -> NSImage

    Objective-C

    - (NSImage *)draggingImageForItemsAtIndexPaths:(NSSet<NSIndexPath *> *)indexPaths withEvent:(NSEvent *)event offset:(NSPointPointer)dragImageOffset

    Parameters

    indexPaths

    The set of NSIndexPath objects corresponding to the items being dragged.

    event

    The mouse-down event that began the drag operation.

    dragImageOffset

    The offset value to use when positioning the image. On input, the point is NSZeroPoint, which centers the returned image under the mouse. Custom implementations can return a different point that repositions the drag image by the specified offset values.

    Return Value

    The image to use for the dragged items.

    Discussion

    The default implementation of this method creates an image using the visible portions of the dragged items. The resulting image is a snapshot of the dragged items as they currently appear in the collection view but rendered with additional transparency to indicate they are part of a drag operation. This method also updates the dragImageOffset parameter to an appropriate point for dragging the resulting image.

    If the delegate implements the collectionView:draggingImageForItemsAtIndexPaths:withEvent:offset: method, the collection view method obtains the drag image from that method instead. If the delegate does not implement that method, the collection view uses the image returned by this method.

    Availability

    Available in OS X v10.11 and later.

  • The receiver’s collection view item prototype.

    Declaration

    Swift

    var itemPrototype: NSCollectionViewItem?

    Objective-C

    @property(strong) NSCollectionViewItem *itemPrototype

    Discussion

    Whenever possible, use a data source object to provide items. For more information, see the dataSource property.

    Availability

    Available in OS X v10.5 and later.

  • Returns the collection view item that is used for the specified object.

    Declaration

    Swift

    func newItemForRepresentedObject(_ object: AnyObject) -> NSCollectionViewItem

    Objective-C

    - (NSCollectionViewItem *)newItemForRepresentedObject:(id)object

    Parameters

    object

    The content object that the collection view item will represent.

    Return Value

    An initialized collection view item with the specified object and the appropriate view set. The collection view item should not be autoreleased.

    Discussion

    Whenever possible, register classes or nib files for your items instead of using this property. For more information, see Creating Collection View Items.

    Subclasses can override this method if the collection view items are not generated from a prototype or if the prototype view needs to be modified. The subclass is responsible for setting the view and representedObject of the new collection view item.

    Availability

    Available in OS X v10.5 and later.

  • The indexes of the currently selected items.

    Declaration

    Swift

    @NSCopying var selectionIndexes: NSIndexSet

    Objective-C

    @property(copy) NSIndexSet *selectionIndexes

    Discussion

    Whenever possible, use the selectionIndexPaths property instead of this one to set selections.

    This property is observable using key-value observing.

    Availability

    Available in OS X v10.5 and later.

  • The maximum number of rows that the collection view displays.

    Declaration

    Swift

    var maxNumberOfRows: Int

    Objective-C

    @property NSUInteger maxNumberOfRows

    Discussion

    When the value of this property is 0, the collection view has no maximum number of rows. The default value of this property is 0.

    It is possible for a collection view to specify both a maximum number of rows and a maximum number of columns. If the number of content objects exceeds the number of displayable items (n=maxNumberOfRows * maxNumberOfColumns) only the first n items of the content array are displayed.

    Availability

    Available in OS X v10.5 and later.

  • The maximum number of columns that the collection view displays.

    Declaration

    Swift

    var maxNumberOfColumns: Int

    Objective-C

    @property NSUInteger maxNumberOfColumns

    Discussion

    When the value of this property is 0, the collection view has no maximum number of columns. The default value of this property is 0.

    It is possible for a collection view to specify both a maximum number of rows and a maximum number of columns. If the number of content objects exceeds the number of displayable items (n=maxNumberOfRows * maxNumberOfColumns) only the first n items of the content array are displayed.

    Availability

    Available in OS X v10.5 and later.

  • The minimum size (in points) of items in the collection view grid.

    Declaration

    Swift

    var minItemSize: NSSize

    Objective-C

    @property NSSize minItemSize

    Discussion

    The default value of this property is (0, 0). If the item’s view is resizable, set the value to the minimum size that the view should use.

    Availability

    Available in OS X v10.5 and later.

  • The maximum size (in points) of items in the collection view grid.

    Declaration

    Swift

    var maxItemSize: NSSize

    Objective-C

    @property NSSize maxItemSize

    Discussion

    Setting the size to (0, 0) means that there is no maximum grid size. The default value of this property is (0, 0). If an item’s view is resizable, set the value to the maximum size that the view should use.

    Availability

    Available in OS X v10.5 and later.

  • Returns the collection view item for the represented object at the specified index.

    Declaration

    Swift

    func itemAtIndex(_ index: Int) -> NSCollectionViewItem?

    Objective-C

    - (NSCollectionViewItem *)itemAtIndex:(NSUInteger)index

    Parameters

    index

    The index of the collection view item.

    Return Value

    An instance of NSCollectionViewItem.

    Discussion

    Rather than using the NSCollectionViewItem instance returned by this method to determine the frame of the collection item’s view you should use content, it is significantly more efficient.

    Availability

    Available in OS X v10.6 and later.

  • Returns the frame of the collection view item at the specified index.

    Declaration

    Swift

    func frameForItemAtIndex(_ index: Int) -> NSRect

    Objective-C

    - (NSRect)frameForItemAtIndex:(NSUInteger)index

    Parameters

    index

    The index of the collection view item.

    Return Value

    The frame calculated by the receiver where it intends to place the subview for the NSCollectionViewItem at the given index. The rectangle is returned in the collection view’s coordinate system.

    Discussion

    You can use this method in the collectionView:draggingImageForItemsAtIndexes:withEvent:offset: method to determine which views are in the visible portion of the enclosing scroll view.

    Overriding this method will have no effect on the collection view’s subview layout.

    Availability

    Available in OS X v10.6 and later.

  • Returns the frame of an item based on the number of items in the collection view.

    Declaration

    Swift

    func frameForItemAtIndex(_ index: Int, withNumberOfItems numberOfItems: Int) -> NSRect

    Objective-C

    - (NSRect)frameForItemAtIndex:(NSUInteger)index withNumberOfItems:(NSUInteger)numberOfItems

    Parameters

    index

    The index of the item in the collection view.

    numberOfItems

    The targeted number of items in the collection view. Use this parameter to specify the number of items you intend to have in the collection view, if that number is different than the actual number of items.

    Return Value

    The frame rectangle that reflects where the collection view would place the item.

    Discussion

    Using the value in the numberOfItems parameter, this method calculates the frame rectangle of the item at the specified index in the collection view.

    When the collection view is a drag destination, use this method (instead of the content method) to get the frame of items. Drag operations can change the number of items, which affects the layout of the item views.

    Availability

    Available in OS X v10.7 and later.

  • This method computes and returns an image to use for dragging.

    Declaration

    Swift

    func draggingImageForItemsAtIndexes(_ indexes: NSIndexSet, withEvent event: NSEvent, offset dragImageOffset: NSPointPointer) -> NSImage

    Objective-C

    - (NSImage *)draggingImageForItemsAtIndexes:(NSIndexSet *)indexes withEvent:(NSEvent *)event offset:(NSPointPointer)dragImageOffset

    Parameters

    indexes

    The index set of the items to be dragged.

    event

    Mouse drag event.

    dragImageOffset

    An in/out parameter that will initially be set to NSZeroPoint. it can be modified to reposition the returned image. A dragImageOffset of NSZeroPoint will cause the image to be centered under the mouse.

    Return Value

    An image containing a rendering of the visible portions of the views for each item.

    Discussion

    You can override the default image by subclassing NSCollectionView and overriding this method, or by implementing the collectionView:draggingImageForItemsAtIndexes:withEvent:offset: delegate method, it will be preferred over this method.

    Availability

    Available in OS X v10.6 and later.

  • Configures the default value returned from draggingSourceOperationMaskForLocal:.

    Declaration

    Swift

    func setDraggingSourceOperationMask(_ dragOperationMask: NSDragOperation, forLocal localDestination: Bool)

    Objective-C

    - (void)setDraggingSourceOperationMask:(NSDragOperation)dragOperationMask forLocal:(BOOL)localDestination

    Parameters

    dragOperationMask

    The types of drag operations allowed.

    localDestination

    If YEStrue, mask applies when the drag destination object is in the same application as the receiver; if NOfalse, mask applies when the destination object is outside the receiver’s application.

    Discussion

    By default, this method returns NSDragOperationEvery when localDestination is YEStrue and NSDragOperationNone when localDestination is NOfalse. NSCollectionView will save the values you set for each localDestination value.

    You typically will invoke this method, and not override it.

    Availability

    Available in OS X v10.6 and later.