Mac Developer Library

Developer

AppKit Framework Reference NSOutlineViewDataSource Protocol Reference

Options
Deployment Target:

On This Page
Language:

NSOutlineViewDataSource

NSOutlineView objects support a data source delegate in addition to the regular delegate object. The NSOutlineViewDataSource protocol defines methods that the outline view invokes as necessary to retrieve data and information about the data from the data source delegate, and—optionally—to update data values.

All the methods in the NSOutlineViewDataSource protocol are marked as @optional. While this is true, there are cases were you must implement some methods to achieve required functionality, specifically when working with conventional data sources rather than data that is provided by Cocoa bindings.

Required and Optional Methods Using Programmatic Conventions and Cocoa Bindings

If you are using conventional data sources for content you must implement the basic methods that provide the outline view with data: outlineView:child:ofItem:, outlineView:isItemExpandable:, outlineView:numberOfChildrenOfItem:, and outlineView:objectValueForTableColumn:byItem:. Applications that acquire their data using Cocoa bindings do not need to implement these methods.

Similarly, when using conventional data sources , if you want to allow the user to edit values, you must implement outlineView:setObjectValue:forTableColumn:byItem:. When these methods are invoked by the outline view, nil as the item refers to the “root” item. NSOutlineView requires that each item in the outline view be unique. In order for the collapsed state of an outline view to remain consistent between reloads you must always return the same object for an item. When using Cocoa bindings to provide outline view content, there is no requirement to implement this method.

  • Returns the child item at the specified index of a given item.

    Declaration

    Swift

    optional func outlineView(_ outlineView: NSOutlineView, child index: Int, ofItem item: AnyObject?) -> AnyObject

    Objective-C

    - (id)outlineView:(NSOutlineView *)outlineView child:(NSInteger)index ofItem:(id)item

    Parameters

    outlineView

    The outline view that sent the message.

    index

    The index of the child item from item to return.

    item

    An item in the data source.

    Return Value

    The child item at index of a item. If item is nil, returns the appropriate child item of the root object.

    Discussion

    Children of a given parent item are accessed sequentially. In order for the collapsed state of the outline view to remain consistent when it is reloaded you must always return the same object for a specified child and item.

    Special Considerations

    The outlineView:child:ofItem: method is called very frequently, so it must be efficient.

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Returns a Boolean value that indicates whether the a given item is expandable.

    Declaration

    Swift

    optional func outlineView(_ outlineView: NSOutlineView, isItemExpandable item: AnyObject) -> Bool

    Objective-C

    - (BOOL)outlineView:(NSOutlineView *)outlineView isItemExpandable:(id)item

    Parameters

    outlineView

    The outline view that sent the message.

    item

    An item in the data source.

    Return Value

    YEStrue if item can be expanded to display its children, otherwise NOfalse.

    Discussion

    This method may be called quite often, so it must be efficient.

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Returns the number of child items encompassed by a given item.

    Declaration

    Swift

    optional func outlineView(_ outlineView: NSOutlineView, numberOfChildrenOfItem item: AnyObject?) -> Int

    Objective-C

    - (NSInteger)outlineView:(NSOutlineView *)outlineView numberOfChildrenOfItem:(id)item

    Parameters

    outlineView

    The outline view that sent the message.

    item

    An item in the data source.

    Return Value

    The number of child items encompassed by item. If item is nil, this method should return the number of children for the top-level item.

    Discussion

    The outlineView:numberOfChildrenOfItem: method is called very frequently, so it must be efficient.

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Invoked by outlineView to return the data object associated with the specified item.

    Declaration

    Swift

    optional func outlineView(_ outlineView: NSOutlineView, objectValueForTableColumn tableColumn: NSTableColumn?, byItem item: AnyObject?) -> AnyObject?

    Objective-C

    - (id)outlineView:(NSOutlineView *)outlineView objectValueForTableColumn:(NSTableColumn *)tableColumn byItem:(id)item

    Parameters

    outlineView

    The outline view that sent the message.

    tableColumn

    A column in outlineView.

    item

    An item in the data source in the specified tableColumn of the view.

    Discussion

    The item is located in the specified tableColumn of the view.

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Set the data object for a given item in a given column.

    Declaration

    Swift

    optional func outlineView(_ outlineView: NSOutlineView, setObjectValue object: AnyObject?, forTableColumn tableColumn: NSTableColumn?, byItem item: AnyObject?)

    Objective-C

    - (void)outlineView:(NSOutlineView *)outlineView setObjectValue:(id)object forTableColumn:(NSTableColumn *)tableColumn byItem:(id)item

    Parameters

    outlineView

    The outline view that sent the message.

    object

    The new value for the item.

    tableColumn

    A column in outlineView.

    item

    An item in the data source in the specified tableColumn of the view.

    Discussion

    The item is located in the specified tableColumn of the view.

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Invoked by outlineView to return the item for the archived object.

    Declaration

    Swift

    optional func outlineView(_ outlineView: NSOutlineView, itemForPersistentObject object: AnyObject) -> AnyObject?

    Objective-C

    - (id)outlineView:(NSOutlineView *)outlineView itemForPersistentObject:(id)object

    Parameters

    outlineView

    The outline view that sent the message.

    object

    An archived representation of an item in outlineView's data source.

    Return Value

    The unarchived item corresponding to object. If the item is an archived object, this method may return the object.

    Discussion

    When the outline view is restoring the saved expanded items, this method is called for each expanded item, to translate the archived object to an outline view item.

    Special Considerations

    You must implement this method if you are automatically saving expanded items (that is, if autosaveExpandedItems returns YEStrue).

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Invoked by outlineView to return an archived object for item.

    Declaration

    Swift

    optional func outlineView(_ outlineView: NSOutlineView, persistentObjectForItem item: AnyObject?) -> AnyObject?

    Objective-C

    - (id)outlineView:(NSOutlineView *)outlineView persistentObjectForItem:(id)item

    Parameters

    outlineView

    The outline view that sent the message.

    item

    The item for which to return an archived object.

    Return Value

    An archived representation of item. If the item is an archived object, this method may return the item.

    Discussion

    When the outline view is saving the expanded items, this method is called for each expanded item, to translate the outline view item to an archived object.

    Special Considerations

    You must implement this method if you are automatically saving expanded items (that is, if autosaveExpandedItems returns YEStrue).

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Returns a Boolean value that indicates whether a drag operation is allowed.

    Declaration

    Swift

    optional func outlineView(_ outlineView: NSOutlineView, writeItems items: [AnyObject], toPasteboard pasteboard: NSPasteboard) -> Bool

    Objective-C

    - (BOOL)outlineView:(NSOutlineView *)outlineView writeItems:(NSArray *)items toPasteboard:(NSPasteboard *)pboard

    Parameters

    outlineView

    The outline view that invoked the method.

    items

    An array of the items participating in the drag.

    pboard

    The pasteboard to which to write the drag data.

    Return Value

    YEStrue if the drag operation is allowed, otherwise NOfalse.

    Discussion

    Invoked by outlineView after it has been determined that a drag should begin, but before the drag has been started.

    To refuse the drag, return NOfalse. To start a drag, return YEStrue and place the drag data onto the pboard (data, owner, and so on). The drag image and other drag-related information will be set up and provided by the outline view once this call returns with YEStrue.

    Availability

    Available in OS X v10.0 and later.

    Available as part of an informal protocol prior to OS X v10.6.

  • Invoked by an outline view to notify the data source that the descriptors changed and the data may need to be resorted.

    Declaration

    Swift

    optional func outlineView(_ outlineView: NSOutlineView, sortDescriptorsDidChange oldDescriptors: [NSSortDescriptor])

    Objective-C

    - (void)outlineView:(NSOutlineView *)outlineView sortDescriptorsDidChange:(NSArray<NSSortDescriptor *> *)oldDescriptors

    Parameters

    outlineView

    The outline view that sent the message.

    oldDescriptors

    An array that contains the previous descriptors.

    Discussion

    The data source typically sorts and reloads the data, and adjusts the selections accordingly. If you need to know the current sort descriptors and the data source does not itself manage them, you can get outlineView's current sort descriptors by sending it a sortDescriptors message.

    Availability

    Available in OS X v10.3 and later.

    Available as part of an informal protocol prior to OS X v10.6.