Class

NSTableView

A set of related records, displayed in rows that represent individual records and columns that represent the attributes of those records.

Declaration

@interface NSTableView : NSControl

Overview

Table views are displayed in scroll views. Beginning with macOS v10.7, you can use NSView objects (most commonly customized NSTableCellView objects) instead of cells for specifying rows and columns. You can still use NSCell objects for each row and column item if you prefer.

A table view does not store its own data; it retrieves data values as needed from a data source to which it has a weak reference. You should not, therefore, directly set data values programmatically in the table view; instead, modify the values in the data source and allow the changes to be reflected in the table view. To learn about the methods that an NSTableView object uses to provide and access the contents of its data source object, see NSTableViewDataSource.

To customize a table view’s behavior without subclassing NSTableView, use the methods defined by the NSTableViewDelegate protocol. For example, the delegate supports table column management, type-to-select functionality, row selection and editing, custom tracking, and custom views for individual columns and rows. To learn more about the table view delegate, see NSTableViewDelegate.

Subclassing

Subclassing NSTableView is usually not necessary. Instead, you customize the table view using a delegate object (an object conforming to the NSTableViewDelegate protocol) and a data source object (conforming to the NSTableViewDataSource protocol), or by subclassing one of the following subcomponents: cells (when using NSCell-based table views), the row cell view or the row view (when using NSView-based table views), the table column class, or table column header classes.

Topics

Managing the Table's Data

dataSource

The object that provides the data displayed by the table view.

usesStaticContents

A Boolean value indicating whether the table uses static data.

- reloadData

Marks the table view as needing redisplay, so it will reload the data for visible cells and draw the new values.

- reloadDataForRowIndexes:columnIndexes:

Reloads the data for only the specified rows and columns.

Creating Views to Display

- makeViewWithIdentifier:owner:

Returns a new or existing view with the specified identifier.

- rowViewAtRow:makeIfNecessary:

Returns a row view at the specified index, creating one if necessary.

- viewAtColumn:row:makeIfNecessary:

Returns a view at the specified row and column indexes, creating one if necessary.

Updating the Table View Arrangement

- beginUpdates

Begins a group of updates for the table view.

- endUpdates

Ends the group of updates for the table view.

- moveRowAtIndex:toIndex:

Moves the specified row to the new row location using animation.

- insertRowsAtIndexes:withAnimation:

Inserts the rows using the specified animation.

- removeRowsAtIndexes:withAnimation:

Removes the rows using the specified animation.

- rowForView:

Returns the index of the row for the specified view.

- columnForView:

Returns the column index for the specified view.

NSView-Based Table Nib File Registration

- registerNib:forIdentifier:

Registers a NIB for the specified identifier, so that view-based table views can use it to instantiate views.

registeredNibsByIdentifier

The dictionary of all registered nib files for view-based table view identifiers.

Target-action Behavior

doubleAction

The message sent to the table view’s target when the user double-clicks a cell or column header.

clickedColumn

The index of the column the user clicked.

clickedRow

The index of the row the user clicked.

Configuring Behavior

allowsColumnReordering

A Boolean value indicating whether the table view allows the user to rearrange columns by dragging their headers.

allowsColumnResizing

A Boolean value indicating whether the table view allows the user to resize columns by dragging between their headers.

allowsMultipleSelection

A Boolean value indicating whether the table view allows the user to select more than one column or row at a time.

allowsEmptySelection

A Boolean value indicating whether the table view allows the user to select zero columns or rows.

allowsColumnSelection

A Boolean value indicating whether the table view allows the user to select columns by clicking their headers.

Setting Display Attributes

intercellSpacing

The horizontal and vertical spacing between cells.

rowHeight

The height of each row in the table.

backgroundColor

The color used to draw the background of the table.

usesAlternatingRowBackgroundColors

A Boolean value indicating whether the table view uses alternating row colors for its background.

selectionHighlightStyle

The selection highlight style used by the table view to indicate row and column selection.

gridColor

The color used to draw grid lines.

gridStyleMask

The grid lines drawn by the table view.

- indicatorImageInTableColumn:

Returns the indicator image of the specified table column.

- setIndicatorImage:inTableColumn:

Sets the indicator image of the specified column.

Getting and Setting Row Size Styles

effectiveRowSizeStyle

The effective row size style for the table.

rowSizeStyle

The row size style (small, medium, large, or custom) used by the table view.

Column Management

- addTableColumn:

Adds the specified column as the last column of the table view.

- removeTableColumn:

Removes the specified column from the table view.

- moveColumn:toColumn:

Moves the column and heading at the specified index to the new specified index.

tableColumns

An array containing the current table column objects.

- columnWithIdentifier:

Returns the index of the first column in the table view whose identifier is equal to the specified identifier.

- tableColumnWithIdentifier:

Returns the NSTableColumn object for the first column whose identifier is equal to the specified object.

