---

NSTableDataSource Protocol Reference

(informal protocol)

Overview

The NSTableDataSource informal protocol declares the methods that an instance of NSTableView uses to access the contents of its data source object.

Tasks

Getting Values

• – numberOfRowsInTableView:
• – tableView:objectValueForTableColumn:row:

Setting Values

• – tableView:setObjectValue:forTableColumn:row:

Dragging

• – tableView:acceptDrop:row:dropOperation:
• – tableView:namesOfPromisedFilesDroppedAtDestination:forDraggedRowsWithIndexes:
• – tableView:validateDrop:proposedRow:proposedDropOperation:
• – tableView:writeRowsWithIndexes:toPasteboard:

Sorting

• – tableView:sortDescriptorsDidChange:

Deprecated Methods

• – tableView:writeRows:toPasteboard: Deprecated in Mac OS X v10.4 and later

Instance Methods

numberOfRowsInTableView:

Returns the number of records managed for aTableView by the data source object.

- (NSInteger)numberOfRowsInTableView:(NSTableView *)aTableView

Parameters

aTableView

The table view that sent the message.

Return Value

The number of rows in aTableView.

Discussion

An instance of NSTableView uses this method to determine how many rows it should create and display.

Availability

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

Declared In

NSTableView.h

tableView:acceptDrop:row:dropOperation:

Invoked by aTableView when the mouse button is released over a table view that previously decided to allow a drop.

- (BOOL)tableView:(NSTableView *)aTableView acceptDrop:(id < NSDraggingInfo >)info row:(NSInteger)row dropOperation:(NSTableViewDropOperation)operation

Parameters

aTableView

The table view that sent the message.

info

An object that contains more information about this dragging operation.

row

The index of the proposed target row.

operation

The type of dragging operation.

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.

To accept a drop on the second row, row would be 2 and operation would be NSTableViewDropOn. To accept a drop below the last row, row would be [aTableView numberOfRows] and operation would be NSTableViewDropAbove.

Implementation of this method is optional.

Availability

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

Declared In

NSTableView.h

tableView:namesOfPromisedFilesDroppedAtDestination:forDraggedRowsWithIndexes:

Returns an array of filenames that represent theindexSet rows for a drag to dropDestination.

- (NSArray *)tableView:(NSTableView *)aTableView namesOfPromisedFilesDroppedAtDestination:(NSURL *)dropDestination forDraggedRowsWithIndexes:(NSIndexSet *)indexSet

Parameters

aTableView

The table view that sent the message.

dropDestination

The drop location where the files are created.

indexSet

The indexes of the items being dragged.

Return Value

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

Discussion

This method is called when a destination has accepted a promise drag.

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

NSTableView.h

tableView:objectValueForTableColumn:row:

Invoked by the table view to return the data object associated with the specified row and column.

- (id)tableView:(NSTableView *)aTableView objectValueForTableColumn:(NSTableColumn *)aTableColumn row:(NSInteger)rowIndex

Parameters

aTableView

The table view that sent the message.

aTableColumn

A column in in aTableView.

rowIndex

The row of the item in aTableColumn.

Return Value

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

Discussion

Availability

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

Declared In

NSTableView.h

tableView:setObjectValue:forTableColumn:row:

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

- (void)tableView:(NSTableView *)aTableView setObjectValue:(id)anObject forTableColumn:(NSTableColumn *)aTableColumn row:(NSInteger)rowIndex

Parameters

aTableView

The table view that sent the message.

anObject

The new value for the item.

aTableColumn

A column in aTableView.

rowIndex

The row of the item in aTableColumn.

Discussion

Implementation of this method is optional.

Availability

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

Declared In

NSTableView.h

tableView:sortDescriptorsDidChange:

Invoked by aTableView to indicate that sorting may need to be done.

- (void)tableView:(NSTableView *)aTableView sortDescriptorsDidChange:(NSArray *)oldDescriptors

Parameters

aTableView

The table 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 manage them itself, you can get the current sort descriptors by sending aTableView a sortDescriptors message.

Implementation of this method is optional.

Availability

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

Declared In

NSTableView.h

tableView:validateDrop:proposedRow:proposedDropOperation:

Used by aTableView to determine a valid drop target.

- (NSDragOperation)tableView:(NSTableView *)aTableView validateDrop:(id < NSDraggingInfo >)info proposedRow:(NSInteger)row proposedDropOperation:(NSTableViewDropOperation)operation

Parameters

aTableView

The table view that sent the message.

info

An object that contains more information about this dragging operation.

row

The index of the proposed target row.

operation

The type of dragging operation proposed.

Return Value

The dragging operation the data source will perform.

Discussion

The data source may “retarget” a drop if desired by calling setDropRow:dropOperation: and returning something other than NSDragOperationNone. One may choose to retarget for various reasons (e.g. for better visual feedback when inserting into a sorted position).

To propose a drop on the second row, row would be 2 and operation would be NSTableViewDropOn. To propose a drop below the last row, row would be [aTableView numberOfRows] and operation would be NSTableViewDropAbove.

Implementation of this method is optional.

Availability

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

Declared In

NSTableView.h

tableView:writeRowsWithIndexes:toPasteboard:

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

- (BOOL)tableView:(NSTableView *)aTableView writeRowsWithIndexes:(NSIndexSet *)rowIndexes toPasteboard:(NSPasteboard *)pboard

Parameters

aTableView

The table view that sent the message.

rowIndexes

An index set of row numbers that will be participating in the drag.

pboard

The pasteboard to which to write the drag data.

Return Value

YES if the drag operation is allowed, NO otherwise.

Discussion

Invoked by aTableView 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 pboard (data, owner, and so on). The drag image and other drag-related information will be set up and provided by the table view once this call returns with YES.

Implementation of this method is optional.

Availability

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

Declared In

NSTableView.h

---