---

NSTableView Class Reference

Class at a Glance

An NSTableView object displays record-oriented data in a table and allows the user to edit values and resize and rearrange columns.

Principal Attributes

• A data source

• Table columns

Commonly Used Methods

dataSource

Returns the object providing the data that the table view displays.

tableColumns

Returns the NSTableColumn objects representing attributes for the table view.

selectedColumn

Returns the index of the selected column.

selectedRow

Returns the index of the selected row.

numberOfRows

Returns the number of rows in the table view.

reloadData

Informs the table view that data has changed and needs to be retrieved and displayed again.

Overview

An NSTableView object displays data for a set of related records, with rows representing individual records and columns representing the attributes of those records.

A table view is usually displayed in a scroll view, like this:

A table view does not store its own data, instead it retrieves data values as needed from a data source to which it has a weak reference (see Communicating With Objects). You should not, therefore, try to directly set data values programmatically in the table view; instead you should modify the values in the data source and allow the changes to be reflected in the table view. See the NSTableDataSource informal protocol, which declares the methods that an NSTableView object uses to access the contents of its data source object.

Adopted Protocols

• – validateUserInterfaceItem:

Tasks

Setting the Data Source

• – setDataSource:
• – dataSource

Loading Data

• – reloadData

Target-action Behavior

• – setDoubleAction:
• – doubleAction
• – clickedColumn
• – clickedRow

Configuring Behavior

• – setAllowsColumnReordering:
• – allowsColumnReordering
• – setAllowsColumnResizing:
• – allowsColumnResizing
• – setAllowsMultipleSelection:
• – allowsMultipleSelection
• – setAllowsEmptySelection:
• – allowsEmptySelection
• – setAllowsColumnSelection:
• – allowsColumnSelection

Setting Display Attributes

• – setIntercellSpacing:
• – intercellSpacing
• – setRowHeight:
• – rowHeight
• – setBackgroundColor:
• – backgroundColor
• – setUsesAlternatingRowBackgroundColors:
• – usesAlternatingRowBackgroundColors
• – selectionHighlightStyle
• – setSelectionHighlightStyle:
• – setGridColor:
• – gridColor
• – setGridStyleMask:
• – gridStyleMask
• – indicatorImageInTableColumn:
• – setIndicatorImage:inTableColumn:

Column Management

• – addTableColumn:
• – removeTableColumn:
• – moveColumn:toColumn:
• – tableColumns
• – columnWithIdentifier:
• – tableColumnWithIdentifier:

Selecting Columns and Rows

• – selectColumnIndexes:byExtendingSelection:
• – selectRowIndexes:byExtendingSelection:
• – selectedColumnIndexes
• – selectedRowIndexes
• – deselectColumn:
• – deselectRow:
• – numberOfSelectedColumns
• – numberOfSelectedRows
• – selectedColumn
• – selectedRow
• – isColumnSelected:
• – isRowSelected:
• – selectAll:
• – deselectAll:
• – allowsTypeSelect
• – setAllowsTypeSelect:

Table Dimensions

• – numberOfColumns
• – numberOfRows

Displaying Cell

• – tableView:willDisplayCell:forTableColumn:row:  delegate method
• – preparedCellAtColumn:row:
• – tableView:dataCellForTableColumn:row:  delegate method
• – tableView:shouldShowCellExpansion:forTableColumn:row:  delegate method
• – tableView:isGroupRow:  delegate method

Editing Cells

• – editColumn:row:withEvent:select:
• – editedColumn
• – editedRow
• – tableView:shouldEditTableColumn:row:  delegate method

Setting Auxiliary Views

• – setHeaderView:
• – headerView
• – setCornerView:
• – cornerView

Layout Support

• – rectOfColumn:
• – rectOfRow:
• – columnsInRect:
• – rowsInRect:
• – columnIndexesInRect:
• – columnAtPoint:
• – rowAtPoint:
• – frameOfCellAtColumn:row:
• – columnAutoresizingStyle
• – setColumnAutoresizingStyle:
• – sizeLastColumnToFit
• – noteNumberOfRowsChanged
• – tile
• – sizeToFit
• – noteHeightOfRowsWithIndexesChanged:
• – tableView:heightOfRow:  delegate method

Drawing

• – drawRow:clipRect:
• – drawGridInClipRect:
• – highlightSelectionInClipRect:
• – drawBackgroundInClipRect:

Scrolling

• – scrollRowToVisible:
• – scrollColumnToVisible:

Persistence

• – autosaveName
• – autosaveTableColumns
• – setAutosaveName:
• – setAutosaveTableColumns:

Selecting in the Tableview