Selecting Columns and Rows

- selectColumnIndexes:byExtendingSelection:

Sets the column selection using indexes possibly extending the selection.

selectedColumn

The index of the last selected column (or the last column added to the selection).

selectedColumnIndexes

An index set containing the indexes of the selected columns.

- deselectColumn:

Deselects the column at the specified index if it’s selected.

numberOfSelectedColumns

The number of selected columns.

- isColumnSelected:

Returns a Boolean value that indicates whether the column at the specified index is selected.

- selectRowIndexes:byExtendingSelection:

Sets the row selection using indexes extending the selection if specified.

selectedRow

The index of the last selected row (or the last row added to the selection).

selectedRowIndexes

An index set containing the indexes of the selected rows.

- deselectRow:

Deselects the row at the specified index if it’s selected.

numberOfSelectedRows

The number of selected rows.

- isRowSelected:

Returns a Boolean value that indicates whether the row at the specified index is selected.

- selectAll:

Selects all rows or all columns, according to whether rows or columns were most recently selected.

- deselectAll:

Deselects all selected rows or columns if empty selection is allowed; otherwise does nothing.

Enumerating Table Rows

- enumerateAvailableRowViewsUsingBlock:

Allows the enumeration of all the table rows that are known to the table view.

Managing Type Select

allowsTypeSelect

A Boolean value indicating whether the table view allows the user to type characters to select rows.

Table Dimensions

numberOfColumns

The number of columns in the table.

numberOfRows

The number of rows in the table.

Getting and Setting Floating Rows

floatsGroupRows

A Boolean value indicating whether the table view draws grouped rows as if they are floating.

Editing Cells

- editColumn:row:withEvent:select:

Edits the cell at the specified column and row using the specified event and selection behavior.

editedColumn

The index of the column being edited.

editedRow

The index of the row being edited.

Adding and Deleting Row Views

- didAddRowView:forRow:

Invoked when a row view is added to the table.

- didRemoveRowView:forRow:

Invoked when a row view is removed from the table.

Setting Auxiliary Views

headerView

The view object used to draw headers over columns.

cornerView

The view used to draw the area to the right of the column headers and above the vertical scroller of the enclosing scroll view.

Layout Support

userInterfaceLayoutDirection

The layout direction of the user interface.

- rectOfColumn:

Returns the rectangle containing the column at the specified index.

- rectOfRow:

Returns the rectangle containing the row at the specified index.

- rowsInRect:

Returns a range of indexes for the rows that lie wholly or partially within the vertical boundaries of the specified rectangle.

- columnIndexesInRect:

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

- columnAtPoint:

Returns the index of the column the specified point lies in.

- rowAtPoint:

Returns the index of the row the specified point lies in.

- frameOfCellAtColumn:row:

Returns a rectangle locating the cell that lies at the intersection of the specified column and row.

columnAutoresizingStyle

The table view’s column autoresizing style.

- sizeLastColumnToFit

Resizes the last column so the table view fits exactly within its enclosing clip view.

- noteNumberOfRowsChanged

Informs the table view that the number of records in its data source has changed.

- tile

Properly sizes the table view and its header view and marks it as needing display.

- sizeToFit

Sizes the table view based on a uniform column autoresizing style.

- noteHeightOfRowsWithIndexesChanged:

Informs the table view that the rows specified in indexSet have changed height.

Drawing

- drawRow:clipRect:

Draws the cells for the row at rowIndex in the columns that intersect clipRect.

- drawGridInClipRect:

Draws the grid lines within the supplied rectangle.

- highlightSelectionInClipRect:

Highlights the region of the table view in the specified rectangle.

- drawBackgroundInClipRect:

Draws the background of the table view in the clip rect specified by the rectangle.

Scrolling

- scrollRowToVisible:

Scrolls the view so the specified row is visible.

- scrollColumnToVisible:

Scrolls the view so the specified column is visible.

Table Column State Persistence

autosaveTableColumns

A Boolean value indicating whether the order and width of the table view’s columns are automatically saved.

autosaveName

The name under which table information is automatically saved.

Accessing the Delegate

delegate

The table view’s delegate.

Highlightable Column Headers

highlightedTableColumn

The column highlighted in the table.

Dragging

- dragImageForRowsWithIndexes:tableColumns:event:offset:

Computes and returns an image to use for dragging.

- canDragRowsWithIndexes:atPoint:

Returns a Boolean value indicating whether the table view allows dragging the rows with the drag initiated at the specified point.

- setDraggingSourceOperationMask:forLocal:

Sets the default operation mask returned by draggingSourceOperationMaskForLocal: to mask.

verticalMotionCanBeginDrag

A Boolean value indicating whether vertical motion is treated as a drag or selection change.

draggingDestinationFeedbackStyle

The feedback style displayed when the user drags over the table view.

- setDropRow:dropOperation:

Retargets the proposed drop operation.

