NSTableViewDataSource Protocol Reference

Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.6 and later.
Companion guide
Declared in
NSTableView.h
Related sample code

Overview

The NSTableViewDataSource protocol declares the methods that an instance of NSTableView uses to provide the data to a table view and allow editing of the contents of its data source object.

Some of the methods in this protocol, such as tableView:objectValueForTableColumn:row: and numberOfRowsInTableView: along with other methods that return data, are called frequently, so they must be efficient.

If you’re not using Cocoa bindings to provide data to the table view, the following methods are required:

To learn more about Cocoa bindings, see Cocoa Bindings Programming Topics.

Tasks

Getting Values

Setting Values

Implementing Pasteboard Support

Drag and Drop

Sorting

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. Your numberOfRowsInTableView: implementation is called very frequently, so it must be efficient.

Both view-based table views and cell-based table views must implement this method.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTableView.h

tableView:acceptDrop:row:dropOperation:

Called 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 use the draggingPasteboard method to get the data for the drop operation from info.

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.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTableView.h

tableView:draggingSession:endedAtPoint:operation:

Implement this method to determine when a dragging session has ended.

- (void)tableView:(NSTableView *)tableView draggingSession:(NSDraggingSession *)session endedAtPoint:(NSPoint)screenPoint operation:(NSDragOperation)operation
Parameters
tableView

The table view.

session

The dragging session.

screenPoint

The ending drag location in screen coordinates.

operation

The drag operation. See NSDragOperation for supported values.

Discussion

This delegate method can be used to determine when the dragging source operation ended at a specific location, such as the trash, by checking for an operation of NSDragOperationDelete.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSTableView.h

tableView:draggingSession:willBeginAtPoint:forRowIndexes:

Implement this method to determine when a dragging session will begin.

- (void)tableView:(NSTableView *)tableView draggingSession:(NSDraggingSession *)session willBeginAtPoint:(NSPoint)screenPoint forRowIndexes:(NSIndexSet *)rowIndexes
Parameters
tableView

The table view.

session

The dragging session.

screenPoint

The initial drag location in screen coordinates.

rowIndexes

The indexes of the rows to be dragged, excluding rows that were not dragged due to tableView:pasteboardWriterForRow: returning nil.

Discussion

Implement this method to know when the dragging session is about to begin and to potentially modify the dragging session.

The dragged item order will directly match 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 tableView:acceptDrop:row:dropOperation: when enumerating the NSDraggingInfo pasteboard classes.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSTableView.h

tableView:namesOfPromisedFilesDroppedAtDestination:forDraggedRowsWithIndexes:

Returns an array of filenames that represent the indexSet 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 OS X v10.4 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTableView.h

tableView:objectValueForTableColumn:row:

Called 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 aTableView.

rowIndex

The row of the item in aTableColumn.

Return Value

An item in the data source in the specified table column of the view.

Discussion

tableView:objectValueForTableColumn:row: is called each time the table cell needs to be redisplayed, 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.
Declared In
NSTableView.h

tableView:pasteboardWriterForRow:

Called to allow the table to support multiple item dragging.

- (id < NSPasteboardWriting >)tableView:(NSTableView *)tableView pasteboardWriterForRow:(NSInteger)row
Parameters
tableView

The table view.

row

The row.

Return Value

Returns an instance of NSPasteboardItem or a custom object that implements the NSPasteboardWriting protocol. Returning nil excludes the row from being dragged.

Discussion

This method is required for multi-image dragging.

If this method is implemented, then tableView:writeRowsWithIndexes:toPasteboard: will not be called.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSTableView.h

tableView:setObjectValue:forTableColumn:row:

Sets the data object for an item in the specified row and 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

This method is intended for use with cell-based table views, it must not be used with view-based table views. In view-based tables, use target/action to set each item in the view cell.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTableView.h

tableView:sortDescriptorsDidChange:

Called 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 doesn’t manage them itself, you can get the current sort descriptors by sending aTableView 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.
Declared In
NSTableView.h

tableView:updateDraggingItemsForDrag:

Implement this method to allow the table to update dragging items as they are dragged over a view.

- (void)tableView:(NSTableView *)tableView updateDraggingItemsForDrag:(id < NSDraggingInfo >)draggingInfo
Parameters
tableView

The table view.

draggingInfo

The dragging information.

Discussion

Required for multi-image dragging. Typically this will involve invoking enumerateDraggingItemsWithOptions:forView:classes:searchOptions:usingBlock: on the draggingInfo parameter value and setting the draggingItem object’s imageComponentsProvider to a proper image based on the content.

For view-based table views, you can use the NSTableCellView method draggingImageComponents. For cell-based tables, use the NSCell method draggingImageComponentsWithFrame:inView:.

Availability
  • Available in OS X v10.7 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 by calling setDropRow:dropOperation: and returning something other than NSDragOperationNone. A data source might retarget for various reasons, such as to provide 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.

Availability
  • Available in OS X v10.0 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
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

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

Availability
  • Available in OS X v10.4 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTableView.h