• – selectionShouldChangeInTableView:  delegate method
• – tableView:shouldSelectRow:  delegate method
• – tableView:selectionIndexesForProposedSelection:  delegate method
• – tableView:shouldSelectTableColumn:  delegate method
• – tableViewSelectionIsChanging:  delegate method
• – tableViewSelectionDidChange:  delegate method
• – tableView:shouldTypeSelectForEvent:withCurrentSearchString:  delegate method
• – tableView:typeSelectStringForTableColumn:row:  delegate method
• – tableView:nextTypeSelectMatchFromRow:toRow:forString:  delegate method

Setting the Delegate

• – setDelegate:
• – delegate

Highlightable Column Headers

• – highlightedTableColumn
• – setHighlightedTableColumn:

Dragging

• – dragImageForRowsWithIndexes:tableColumns:event:offset:
• – canDragRowsWithIndexes:atPoint:
• – setDraggingSourceOperationMask:forLocal:
• – setDropRow:dropOperation:
• – setVerticalMotionCanBeginDrag:
• – verticalMotionCanBeginDrag

Sorting

• – setSortDescriptors:
• – sortDescriptors

Moving and Resizing Columns

• – tableView:didDragTableColumn:  delegate method
• – tableViewColumnDidMove:  delegate method
• – tableViewColumnDidResize:  delegate method

Responding to Mouse Events

• – tableView:didClickTableColumn:  delegate method
• – tableView:mouseDownInHeaderOfTableColumn:  delegate method
• – tableView:shouldTrackCell:forTableColumn:row:  delegate method

Text Delegate Methods

• – textShouldBeginEditing:
• – textDidBeginEditing:
• – textDidChange:
• – textShouldEndEditing:
• – textDidEndEditing:

Displaying Tooltips

• – tableView:toolTipForCell:rect:tableColumn:row:mouseLocation:  delegate method

Deprecated Methods

• – autoresizesAllColumnsToFit
• – drawsGrid Deprecated in Mac OS X v10.3
• – selectColumn:byExtendingSelection: Deprecated in Mac OS X v10.3
• – selectedColumnEnumerator Deprecated in Mac OS X v10.3
• – selectedRowEnumerator Deprecated in Mac OS X v10.3
• – selectRow:byExtendingSelection: Deprecated in Mac OS X v10.3
• – setDrawsGrid: Deprecated in Mac OS X v10.3
• – dragImageForRows:event:dragImageOffset: Deprecated in Mac OS X v10.4 and later
• – setAutoresizesAllColumnsToFit: Deprecated in Mac OS X v10.4 and later

Instance Methods

addTableColumn:

Adds a given column as the last column of the receiver.

- (void)addTableColumn:(NSTableColumn *)aColumn

Parameters

aColumn

The column to add to the receiver.

Availability

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

See Also

• – sizeLastColumnToFit
• – removeTableColumn:

Declared In

NSTableView.h

allowsColumnReordering

Returns a Boolean value that indicates whether the receiver allows the user to rearrange columns by dragging their headers.

- (BOOL)allowsColumnReordering

Return Value

YES to allow the user to rearrange columns by dragging their headers, otherwise NO.

Discussion

The default is YES. You can rearrange columns programmatically regardless of this setting.

Availability

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

See Also

• – moveColumn:toColumn:
• – setAllowsColumnReordering:

Declared In

NSTableView.h

allowsColumnResizing

Returns a Boolean value that indicates whether the receiver allows the user to resize columns by dragging between their headers.

- (BOOL)allowsColumnResizing

Return Value

YES if the receiver allows the user to resize columns by dragging between their headers, otherwise NO.

Discussion

The default is YES. You can resize columns programmatically regardless of this setting.

Availability

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

See Also

• – setWidth: (NSTableColumn)
• – setAllowsColumnResizing:

Declared In

NSTableView.h

allowsColumnSelection

Returns a Boolean value that indicates whether the receiver allows the user to select columns by clicking their headers.

- (BOOL)allowsColumnSelection

Return Value

YES if the receiver allows the user to select columns by clicking their headers, otherwise NO.

Discussion

The default is NO. You can select columns programmatically regardless of this setting.

Availability

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

See Also

• – selectColumn:byExtendingSelection:
• – allowsColumnReordering
• – setAllowsColumnSelection:

Declared In

NSTableView.h

allowsEmptySelection

Returns a Boolean value that indicates whether the receiver allows the user to select zero columns or rows.

- (BOOL)allowsEmptySelection

Return Value

YES if the receiver allows the user to select zero columns or rows, otherwise NO.

Discussion

The default is YES.

You cannot set an empty selection programmatically if this setting is NO, unlike with the other settings that affect selection behavior.

Availability

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

See Also

• – deselectAll:
• – deselectColumn:
• – deselectRow:
• – setAllowsEmptySelection:

