Mac Developer Library

Developer

AppKit Framework Reference NSCollectionView Class Reference

Options
Deployment Target:

On This Page
Language:

NSCollectionView

An NSCollectionView object displays a grid of views. Each view in the grid is represented by a NSCollectionViewItem object, which manages the loading of the view’s content from your storyboard or nib file. After adding the collection view in your window, use the methods and properties of this class to manage the contents of the collection view and its behavior.

Inheritance


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.5 and later.
  • The receiver’s collection view item prototype.

    Declaration

    Swift

    var itemPrototype: NSCollectionViewItem!

    Objective-C

    @property(strong) NSCollectionViewItem *itemPrototype

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • content content Property

    An array containing the receiver’s content.

    Declaration

    Swift

    var content: [AnyObject]!

    Objective-C

    @property(copy) NSArray *content

    Discussion

    The content array can also be provided by creating a binding between the receiver’s NSContentBinding and an array controller’s arrangedObjects method.

    This property is observable using key-value observing.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • A Boolean value that indicates whether the receiver allows the user to select items.

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • A Boolean value that indicates whether the collection view allows the user to select more than one item at a time.

    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 column or row at a time. The default value of this property is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • An index set containing the indexes of the selected items in the content array.

    Declaration

    Swift

    @NSCopying var selectionIndexes: NSIndexSet!

    Objective-C

    @property(copy) NSIndexSet *selectionIndexes

    Discussion

    To select all items, create an NSRange type whose location value is 0 and whose length is the number of items in the array minus 1—in other words, count - 1—and assign it to this property.To deselect all items, assign an empty index set to this property.

    This property is observable using key-value observing.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    var backgroundColors: [AnyObject]!

    Objective-C

    @property(copy) NSArray *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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 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 frameForItemAtIndex:, it is significantly more efficient.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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 frameForItemAtIndex: method) to get the frame of items. Drag operations can change the number of items, which affects the layout of the item views.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • These constants specify if acceptance of a drop should be at the item it is dropped on or before the item. These constants are used by the collectionView:acceptDrop:index:dropOperation: and collectionView:validateDrop:proposedIndex:dropOperation: methods in NSCollectionViewDelegate Protocol

    Declaration

    Swift

    enum NSCollectionViewDropOperation : Int { case On case Before }

    Objective-C

    enum { NSCollectionViewDropOn = 0, NSCollectionViewDropBefore = 1, }; typedef NSInteger NSCollectionViewDropOperation;

    Constants

    • On

      NSCollectionViewDropOn

      The drop occurs at the collection view item to which the item was dragged.

      Available in OS X v10.6 and later.

    • Before

      NSCollectionViewDropBefore

      The drop occurs above the collection view item to which the item was dragged..

      Available in OS X v10.6 and later.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.