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 | |
Overview
The NSTableViewDelegate protocol defines the optional methods implemented by delegates of NSTableView objects.
Tasks
Providing Views for Rows and Columns
Notification of Row Views Being Added or Removed.
Grouping Rows
Providing Cells for Rows and Columns
-
– tableView:willDisplayCell:forTableColumn:row: -
– tableView:dataCellForTableColumn:row: -
– tableView:shouldShowCellExpansionForTableColumn:row: -
– tableView:toolTipForCell:rect:tableColumn:row:mouseLocation:
Editing Cells
Setting Row and Column Size
Selecting Rows
-
– selectionShouldChangeInTableView: -
– tableView:shouldSelectRow: -
– tableView:selectionIndexesForProposedSelection: -
– tableView:shouldSelectTableColumn: -
– tableViewSelectionIsChanging: -
– tableViewSelectionDidChange: -
– tableView:shouldTypeSelectForEvent:withCurrentSearchString: -
– tableView:typeSelectStringForTableColumn:row: -
– tableView:nextTypeSelectMatchFromRow:toRow:forString:
Moving and Resizing Columns
-
– tableView:shouldReorderColumn:toColumn: -
– tableView:didDragTableColumn: -
– tableViewColumnDidMove: -
– tableViewColumnDidResize:
Responding to Mouse Events
Instance Methods
selectionShouldChangeInTableView:
Returns whether the selection should change.
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.htableView:dataCellForTableColumn:row:
Invoked to allow the delegate to return a custom data cell for a specified row and column.
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 (a full width cell).
If the tableColumn is non-nil, you should return a cell, and generally that will be the result of sending tableColumn a dataCellForRow: message.
This method will be invoked with a tableColumn value of nil to allow you to return a group cell–a cell that will be used to draw the entire row, acting as a separator. If you return a cell when tableColumn is nil, any implemented datasource and delegate methods must be prepared to handle a nil table column value.
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.htableView:didAddRowView:forRow:
Invoked when a row view was added at the specified row.
Parameters
- tableView
The table view that sent the message.
- rowView
The row view.
- row
The index of the row.
Discussion
This delegate method informs the application that a new row view has been added to the table. At this point, the application can add extra views, or modify properties of the row view.
Availability
- Available in OS X v10.7 and later.
Declared In
NSTableView.htableView:didClickTableColumn:
Sent when the mouse button was clicked in a table column, but the column was not dragged.
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.htableView:didDragTableColumn:
Sent at the time the mouse button goes up in tableView and tableColumn has been dragged during the time the mouse button was down.
Parameters
- tableView
The table view that sent the message.
- tableColumn
The table column.
Special Considerations
The behavior of this method on OS X v10.5 is different from prior versions. On OS X v 10.5 the dragged column is sent to the delegate. In earlier versions the table column that is 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.htableView:didRemoveRowView:forRow:
Invoked when a row view was removed at the specified row.
Parameters
- tableView
The table view that sent the message.
- rowView
The row view.
- row
The index of the row.
Discussion
This delegate method can be used to know when a row view has been removed from the table.
If the row parameter is -1 the row is being deleted from the table and is no longer a valid row, otherwise it will be a valid row that is being removed due to it being moved off screen.
Availability
- Available in OS X v10.7 and later.
Declared In
NSTableView.htableView:heightOfRow:
Returns the height of the specified 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.
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.htableView:isGroupRow:
Invoked to allow the delegate to indicate that a specified row is a group 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 view-based table views can be made to visually ‘float’ by setting the tableview 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
-
– floatsGroupRows(NSTableView Class) -
– setFloatsGroupRows:(NSTableView Class)
Declared In
NSTableView.htableView:mouseDownInHeaderOfTableColumn:
Sent to the delegate whenever the mouse button is clicked in the table view’s header column.
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.htableView:nextTypeSelectMatchFromRow:toRow:forString:
Invoked to allow the delegate to allow the delegate to modify how type selection works.
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
It is 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.htableView:rowViewForRow:
Returns the view used to display the specified 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, a NSTableRowView instance will be created and used.
Discussion
The delegate can implement this method to return a custom NSTableRowView for a particular 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 is added to the tableView.
Availability
- Available in OS X v10.7 and later.
Declared In
NSTableView.htableView:selectionIndexesForProposedSelection:
Invoked to allow the delegate to modify the proposed selection.
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.
Implementation of this method is optional. 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.htableView:shouldEditTableColumn:row:
Returns whether the cell at the specified row and column can be edited.
Parameters
- aTableView
The table view that sent the message.
- aTableColumn
The table column.
- rowIndex
The row index.
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.htableView:shouldReorderColumn:toColumn:
Sent to the delegate to allow or prohibit the specified column to be dragged to a new location.
Parameters
- tableView
The tableview 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 is not implemented, all columns are considered reorderable.
Availability
- Available in OS X v10.6 and later.
Declared In
NSTableView.htableView:shouldSelectRow:
Returns whether the table view should allow selection of the specified row.
Parameters
- aTableView
The table view that sent the message.
- rowIndex
The row index.
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.htableView:shouldSelectTableColumn:
Returns whether the specified table column can be selected.
Parameters
- aTableView
The table view that sent the message.
- aTableColumn
The table column.
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.htableView:shouldShowCellExpansionForTableColumn:row:
Invoked to allow the delegate to control cell expansion for a specific row and column.
Parameters
- tableView
The table view that sent the message.
- tableColumn
The table column.
- row
The row index.
Return Value
YES if the tooltip cell should expand, NO otherwise.
Discussion
Cell expansion can occur when the mouse hovers over the specified cell and the cell contents are unable to be fully displayed within the cell. If this method returns YES, the full cell contents will be shown in a special floating tool tip view, otherwise the content is truncated.
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.htableView:shouldTrackCell:forTableColumn:row:
Invoked to allow the delegate to control the tracking behavior for a specific cell.
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 track, NO otherwise.
Discussion
Normally, only selectable or selected cells can be tracked. If you implement this method, cells which are not selectable or selected can be tracked, and vice-versa.
For example, this allows you to have an NSButtonCell in a table which does not 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.htableView:shouldTypeSelectForEvent:withCurrentSearchString:
Invoked to allow the delegate to control type select for a specific event.
Parameters
- tableView
The table view that sent the message.
- event
The event.
- searchString
The search string or
nilif 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.htableView:sizeToFitWidthOfColumn:
Invoked to allow the delegate to provide custom sizing behavior when a column’s resize divider is double clicked.
Parameters
- tableView
The tableview 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 is 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.htableView:toolTipForCell:rect:tableColumn:row:mouseLocation:
Returns a string that is displayed as a tooltip for the specified cell in the column and row.
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 containing the tooltip. Return nil or the empty string if no tooltip is desired.
Discussion
By default, rect is computed as [cell drawingRectForBounds:cellFrame].
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.htableView:typeSelectStringForTableColumn:row:
Invoked to allow the delegate to provide an alternate text value used for type selection for a specified row and column.
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 the 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 is not implemented the string value is:
[[tableView preparedCellAtColumn:tableColumn row:row] stringValue] |
This value can be returned from the delegate method if desired.
Implementation of this method is optional.
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.htableView:viewForTableColumn:row:
Returns the view used to display the specified row and column.
Parameters
- tableView
The table view that sent the message.
- tableColumn
The table column. Will be
nilif the row is a group row.- row
The row index.
Return Value
The view to display the specified column and row. Returning nil is acceptable, and a view will not be shown at that location.
Discussion
This method is required if you wish to use NSView objects instead of NSCell objects for the cells within a table view. Cells and views can not be mixed within the same table view.
It is 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. 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. If this method is not implemented, the table will automatically call the NSTableView method makeViewWithIdentifier:owner: with the tableColumn parameter’s identifier and the table view’s delegate respectively as parameters, to attempt to reuse a previous view, or automatically unarchive a prototype associated with the table view.
The autoresizingMask 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.htableView:willDisplayCell:forTableColumn:row:
Informs the delegate that the tableview will display the specified cell at the row in the column.
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 normal 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.htableViewColumnDidMove:
Informs the delegate that a column was moved by user action in the table view.
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.htableViewColumnDidResize:
Informs the delegate that a column was resized in the table view.
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.htableViewSelectionDidChange:
Informs the delegate that the table view’s selection has changed.
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.htableViewSelectionIsChanging:
Informs the delegate that the table view’s selection is in the process of changing (typically because the user is dragging the mouse across a number of rows).
Parameters
- aNotification
A notification named
NSTableViewSelectionIsChangingNotification.
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© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-06-06)