Declared In

NSTableView.h

allowsMultipleSelection

Returns a Boolean value that indicates whether the receiver allows the user to select more than one column or row at a time.

- (BOOL)allowsMultipleSelection

Return Value

YES if the receiver allows the user to select more than one column or row at a time, otherwise NO.

Discussion

The default is NO. You can select multiple columns or rows programmatically regardless of this setting.

Availability

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

See Also

• – selectColumn:byExtendingSelection:
• – selectRow:byExtendingSelection:
• – setAllowsMultipleSelection:

Declared In

NSTableView.h

allowsTypeSelect

Returns a Boolean value that indicates whether the receiver allows the user to type characters to select rows.

- (BOOL)allowsTypeSelect

Return Value

YES if the receiver allows type selection, otherwise NO.

Discussion

The default value is YES.

Availability

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

See Also

• – setAllowsTypeSelect:

Declared In

NSTableView.h

autoresizesAllColumnsToFit

Returns YES if the receiver proportionally resizes its columns to fit when its superview’s frame changes, NO if it only resizes the last column. (Deprecated. Use columnAutoresizingStyle instead.)

- (BOOL)autoresizesAllColumnsToFit

Availability

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

See Also

• – columnAutoresizingStyle
• – setColumnAutoresizingStyle:

Declared In

NSTableView.h

autosaveName

Returns the name under which table information is automatically saved.

- (NSString *)autosaveName

Return Value

The name under which table information is automatically saved. If no name has been set, returns nil.

Discussion

The table information is saved separately for each user and for each application that user uses.

Note that even when a table view has an autosave name, it may not be saving table information automatically. To check whether table information is being saved automatically, use autosaveTableColumns.

Availability

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

See Also

• – autosaveTableColumns
• – setAutosaveName:

Declared In

NSTableView.h

autosaveTableColumns

Returns a Boolean value that indicates whether the order and width of the receiver’s columns are automatically saved.

- (BOOL)autosaveTableColumns

Discussion

The table information is saved separately for each user and for each application that user uses. Note that if autosaveName returns nil, this setting is ignored and table information isn’t saved.

Availability

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

See Also

• – autosaveName
• – setAutosaveTableColumns:
• – setAutosaveName:

Declared In

NSTableView.h

backgroundColor

Returns the color used to draw the background of the receiver.

- (NSColor *)backgroundColor

Return Value

The color used to draw the background of the receiver.

Discussion

The default background color is light gray.

Availability

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

See Also

• – setBackgroundColor:

Declared In

NSTableView.h

canDragRowsWithIndexes:atPoint:

Returns whether the receiver allows dragging the rows at rowIndexes with a drag initiated at mousedDownPoint.

- (BOOL)canDragRowsWithIndexes:(NSIndexSet *)rowIndexes atPoint:(NSPoint)mouseDownPoint

Discussion

Return NO to disallow the drag.

Availability

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

Declared In

NSTableView.h

clickedColumn

Returns the index of the column the user clicked to trigger an action message.

- (NSInteger)clickedColumn

Return Value

The index of the column the user clicked to trigger an action message. Returns –1 if the user clicked in an area of the table view not occupied by columns.

Discussion

The return value of this method is meaningful only in the target’s implementation of the action or double-action method.

Availability

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

See Also

• – clickedRow
• – setAction: (NSControl)
• – setDoubleAction:

Declared In

NSTableView.h

clickedRow

Returns the index of the row the user clicked to trigger an action message.

- (NSInteger)clickedRow

Return Value

The index of the row the user clicked to trigger an action message. Returns –1 if the user clicked in an area of the table view not occupied by table rows.

Discussion

The return value of this method is meaningful only in the target’s implementation of the action or double-action method.

Availability

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

See Also

• – clickedColumn
• – setAction: (NSControl)
• – setDoubleAction:

Declared In

NSTableView.h

columnAtPoint:

Returns the index of the column a given point lies in.

- (NSInteger)columnAtPoint:(NSPoint)aPoint

Parameters

aPoint

A point in the coordinate system of the receiver.

Return Value

The index of the column aPoint lies in, or –1 if aPoint lies outside the receiver’s bounds.

Availability

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

See Also

• – rowAtPoint:

Declared In

NSTableView.h

columnAutoresizingStyle

Returns the receiver’s column autoresizing style.

- (NSTableViewColumnAutoresizingStyle)columnAutoresizingStyle

Return Value

The receiver’s column autoresizing style. For possible values, see “Autoresizing Styles.”

Availability

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

See Also

• – setColumnAutoresizingStyle:

Declared In

NSTableView.h

columnIndexesInRect:

Returns the indexes of the receiver’s columns that intersect the specified rectangle.

- (