Sorting

sortDescriptors

The table view’s sort descriptors.

Row Actions

rowActionsVisible

A Boolean value indicating whether a table row’s actions are visible.

Hiding and Showing Table Rows

- hideRowsAtIndexes:withAnimation:

Hides the specified table rows.

- unhideRowsAtIndexes:withAnimation:

Unhides the specified table rows.

hiddenRowIndexes

The indexes of all hidden table rows.

Deprecated Methods

- dragImageForRows:event:dragImageOffset:

Computes and returns an image to use for dragging.

Deprecated
- setAutoresizesAllColumnsToFit:

Controls whether the table view proportionally resizes its columns to fit when its superview’s frame changes.

Deprecated
- autoresizesAllColumnsToFit

Returns YES if the table view proportionally resizes its columns to fit when its superview’s frame changes, NO if it only resizes the last column.

Deprecated
- selectColumn:byExtendingSelection:

Selects the column at the specified index, optionally extending any existing selection.

Deprecated
- selectRow:byExtendingSelection:

Selects a row at the specified index, optionally extending any existing selection.

Deprecated
- tableView:writeRows:toPasteboard:

Writes the specified rows to the specified pasteboard.

Deprecated
- setDrawsGrid:

Sets whether the table view draws a grid.

Deprecated
- drawsGrid

Returns a Boolean value that indicates whether the table view draws a grid.

Deprecated
- selectedColumnEnumerator

This method has been deprecated.

Deprecated
- selectedRowEnumerator

This method has been deprecated.

Deprecated
- focusedColumn

Returns the currently focused column.

Deprecated
- setFocusedColumn:

Sets the currently focused column to the specified index.

Deprecated
- shouldFocusCell:atColumn:row:

Returns whether the fully prepared cell at the specified row and column can be made the focused cell.

Deprecated
- performClickOnCellAtColumn:row:

Performs a click action on the cell at the specified row and column.

Deprecated
- preparedCellAtColumn:row:

Returns the fully prepared cell that the table view will use for drawing or processing of the specified row and column.

Deprecated
- columnsInRect:

Returns a range of indexes for the table view’s columns that lie wholly or partially within the horizontal boundaries of the specified rectangle.

Deprecated
- textShouldBeginEditing:

Queries the delegate to determine if the text should begin editing.

Deprecated
- textDidBeginEditing:

Posts an NSControlTextDidBeginEditingNotification to the default notification center.

Deprecated
- textDidChange:

Sends textDidChange: to the edited cell and posts an NSControlTextDidChangeNotification to the default notification center.

Deprecated
- textShouldEndEditing:

Validates the text object for the cell being edited by querying the delegate.queries the delegate using control:textShouldEndEditing:, returning the delegate’s response if it responds to that method.

Deprecated
- textDidEndEditing:

Updates the data source based on the newly edited value and selects another cell for editing if possible according to the character that ended editing (Return, Tab, Backtab).

Deprecated

Constants

Specifying a Custom Row View in a Nib File

View-based table view instances use NSTableViewRowKey to identify the nib file containing the template row view. You can specify a custom row view (without any code) by associating this key with the appropriate nib name in Interface Builder.

NSTableViewDraggingDestinationFeedbackStyle

These constants specify the drag styles displayed by the table view. They’re used by draggingDestinationFeedbackStyle.

NSTableViewDropOperation

NSTableView defines these constants to specify drop operations.

NSTableViewGridLineStyle

NSTableView defines these constants to specify grid styles. These constants are used by the gridStyleMask property. The mask can be either NSTableViewGridNone or it can contain either or both of the other options combined using the C bitwise OR operator.

NSTableViewColumnAutoresizingStyle

The following constants specify the autoresizing styles. These constants are used by the columnAutoresizingStyle property.

NSTableViewSelectionHighlightStyle

The following constants specify the selection highlight styles. These constants are used by the selectionHighlightStyle property.

NSTableViewAnimationOptions

Specifies the animation effects to apply when inserting or removing rows.

NSTableViewRowSizeStyle

The row size style constants define the size of the rows in the table view. They are used by the effectiveRowSizeStyle and rowSizeStyle properties. You can also query the row size in the NSTableCellView class’ property rowSizeStyle.

NSTableRowActionEdge

These constants define table row edges on which row actions are attached. They are used by the tableView:rowActionsForRow:edge: delegate method.

Notifications

NSTableViewColumnDidMoveNotification

Posted whenever a column is moved by user action in an NSTableView object.

NSTableViewColumnDidResizeNotification

Posted whenever a column is resized in an NSTableView object.

NSTableViewSelectionDidChangeNotification

Posted after an NSTableView object's selection changes.

NSTableViewSelectionIsChangingNotification

Posted as an NSTableView object's selection changes (while the mouse button is still down).

See Also

Views

NSTableCellView

A reusable container view shown for a particular cell in a table view that uses rows for content.