---

NSOutlineViewDataSource Protocol Reference

(informal protocol)

Overview

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.

The regular delegate object handles all other delegate responsibilities for the outline view.

You must implement the basic methods that provide the outline view with data: outlineView:child:ofItem:, outlineView:isItemExpandable:, outlineView:numberOfChildrenOfItem:, and outlineView:objectValueForTableColumn:byItem:. If you want to allow the user to edit values, you must implement outlineView:setObjectValue:forTableColumn:byItem:. When these methods are invoked by the table 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.

Tasks

Working with Items in a View

• – outlineView:child:ofItem:
• – outlineView:isItemExpandable:
• – outlineView:numberOfChildrenOfItem:
• – outlineView:objectValueForTableColumn:byItem:
• – outlineView:setObjectValue:forTableColumn:byItem:

Supporting Drag and Drop

• – outlineView:acceptDrop:item:childIndex:
• – outlineView:validateDrop:proposedItem:proposedChildIndex:
• – outlineView:namesOfPromisedFilesDroppedAtDestination:forDraggedItems:

Supporting Object Persistence

• – outlineView:itemForPersistentObject:
• – outlineView:persistentObjectForItem:

Working with a Pasteboard

• – outlineView:writeItems:toPasteboard:

Sorting

• – outlineView:sortDescriptorsDidChange:

Instance Methods

outlineView:acceptDrop:item:childIndex:

Returns a Boolean value that indicates whether a drop operation was successful.

- (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

YES if the drop operation was successful, otherwise NO.

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.

Implementation of this method is optional.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – shouldCollapseAutoExpandedItemsForDeposited:

Declared In

NSOutlineView.h

outlineView:child:ofItem:

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

- (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

You must implement this method.

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

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – outlineView:numberOfChildrenOfItem:

Declared In

NSOutlineView.h

outlineView:isItemExpandable:

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

- (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

YES if item can be expanded to display its children, otherwise NO.

Special Considerations

You must implement this method.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSOutlineView.h

outlineView:itemForPersistentObject:

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

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

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSOutlineView.h

outlineView:namesOfPromisedFilesDroppedAtDestination:forDraggedItems:

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

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

Availability

• Available in Mac OS X v10.4 and later.

Declared In

NSOutlineView.h

outlineView:numberOfChildrenOfItem:

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

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

Special Considerations

You must implement this method.

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

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSOutlineView.h

outlineView:objectValueForTableColumn:byItem:

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

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

Special Considerations

You must implement this method.

NSOutlineView requires that each item in the outline view be unique. 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 the specified item.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSOutlineView.h

outlineView:persistentObjectForItem:

Invoked by outlineView to return an archived object for item.

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

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSOutlineView.h

outlineView:setObjectValue:forTableColumn:byItem:

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

- (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

Implementation of this method is optional.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSOutlineView.h

outlineView:sortDescriptorsDidChange:

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

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

Implementation of this method is optional.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

NSOutlineView.h

outlineView:validateDrop:proposedItem:proposedChildIndex:

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

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

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSOutlineView.h

outlineView:writeItems:toPasteboard:

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

- (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

YES if the drag operation is allowed, otherwise NO.

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 NO. To start a drag, return YES 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 YES.

Implementation of this method is optional.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSOutlineView.h

---