NSTableViewDelegate Protocol Reference

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

Overview

The NSTableViewDelegate protocol defines the optional methods implemented by delegates of NSTableView objects. Using a table view delegate allows you to customize a table view’s behavior without creating a table view subclass. A table view delegate provides views for table rows and columns, and supports functionality such as column reordering and resizing and row selection.

Tasks

Providing Views for Rows and Columns

Notification of Row Views Being Added or Removed

Grouping Rows

Providing Cells for Rows and Columns

Editing Cells

Setting Row and Column Size

Selecting Rows

Moving and Resizing Columns

Responding to Mouse Events

Instance Methods

selectionShouldChangeInTableView:

Asks the delegate if the user is allowed to change the selection.

- (BOOL)selectionShouldChangeInTableView:(NSTableView *)aTableView
Parameters
aTableView

The table view that sent the message.

Return Value

YES to allow the table view to change its selection (typically a row being edited), NO to deny selection change.

Discussion

The user can select and edit different cells within the same row, but can’t select another row unless the delegate approves. The delegate can implement this method for complex validation of edited rows based on the values of any of their cells.

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:dataCellForTableColumn:row:

Asks the delegate for a custom data cell for the specified row and column.

- (NSCell *)tableView:(NSTableView *)tableView dataCellForTableColumn:(NSTableColumn *)tableColumn row:(NSInteger)row
Parameters
tableView

The table view that sent the message.

tableColumn

The table column.

row

The row index.

Return Value

An NSCell subclass that is used for the specified row and tableColumn. The returned cell must properly implement copyWithZone:.

Discussion

A different data cell can be returned for any particular table column and row, or a cell that will be used for the entire row (that is, a full width cell).

If tableColumn is non-nil, you should return a cell (generally as the result of sending tableColumn a dataCellForRow: message).

While each row is being drawn, this method is first called with a tableColumn value of nil to allow you to return a group cell—that is, a cell that will be used to draw the entire row. If you return a cell when tableColumn is nil, all implemented datasource and delegate methods must be prepared to handle a nil table column value. If you don't return a cell, this method is called once for each tableColumn in tableView.

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

tableView:didAddRowView:forRow:

Tells the delegate that a row view was added at the specified row.

- (void)tableView:(NSTableView *)tableView didAddRowView:(NSTableRowView *)rowView forRow:(NSInteger)row
Parameters
tableView

The table view that sent the message.

rowView

The row view.

row

The index of the row.

Discussion

At this point, the delegate can add extra views, or modify the properties of rowView.

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

tableView:didClickTableColumn:

Tells the delegate that the mouse button was clicked in the specified table column, but the column was not dragged.

- (void)tableView:(NSTableView *)tableView didClickTableColumn:(NSTableColumn *)tableColumn
Parameters
tableView

The table view that sent the message.

tableColumn

The table column.

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:didDragTableColumn:

Tells the delegate that the specified table column was dragged.

- (void)tableView:(NSTableView *)tableView didDragTableColumn:(NSTableColumn *)tableColumn
Parameters
tableView

The table view that sent the message.

tableColumn

The table column.

Special Considerations

