Mac Developer Library

Developer

AppKit Framework Reference NSOutlineViewDataSource Protocol Reference

Options
Deployment Target:

On This Page
Language:

NSOutlineViewDataSource

Inheritance


Not Applicable

Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.6 and later.

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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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 drop operation was successful.

    Declaration

    Swift

    optional func outlineView(_ outlineView: NSOutlineView, acceptDrop info: NSDraggingInfo, item item: AnyObject?, childIndex index: Int) -> Bool

    Objective-C

    - (BOOL)outlineView:(NSOutlineView *)outlineView acceptDrop:(id<NSDraggingInfo>)info item:(id)item childIndex:(NSInteger)index

    Parameters

    outlineView

    The outline view that sent the message. outlineView must have previously allowed a drop.

    info

    An object that contains more information about this dragging operation.

    item

    The parent of the item over which the cursor was placed when the mouse button was released.

    index

    The index of the child of item over which the cursor was placed when the mouse button was released.

    Return Value

    YEStrue if the drop operation was successful, otherwise NOfalse.

    Discussion

    The data source should incorporate the data from the dragging pasteboard in the implementation of this method. You can get the data for the drop operation from info using the draggingPasteboard method.

    The return value indicates success or failure of the drag operation to the system.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

  • Used by an outline view to determine a valid drop target.

    Declaration

    Swift

    optional func outlineView(_ outlineView: NSOutlineView, validateDrop info: NSDraggingInfo, proposedItem item: AnyObject?, proposedChildIndex index: Int) -> NSDragOperation

    Objective-C

    - (NSDragOperation)outlineView:(NSOutlineView *)outlineView validateDrop:(id<NSDraggingInfo>)info proposedItem:(id)item proposedChildIndex:(NSInteger)index

    Parameters

    outlineView

    The outline view that sent the message.

    info

    An object that contains more information about this dragging operation.

    item

    The proposed parent.

    index

    The proposed child location.

    Return Value

    A value that indicates which dragging operation the data source will perform.

    Discussion

    Based on the mouse position, the outline view will suggest a proposed drop location. The data source may “retarget” a drop if desired by calling setDropItem:dropChildIndex: and returning something other than NSDragOperationNone. You may choose to retarget for various reasons (for example, for better visual feedback when inserting into a sorted position).

    Implementation of this method is optional.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

  • Returns an array of filenames for the created files that the receiver promises to create.

    Declaration

    Swift

    optional func outlineView(_ outlineView: NSOutlineView, namesOfPromisedFilesDroppedAtDestination dropDestination: NSURL, forDraggedItems items: [AnyObject]) -> [AnyObject]

    Objective-C

    - (NSArray *)outlineView:(NSOutlineView *)outlineView namesOfPromisedFilesDroppedAtDestination:(NSURL *)dropDestination forDraggedItems:(NSArray *)items

    Parameters

    outlineView

    The outline view that sent the message.

    dropDestination

    The drop location where the files are created.

    items

    The items being dragged.

    Return Value

    An array of filenames (not full paths) for the created files that the receiver promises to create.

    Discussion

    For more information on file promise dragging, see documentation on the NSDraggingSource protocol and namesOfPromisedFilesDroppedAtDestination:.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

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

  • Implement this method to know when the given dragging session has ended. (required)

    Declaration

    Swift

    optional func outlineView(_ outlineView: NSOutlineView, draggingSession session: NSDraggingSession, endedAtPoint screenPoint: NSPoint, operation operation: NSDragOperation)

    Objective-C

    - (void)outlineView:(NSOutlineView *)outlineView draggingSession:(NSDraggingSession *)session endedAtPoint:(NSPoint)screenPoint operation:(NSDragOperation)operation

    Parameters

    outlineView

    The outline view in which the drag began.

    session

    The dragging session that ended.

    screenPoint

    The point onscreen at which the drag ended.

    operation

    A mask specifying the types of drag operations permitted by the dragging source.

    Discussion

    You can implement this optional delegate method to know when the dragging source operation ended at a specific location, such as the trash (by checking for an operation of NSDragOperationDelete).

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Implement this method know when the given dragging session is about to begin and potentially modify the dragging session. (required)

    Declaration

    Swift

    optional func outlineView(_ outlineView: NSOutlineView, draggingSession session: NSDraggingSession, willBeginAtPoint screenPoint: NSPoint, forItems draggedItems: [AnyObject])

    Objective-C

    - (void)outlineView:(NSOutlineView *)outlineView draggingSession:(NSDraggingSession *)session willBeginAtPoint:(NSPoint)screenPoint forItems:(NSArray *)draggedItems

    Parameters

    outlineView

    The outline view in which the drag is about to begin.

    session

    The dragging session that is about to begin.

    screenPoint

    The point onscreen at which the drag is to begin.

    draggedItems

    A array of items to be dragged, excluding items for which outlineView:pasteboardWriterForItem: returns nil.

    Discussion

    The draggedItems array directly matches the pasteboard writer array used to begin the dragging session with the NSView method beginDraggingSessionWithItems:event:source:. Hence, the order is deterministic, and can be used in outlineView:acceptDrop:item:childIndex: when enumerating the NSDraggingInfo protocol's pasteboard classes.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Implement this method to enable the table to be an NSDraggingSource that supports dragging multiple items. (required)

    Declaration

    Swift

    optional func outlineView(_ outlineView: NSOutlineView, pasteboardWriterForItem item: AnyObject?) -> NSPasteboardWriting!

    Objective-C

    - (id<NSPasteboardWriting>)outlineView:(NSOutlineView *)outlineView pasteboardWriterForItem:(id)item

    Parameters

    outlineView

    The outline view in which the drag begins.

    item

    The item for which to return a pasteboard writer.

    Return Value

    A custom object that implements NSPasteboardWriting protocol (or simply use NSPasteboardItem).

    Discussion

    If this method is implemented, then outlineView:writeItems:toPasteboard: is not called.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • Implement this method to enable the table to update dragging items as they are dragged over the view. (required)

    Declaration

    Swift

    optional func outlineView(_ outlineView: NSOutlineView, updateDraggingItemsForDrag draggingInfo: NSDraggingInfo)

    Objective-C

    - (void)outlineView:(NSOutlineView *)outlineView updateDraggingItemsForDrag:(id<NSDraggingInfo>)draggingInfo

    Parameters

    outlineView

    The outline view in which the drag occurs.

    draggingInfo

    The dragging info object.

    Discussion

    Implementing this method is required for multi-image dragging. A typical implementation calls the passed-in dragging info object’s enumerateDraggingItemsWithOptions:forView:classes:searchOptions:usingBlock: method and sets the dragging item's imageComponentsProvider property to a proper image based on the content. For NSView-based table views, you can use the NSTableCellView method draggingImageComponents.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.7 and later.

  • 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).

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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).

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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 pboard: 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    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: [AnyObject])

    Objective-C

    - (void)outlineView:(NSOutlineView *)outlineView sortDescriptorsDidChange:(NSArray *)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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.3 and later.

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