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.

Parameters

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.

Parameters

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.

Parameters

tableView

The table view that sent the message.

tableColumn

The table column.

row

The row index.

Return Value

YEStrue if an expansion tooltip should be displayed, NOfalse otherwise.

Discussion

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

Parameters

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.

To avoid the possibility of a hang due to unexpected recursion, don’t call geometry-calculating methods such as bounds, rectOfColumn:, or any NSTableView method that calls tile within your implementation of this method.

Declaration

Parameters

aTableView

The table view that sent the message.

Return Value

YEStrue to allow the table view to change its selection (typically a row being edited), NOfalse 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.

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.

Parameters

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.

Parameters

Return Value

YEStrue if the column reordering should be allowed, otherwise NOfalse.

Discussion

When a column is initially dragged by the user, the delegate is first called with a newColumnIndex value of -1. Returning NOfalse will disallow that column from being reordered at all. Returning YEStrue 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.

Declaration

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

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

YEStrue if the cell should be tracked, NOfalse 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.