Specifically, this method is sent when the mouse button goes up in tableView and tableColumn has been dragged during the time the mouse button was down. On OS X v 10.5 and later the dragged column is sent to the delegate. (In earlier versions of OS X the table column that’s currently located at the dragged column's original index is sent.)

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:didRemoveRowView:forRow:

Tells the delegate that a row view was removed from the table at the specified row.

- (void)tableView:(NSTableView *)tableView didRemoveRowView:(NSTableRowView *)rowView forRow:(NSInteger)row
Parameters
tableView

The table view that sent the message.

rowView

The row view.

row

The index of the row.

Discussion

If row equals -1, the row is being deleted from the table and is no longer a valid row; otherwise row is a valid row that is being removed by being moved off screen.

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

tableView:heightOfRow:

Asks the delegate for the height of the specified row.

- (CGFloat)tableView:(NSTableView *)tableView heightOfRow:(NSInteger)row
Parameters
tableView

The table view that sent the message.

row

The row index.

Return Value

The height of the row. The height should not include intercell spacing and must be greater than zero.

Discussion

You should implement this method if your table supports varying row heights.

Although table views may cache the returned values, you should ensure that this method is efficient. When you change a row's height you must invalidate the existing row height by calling noteHeightOfRowsWithIndexesChanged:. NSTableView automatically invalidates its entire row height cache when reloadData and noteNumberOfRowsChanged are called.

If you call viewAtColumn:row:makeIfNecessary: or rowViewAtRow:makeIfNecessary: within your implementation of this method, an exception is thrown.

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:isGroupRow:

Returns whether the specified row is a group row.

- (BOOL)tableView:(NSTableView *)tableView isGroupRow:(NSInteger)row
Parameters
tableView

The table view that sent the message.

row

The row index.

Return Value

YES if the specified row should have the group row style drawn, NO otherwise.

Discussion

If the cell in row is an NSTextFieldCell and contains only a string, the group row style attributes will automatically be applied to the cell.

Group rows in NSView-based table views can be made to visually “float” by setting the table view method setFloatsGroupRows: to YES.

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

tableView:mouseDownInHeaderOfTableColumn:

Tells the delegate that the mouse button was clicked in the specified table column’s header.

- (void)tableView:(NSTableView *)tableView mouseDownInHeaderOfTableColumn:(NSTableColumn *)tableColumn
Parameters
tableView

The table view that sent the message.

tableColumn

The table column.

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:nextTypeSelectMatchFromRow:toRow:forString:

Asks the delegate for the row within the specified search range that matches the specified string.

- (NSInteger)tableView:(NSTableView *)tableView nextTypeSelectMatchFromRow:(NSInteger)startRow toRow:(NSInteger)endRow forString:(NSString *)searchString
Parameters
tableView

The table view that sent the message.

startRow

The starting row of the search range.

endRow

The ending row of the search range.

searchString

A string containing the typed selection.

Return Value

The first row in the range of startRow through endRow (excluding endRow itself) that matches selectionString. Return -1 if no match is found.

Discussion

Use this method to control how type selection works in a table. (Implementation of this method isn’t required to support type selection.) Note that it’s possible for endRow to be less than startRow if the search will wrap.

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

tableView:rowViewForRow:

Asks the delegate for a view to display the specified row.

- (NSTableRowView *)tableView:(NSTableView *)tableView rowViewForRow:(NSInteger)row
Parameters
tableView

The table view that sent the message.

row

The row index.

Return Value

An instance or subclass of NSTableRowView. If nil is returned, an NSTableRowView instance will be created and used.

Discussion

The delegate can implement this method to return a custom NSTableRowView for row.

The reuse queue can be used in the same way as documented in tableView:viewForTableColumn:row:. The returned view will have attributes properly set to it before it’s added to the tableView.

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

tableView:selectionIndexesForProposedSelection:

Asks the delegate to accept or reject the proposed selection.

- (NSIndexSet *)tableView:(NSTableView *)tableView selectionIndexesForProposedSelection:(NSIndexSet *)proposedSelectionIndexes
Parameters
tableView

The table view that sent the message.

proposedSelectionIndexes

An index set containing the indexes of the proposed selection.

Return Value

An NSIndexSet instance containing the indexes of the new selection. Return proposedSelectionIndexes if the proposed selection is acceptable, or the value of the table view’s existing selection to avoid changing the selection.

Discussion

This method may be called multiple times with one new index added to the existing selection to find out if a particular index can be selected when the user is extending the selection with the keyboard or mouse.

If implemented, this method will be called instead of tableView:shouldSelectRow:.

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

tableView:shouldEditTableColumn:row:

Asks the delegate if the cell at the specified row and column can be edited.

- (BOOL)tableView:(NSTableView *)aTableView shouldEditTableColumn:(NSTableColumn *)aTableColumn row:(NSInteger)rowIndex
Parameters
aTableView

The table view that sent the message.

aTableColumn

The table column.

rowIndex

The row index.

Return Value

YES to allow editing the cell, NO to deny editing.

Discussion

The delegate can implement this method to disallow editing of specific cells.

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:shouldReorderColumn:toColumn:

Asks the delegate to allow or prohibit the specified column to be dragged to a new location.

- (BOOL)tableView:(NSTableView *)tableView shouldReorderColumn:(NSInteger)columnIndex toColumn:(NSInteger)newColumnIndex
Parameters
tableView

The table view that sent the message.

columnIndex

The index of the column being dragged.

newColumnIndex

The proposed target index of the column.

Return Value

YES if the column reordering should be allowed, otherwise NO.

Discussion

When a column is initially dragged by the user, the delegate is first called with a newColumnIndex value of -1. Returning NO will disallow that column from being reordered at all. Returning YES allows it to be reordered, and the delegate will be called again when the column reaches a new location.

The actual NSTableColumn instance can be retrieved from the tableColumns array.

If this method isn’t implemented, all columns are considered reorderable.

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

tableView:shouldSelectRow:

Asks the delegate if the table view should allow selection of the specified row.

- (BOOL)tableView:(NSTableView *)aTableView shouldSelectRow:(NSInteger)rowIndex
Parameters
aTableView

The table view that sent the message.

rowIndex

The row index.

Return Value

YES to permit selection of the row, NO to deny selection.

Discussion

The delegate can implement this method to disallow selection of particular rows.

For better performance and finer-grain control over the selection, use tableView:selectionIndexesForProposedSelection:.

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:shouldSelectTableColumn:

Asks the delegate whether the specified table column can be selected.

- (BOOL)tableView:(NSTableView *)aTableView shouldSelectTableColumn:(NSTableColumn *)aTableColumn
Parameters
aTableView

The table view that sent the message.

aTableColumn

The table column.

Return Value

YES to permit selection, otherwise NO.

Discussion

The delegate can implement this method to disallow selection of particular columns.

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:shouldShowCellExpansionForTableColumn:row:

Asks the delegate if an expansion tooltip should be displayed for a specific row and column.

- (BOOL)tableView:(NSTableView *)tableView shouldShowCellExpansionForTableColumn:(NSTableColumn *)tableColumn row:(NSInteger)row
Parameters
tableView

The table view that sent the message.

tableColumn

The table column.

row

The row index.

Return Value

YES if an expansion tooltip should be displayed, NO otherwise.

Discussion

An expansion tooltip can be displayed when the pointer hovers over a cell that contains truncated text. When this method returns YES, the cell’s full contents is shown in an expansion tooltip, which looks similar to a help tag.

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

tableView:shouldTrackCell:forTableColumn:row:

Asks the delegate whether the specified cell should be tracked.

- (BOOL)tableView:(NSTableView *)tableView shouldTrackCell:(NSCell *)cell forTableColumn:(NSTableColumn *)tableColumn row:(NSInteger)row
Parameters
tableView

The table view that sent the message.

cell

The cell to track.

tableColumn

The table column.

row

A row in tableView.

Return Value

YES if the cell should be tracked, NO otherwise.

Discussion

In general, only selectable or selected cells can be tracked. If you implement this method, cells that aren’t selectable or selected can be tracked; similarly, cells that are selectable or selected can be set as untracked.

For example, this allows you to have an NSButtonCell in a table that doesn’t change the selection, but can still be clicked on and tracked.

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

tableView:shouldTypeSelectForEvent:withCurrentSearchString:

Asks the delegate to allow or deny type select for the specified event and current search string.

- (BOOL)tableView:(NSTableView *)tableView shouldTypeSelectForEvent:(NSEvent *)event withCurrentSearchString:(NSString *)searchString
Parameters
tableView

The table view that sent the message.

event

The event.

searchString

The search string or nil if no type select has began.

Return Value

YES to allow type select for event, NO otherwise.

Discussion

Typically, this is called from the table view keyDown: implementation and the event will be a key event.

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

tableView:sizeToFitWidthOfColumn:

Asks the delegate to provide custom sizing behavior when a column’s resize divider is double clicked.

- (CGFloat)tableView:(NSTableView *)tableView sizeToFitWidthOfColumn:(NSInteger)column
Parameters
tableView

The table view that sent the message.

column

The index of the column.

Return Value

The width of the specified column.

Discussion

By default, NSTableView iterates every row in the table, accesses a cell via preparedCellAtColumn:row:, and requests the cellSize to find the appropriate largest width to use.

For accurate results and performance, it’s recommended that this method is implemented when using large tables. By default, large tables use a monte carlo simulation instead of iterating every row.

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

tableView:toolTipForCell:rect:tableColumn:row:mouseLocation:

Asks the delegate for a string to display in a tooltip for the specified cell in the column and row.

- (NSString *)tableView:(NSTableView *)aTableView toolTipForCell:(NSCell *)aCell rect:(NSRectPointer)rect tableColumn:(NSTableColumn *)aTableColumn row:(NSInteger)row mouseLocation:(NSPoint)mouseLocation
Parameters
aTableView

The table view that sent the message.

aCell

The cell.

rect

The proposed active area of the tooltip. You can modify rect to provide an alternative active area.

aTableColumn

The table column.

row

The row index.

mouseLocation

The mouse location.

Return Value

A string that should be displayed in the tooltip. Return nil or the empty string if no tooltip is desired.

Discussion

By default, rect is computed as [cell drawingRectForBounds:cellFrame]. Note that tooltips are also known as help tags.

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:typeSelectStringForTableColumn:row:

Asks the delegate to provide an alternative text value used for type selection for the specified row and column.

- (NSString *)tableView:(NSTableView *)tableView typeSelectStringForTableColumn:(NSTableColumn *)tableColumn row:(NSInteger)row
Parameters
tableView

The table view that sent the message.

tableColumn

The table column.

row

The row index.

Return Value

A string that is used in type select comparison for row and tableColumn. Return nil if row or tableColumn should not be searched.

Discussion

Implement this method to change the string value that is searched for based on what is displayed. By default, all cells with text in them are searched.

If this delegate method isn’t implemented, the default string value (which can also be returned from the delegate method) is:

[[tableView preparedCellAtColumn:tableColumn row:row] stringValue]
Availability
  • Available in OS X v10.5 and later.
  • Available as part of an informal protocol prior to OS X v10.6.
Declared In
NSTableView.h

tableView:viewForTableColumn:row:

Asks the delegate for a view to display the specified row and column.

- (NSView *)tableView:(NSTableView *)tableView viewForTableColumn:(NSTableColumn *)tableColumn row:(NSInteger)row
Parameters
tableView

The table view that sent the message.

tableColumn

The table column. (If the row is a group row, tableColumn is nil.)

row

The row index.

Return Value

The view to display the specified column and row. If you return nil, a view will not be shown at that location.

Discussion

This method is required if you want to use NSView objects instead of NSCell objects for the cells within a table view. Cells and views can’t be mixed within the same table view.

It’s recommended that the implementation of this method first call the NSTableView method makeViewWithIdentifier:owner: passing, respectively, the tableColumn parameter’s identifier and self as the owner to attempt to reuse a view that is no longer visible or automatically unarchive an associated prototype view for that identifier. The frame of the view returned by this method is not important, and it will be automatically set by the table.

The view's properties should be properly set up before returning the result.

When using Cocoa bindings, this method is optional if at least one identifier has been associated with the table view at design time. (Note that a view’s identifier must be the same as the identifier of its column. An easy way to achieve this is to use the Automatic identifier setting in Interface Builder.) If this method isn’t implemented, the table will automatically call the NSTableView method makeViewWithIdentifier:owner: with the tableColumn parameter’s identifier and the table view’s delegate as parameters, to attempt to reuse a previous view, or automatically unarchive a prototype associated with the table view. If this method is implemented, you can set up properties that aren’t using bindings.

The autoresizing mask of the returned view will automatically be set to NSViewHeightSizable to resize properly on row height changes.

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

tableView:willDisplayCell:forTableColumn:row:

Tells the delegate that the table view will display the specified cell at the specified row and column.

- (void)tableView:(NSTableView *)aTableView willDisplayCell:(id)aCell forTableColumn:(NSTableColumn *)aTableColumn row:(NSInteger)rowIndex
Parameters
aTableView

The table view that sent the message.

aCell

The cell to be displayed.

aTableColumn

The table column.

rowIndex

The row index.

Discussion

The delegate can modify the display attributes of aCell to alter the appearance of the cell.

Because aCell is reused for every row in aTableColumn, the delegate must set the display attributes both when drawing special cells and when drawing standard cells.

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

tableViewColumnDidMove:

Tells the delegate that a table column was moved by user action.

- (void)tableViewColumnDidMove:(NSNotification *)aNotification
Parameters
aNotification

A notification named NSTableViewColumnDidMoveNotification.

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

tableViewColumnDidResize:

Tells the delegate that a tablecolumn was resized.

- (void)tableViewColumnDidResize:(NSNotification *)aNotification
Parameters
aNotification

A notification named NSTableViewColumnDidResizeNotification.

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

tableViewSelectionDidChange:

Tells the delegate that the table view’s selection has changed.

- (void)tableViewSelectionDidChange:(NSNotification *)aNotification
Parameters
aNotification

A notification named NSTableViewSelectionDidChangeNotification.

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

tableViewSelectionIsChanging:

Tells the delegate that the table view’s selection is in the process of changing.

- (void)tableViewSelectionIsChanging:(NSNotification *)aNotification
Parameters
aNotification

A notification named NSTableViewSelectionIsChangingNotification.

Discussion

This method is called only when mouse events—and not keyboard events—are changing the selection. For example, this method is called when the user drags the mouse across multiple table rows.

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