NSTableView Class Reference

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

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.

Table views are displayed in scroll views. Beginning with OS X v 10.7 NSView instances (most commonly NSTableCellView instances or a subclass) are supported for rows and columns. Alternatively, NSCell subclass instances can be used for each row and column item.

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, 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. To learn about the methods that an NSTableView object uses to provide and access the contents of its data source object, see NSTableViewDataSource Protocol Reference.

To customize a table view’s behavior without subclassing NSTableView, you can 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 Protocol Reference.

Subclassing

Subclassing NSTableView is usually not necessary. Instead, consider customizing the table view using a delegate class (conforming to the NSTableViewDelegate Protocol protocol) or a data source class (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.

Tasks

Creating Views to Display

Setting the Data Source

Loading Data

Using Views for Row and Column Content

NSView-based Table Nib Registration

Target-action Behavior

Configuring Behavior

Setting Display Attributes

Getting and Setting Row Size Styles

Column Management

Selecting Columns and Rows

Enumerating Table Rows

Managing Type Select

Getting and Setting Column Focus

Table Dimensions

Displaying Cell

Getting and Setting Floating Rows

Editing Cells

Adding and Deleting Row Views

Setting Auxiliary Views

Layout Support

Drawing

Scrolling

Table Column State Persistence

Setting the Delegate

Highlightable Column Headers

Dragging

Sorting

Text Delegate Methods

Deprecated Methods

Instance Methods

addTableColumn:

Adds the specified column as the last column of the receiver.

- (void)addTableColumn:(NSTableColumn *)aColumn
Parameters
aColumn

The column to add to the receiver.

Availability
  • Available in OS X v10.0 and later.
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 OS X v10.0 and later.
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 OS X v10.0 and later.
See Also
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 OS X v10.0 and later.
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.

Availability
  • Available in OS X v10.0 and later.
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 OS X v10.0 and later.
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 OS X v10.5 and later.
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 will only save the table information if autosaveTableColumns returns YES.

Availability
  • Available in OS X v10.0 and later.
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
Return Value

YES if the table column order and width should be automatically saved, otherwise NO.

Discussion

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

The following information is saved: the table column width, the table column order, any applied sort descriptors, and the table column hidden state (on OS X v 10.5 and later).

Note that if autosaveName returns nil, this setting is ignored and table information isn’t saved.

Availability
  • Available in OS X v10.0 and later.
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 OS X v10.0 and later.
Declared In
NSTableView.h

beginUpdates

Begins a group of updates for the table view.

- (void)beginUpdates
Discussion

For NSView-based table views, multiple row changes—that is, insertions, deletions, and moves—are animated simultaneously by surrounding calls to those method calls with beginUpdates and endUpdates. These methods are nestable.

The selected rows are maintained during the series of insertions, deletions, moves, and scrolling. If a selected row is deleted, a selection changed notification occurs after removeRowsAtIndexes:withAnimation: is called.

It is not necessary to call beginUpdates and endUpdates if only one insertion, deletion, or move is occurring and the receiver is an NSView-based table view. When using an NSCell-based table view, you must surround any insertion, deletion, or move in an update block for animations to occur.

The main reason for doing a batch update of changes to a table view is to avoid having the table animate unnecessarily.

Note that these methods should be called to reflect changes in your model; they do not make any underlying model changes.

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

canDragRowsWithIndexes:atPoint:

Returns whether the receiver allows dragging the rows at with the drag initiated at the specified point.

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

The row indexes to drag.

mouseDownPoint

The location where the drag was initiated.

Return Value

Return NO to disallow the drag.

Availability
  • Available in 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 in the tableColumns array 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 or if the user clicked in a row that is a group separator.

Discussion

The return value of this method is meaningful in the target’s implementation of the action or double-action method. You can also use the return value to determine which contextual menu to display when the user Control-clicks in a table. Note that the clickedColumn value remains valid when the menu item sends the action message. To see an example of using clickedColumn in the implementation of a contextual menu, download the DragNDropOutlineView sample project.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
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 in the target’s implementation of the action or double-action method. You can also use the return value to determine which contextual menu to display when the user Control-clicks in a table. Note that you should check to see if clickedRow is one of the rows the user selected and if it is, perform the contextual menu operation on all of the selected rows. To see an example of using clickedRow in the implementation of a contextual menu, download the DragNDropOutlineView sample project.

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

columnAtPoint:

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

- (NSInteger)columnAtPoint:(NSPoint)aPoint
Parameters
aPoint

A point in the coordinate system of the receiver.

Return Value

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

Availability
  • Available in OS X v10.0 and later.
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 rowSizeStyle.

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

columnForView:

Returns the column index for the specified view.

- (NSInteger)columnForView:(NSView *)view
Parameters
view

The view.

Return Value

The index of the column that contains view in the tableColumns array. Returns -1 if view is not an instance of NSTableRowView or a subview of an NSTableRowView instance. In other words, if view is not in a table view, this method returns -1. (Note that this method may also return -1 when a row is being animated away, because view no longer has a valid row.)

Discussion

This method is typically called in the action method of an NSButton (or NSControl) to find out what row (and column) the action should be performed on.

The implementation is O(n) where n is the number of visible rows, so this method should generally not be called within a loop.

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

columnIndexesInRect:

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

- (NSIndexSet *)columnIndexesInRect:(NSRect)rect
Parameters
rect

The rectangle in the receiver’s coordinate system to test for column enclosure.

Return Value

New NSIndexSet object containing the indexes of the receiver’s columns that intersect with rect.

Discussion

Columns that return YES for the NSTableColumn method isHidden are excluded from the results.

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

columnWithIdentifier:

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

- (NSInteger)columnWithIdentifier:(NSString *)anObject
Parameters
anObject

A column identifier.

Return Value

The index in the tableColumns array of the first column in the receiver whose identifier is equal to anObject (when compared using isEqual:) or –1 if no columns are found with the specified identifier.

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

cornerView

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

- (NSView *)cornerView
Return Value

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

Discussion

This is by default a simple view that merely fills in its frame, but you can replace it with a custom view using setCornerView:.

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

dataSource

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

- (id<NSTableViewDataSource>)dataSource
Return Value

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

Discussion

See “Populating View-Based Table Views Programmatically” and the NSTableViewDataSource protocol specification for more information.

Availability
  • Available in OS X v10.0 and later.
See Also
  • – setDataSource:
Declared In
NSTableView.h

delegate

Returns the receiver’s delegate.

- (id<NSTableViewDelegate>)delegate
Return Value

The receiver’s delegate.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSTableView.h

deselectAll:

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

- (void)deselectAll:(id)sender
Parameters
sender

Typically the object that sent the message.

Discussion

Posts NSTableViewSelectionDidChangeNotification to the default notification center if the selection does in fact change.

As a target-action method, deselectAll: checks with the delegate before changing the selection, using selectionShouldChangeInTableView:.

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

deselectColumn:

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

- (void)deselectColumn:(NSInteger)columnIndex
Parameters
columnIndex

The index in the tableColumns array of the column to deselect.

Discussion

Deselects the column at columnIndex if it’s selected, regardless of whether empty selection is allowed.

If the selection does in fact change, this method posts NSTableViewSelectionDidChangeNotification to the default notification center.

If the indicated column was the last column selected by the user, the column nearest it effectively becomes the last selected column. In case of a tie, priority is given to the column on the left.

This method doesn’t check with the delegate before changing the selection.

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

deselectRow:

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

- (void)deselectRow:(NSInteger)rowIndex
Parameters
rowIndex

The index of the row to deselect.

Discussion

Deselects the row at rowIndex if it’s selected, regardless of whether empty selection is allowed.

If the selection does in fact change, posts NSTableViewSelectionDidChangeNotification to the default notification center.

If the indicated row was the last row selected by the user, the row nearest it effectively becomes the last selected row. In case of a tie, priority is given to the row above.

This method doesn’t check with the delegate before changing the selection.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSTableView.h

didAddRowView:forRow:

Invoked when a row view is added to the table.

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

The row view.

row

The row index.

Discussion

The subclass can implement this method to be alerted when rowView has been added to the table. At this point, the subclass can choose to add in extra views, or modify any properties of rowView. Subclasses must be sure to call super.

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

didRemoveRowView:forRow:

Invoked when a row view was removed from the table.

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

The row view.

row

The row index. The index is -1 for rows that are being deleted from the table, and no longer have a valid row; otherwise it is the valid row that is being removed due to it being moved off screen.

Discussion

The subclass can implement this method to be alerted when rowView has been removed from the table. The removed rowView may be reused by the table, so any additionally inserted views should be removed at this point. Subclasses must be sure to call super.

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

doubleAction

Returns the message sent to the target when the user double-clicks a cell or column header.

- (SEL)doubleAction
Return Value

The message the table view sends to its target when the user double-clicks a cell or a column header.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSTableView.h

draggingDestinationFeedbackStyle

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

- (NSTableViewDraggingDestinationFeedbackStyle)draggingDestinationFeedbackStyle
Return Value

The dragging feedback style. See NSTableViewDraggingDestinationFeedbackStyle for the possible values.

Discussion

The default value is NSTableViewDraggingDestinationFeedbackStyleRegular.

However, changing the selection highlight style to NSTableViewSelectionHighlightStyleSourceList automatically changes draggingDestinationFeedbackStyle to NSTableViewDraggingDestinationFeedbackStyleSourceList..

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

dragImageForRowsWithIndexes:tableColumns:event:offset:

Computes and returns an image to use for dragging.

- (NSImage *)dragImageForRowsWithIndexes:(NSIndexSet *)dragRows tableColumns:(NSArray *)tableColumns event:(NSEvent *)dragEvent offset:(NSPointPointer)dragImageOffset
Parameters
dragRows

An index set containing the row indexes that should be in the image.

tableColumns

An array of table columns that should be in the image.

dragEvent

The event that initiated the drag.

dragImageOffset

An in/out parameter specifying the offset of the cursor in the image, the default value is NSZeroPoint. Returning NSZeroPoint causes the cursor to be centered.

Return Value

An NSImage containing a custom image for the specified rows and columns participating in the drag.

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

drawBackgroundInClipRect:

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

- (void)drawBackgroundInClipRect:(NSRect)clipRect
Parameters
clipRect

The rectangle, in the table view’s coordinate system.

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

drawGridInClipRect:

Draws the grid lines within aRect, using the grid color set with setGridColor:.

- (void)drawGridInClipRect:(NSRect)aRect
Parameters
aRect

The rectangle in the table view’s coordinate system.

Discussion

This method draws a grid regardless of whether the receiver is set to draw one automatically.

Subclasses can override this method to draw grid lines other than the standard ones.

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

drawRow:clipRect:

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

- (void)drawRow:(NSInteger)rowIndex clipRect:(NSRect)clipRect
Parameters
rowIndex

The row index.

clipRect

The intersecting rectangle.

Discussion

NSCell-based table views can override this method to custom the drawing of the rows.

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

editColumn:row:withEvent:select:

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

- (void)editColumn:(NSInteger)columnIndex row:(NSInteger)rowIndex withEvent:(NSEvent *)theEvent select:(BOOL)flag
Parameters
columnIndex

The index of the column in the tableColumns array.

rowIndex

The row index.

theEvent

The event.

flag

YES if the entered contents should be selected, otherwise NO.

Discussion

This method is invoked automatically in response to user actions; you should rarely need to invoke it directly. theEvent is usually the mouse event that triggered editing; it can be nil when starting an edit programmatically.

This method scrolls the receiver so that the cell is visible, sets up the field editor, and sends editWithFrame:inView:editor:delegate:event: or, if flag is YES, selectWithFrame:inView:editor:delegate:start:length: to the field editor’s NSCell object with the NSTableView as the text delegate.

This method can be overridden to customize drawing for rowIndex when using NSCell-based table views.

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

editedColumn

Returns the index of the column being edited.

- (NSInteger)editedColumn
Return Value

If sent during editColumn:row:withEvent:select:, the index in the tableColumns array of the column being edited; otherwise –1.

Discussion

The returned value will also be –1 if there is no editing session, or the currently edited row is a "full width" row.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSTableView.h

editedRow

Returns the index of the row being edited.

- (NSInteger)editedRow
Return Value

If sent during editColumn:row:withEvent:select:, the index of the row being edited; otherwise –1.

Discussion

This method is not applicable to NSView-based table views. Instead, subviews are responsible for editing.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSTableView.h

effectiveRowSizeStyle

Returns the effective row size style for the table.

- (NSTableViewRowSizeStyle)effectiveRowSizeStyle
Return Value

The row size style for the table.

Discussion

If the rowSizeStyle is NSTableViewRowSizeStyleDefault, then this method returns the default size for this table.

The default size is currently set in the System Preferences by the user.s

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

endUpdates

Ends the group of updates for the table view.

- (void)endUpdates
Discussion

Ends the group of updates for the table view. This method, like beginUpdates, is nestable. See beginUpdates for details.

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

enumerateAvailableRowViewsUsingBlock:

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

- (void)enumerateAvailableRowViewsUsingBlock:(void (^)(NSTableRowView *rowView, NSInteger row))handler
Parameters
handler

The Block to apply to elements in the set.

The Block takes two arguments:

rowView

The view for the row.

row

The index of the row

Discussion

The enumeration includes all views in the visibleRect, however, it may also include ones that are "in flight" due to animations or other attributes of the table.

It is preferred to use this method to efficiently make changes over all views that exist in the table.

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

floatsGroupRows

Returns whether the table view will draw grouped rows as floating.

- (BOOL)floatsGroupRows
Return Value

The group float row state. The default value is YES.

Discussion

Group rows can optionally appear to float (group rows are rows that return YES when the delegate method tableView:isGroupRow: is called).

This property is encoded and decoded in the NIB.

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

focusedColumn

Returns the currently focused column.

- (NSInteger)focusedColumn
Return Value

The index of the column, or -1 if there is no focused column

Discussion

The focus interaction will always be on the selectedRow of the table. If the selectedRow is a full width cell, then focusedColumn will return 1 when focused.

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

frameOfCellAtColumn:row:

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

- (NSRect)frameOfCellAtColumn:(NSInteger)columnIndex row:(NSInteger)rowIndex
Parameters
columnIndex

The index in the tableColumns array of the column containing the cell whose rectangle you want.

rowIndex

The index of the row containing the cell whose rectangle you want.

Return Value

A rectangle locating the cell that lies at the intersection of columnIndex and rowIndex. Returns NSZeroRect if columnIndex or rowIndex is greater than the number of columns or rows in the receiver.

Discussion

You can use this method to update a single cell more efficiently than sending the table view a reloadData message using reloadDataForRowIndexes:columnIndexes:

The result of this method is used in a drawWithFrame:inView: message to the table column's data cell. You can subclass and override this method to customize the frame of a particular cell. However, never return a frame larger than the default implementation returns.

The default frame is computed to have a height equal to the rectOfRow: for rowIndex, minus the half intercellSpacing height on the top and half on the bottom. The width of frame is equal to the with of the table column minus half the intercellSpacing width on the left, and half on the right.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSTableView.h

gridColor

Returns the color used to draw grid lines.

- (NSColor *)gridColor
Return Value

The color used to draw grid lines.

Discussion

The default color is gray.

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

gridStyleMask

Returns the receiver’s grid style mask.

- (NSTableViewGridLineStyle)gridStyleMask
Return Value

The receiver’s grid style mask. Possible return values are described in “Grid styles.”

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

headerView

Returns the NSTableHeaderView object used to draw headers over columns.

- (NSTableHeaderView *)headerView
Return Value

The NSTableHeaderView object used to draw headers over columns, or nil if the receiver has no header view

Discussion

For more information, see NSTableHeaderView.

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

highlightedTableColumn

Returns the table column highlighted in the receiver.

- (NSTableColumn *)highlightedTableColumn
Return Value

The table column highlighted in the receiver.

Discussion

A highlightable column header can be used in conjunction with row selection to highlight a particular column of the table. An example of this is how the Mail application indicates the currently sorted column.

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

highlightSelectionInClipRect:

Highlights the region of the receiver in the specified rectangle.

- (void)highlightSelectionInClipRect:(NSRect)clipRect
Parameters
clipRect

The rectangle, in the table view view’s coordinate system.

Discussion

This method is invoked before drawRow:clipRect:.

NSCell-based table views can override this method to change the manner in which they highlight selections.

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

indicatorImageInTableColumn:

Returns the indicator image of the specified table column.

- (NSImage *)indicatorImageInTableColumn:(NSTableColumn *)aTableColumn
Parameters
aTableColumn

A table column in the receiver.

Discussion

An indicator image is an arbitrary (small) image that is rendered on the right side of the column header. An example of its use is in Mail to indicate the sorting direction of the currently sorted column in a mailbox.

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

insertRowsAtIndexes:withAnimation:

Inserts the rows using the specified animation.

- (void)insertRowsAtIndexes:(NSIndexSet *)indexes withAnimation:(NSTableViewAnimationOptions)animationOptions
Parameters
indexes

The final positions of the new rows to be inserted.

animationOptions

The animation displayed during the insert. See NSTableViewAnimationOptions for the possible values that can be combined using the C bitwise OR operator.

Discussion

The numberOfRows in the table view is automatically increased by the count of indexes.

Calling this method multiple times within the same beginUpdates and endUpdates block is allowed, and changes are processed incrementally.

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

intercellSpacing

Returns the horizontal and vertical spacing between cells.

- (NSSize)intercellSpacing
Return Value

The horizontal and vertical spacing between cells.

Discussion

The default spacing is (3.0, 2.0).

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

isColumnSelected:

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

- (BOOL)isColumnSelected:(NSInteger)columnIndex
Parameters
columnIndex

The index into the tableColumns array that represents the column to test.

Return Value

YES if the column at columnIndex is selected, otherwise NO.

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

isRowSelected:

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

- (BOOL)isRowSelected:(NSInteger)rowIndex
Parameters
rowIndex

The index of the row to test.

Return Value

YES if the row at rowIndex is selected, otherwise NO.

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

makeViewWithIdentifier:owner:

Returns a new or existing view with the specified identifier.

- (id)makeViewWithIdentifier:(NSString *)identifier owner:(id)owner
Parameters
identifier

The view identifier. Must not be nil.

owner

The owner of the NIB that may be loaded and instantiated to create a new view with the specified identifier.

Return Value

A view for the row.

Discussion

Typically, identifier is associated with a cell view that’s contained in a table’s nib file. When this method is called, the table view automatically instantiates the cell view with the specified owner, which is usually the table view’s delegate. (The owner is useful in setting up outlets and target/actions from the view.) Note that a cell view’s identifier must be the same as its table column’s identifier for bindings to work. If you’re using bindings, it’s recommended that you use the Automatic identifier setting in Interface Builder.

This method may also return a reused view with the same identifier that is no longer available on screen. If a view with the specified identifier can’t be instantiated from the nib file or found in the reuse queue, this method returns nil.

This method is usually called by the delegate in tableView:viewForTableColumn:row:, but it can also be overridden to provide custom views for the identifier. Note that awakeFromNib is called each time this method is called, which means that awakeFromNib is also called on owner, even though the owner is already awake.

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

moveColumn:toColumn:

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

- (void)moveColumn:(NSInteger)columnIndex toColumn:(NSInteger)newIndex
Parameters
columnIndex

The current index in the tableColumns array of the column to move.

newIndex

The new index in the tableColumns array for the moved column.

Discussion

This method posts NSTableViewColumnDidMoveNotification to the default notification center.

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

moveRowAtIndex:toIndex:

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

- (void)moveRowAtIndex:(NSInteger)oldIndex toIndex:(NSInteger)newIndex
Parameters
oldIndex

Initial row index.

newIndex

New row index.

Discussion

This is similar to removing a row at oldIndex and inserting it at newIndex, except the same view is used and simply has its position updated to the new location.

Changes happen incrementally as they are sent to the table, so as soon as this method is called the row can be considered moved. However the underlying view is not moved until endUpdates has been called.

This method can be called multiple times within the same beginUpdates and endUpdates block.

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

noteHeightOfRowsWithIndexesChanged:

Informs the receiver that the rows specified in indexSet have changed height.

- (void)noteHeightOfRowsWithIndexesChanged:(NSIndexSet *)indexSet
Parameters
indexSet

Index set of rows that have changed their height.

Discussion

If the delegate implements tableView:heightOfRow: this method immediately re-tiles the table view using the row heights the delegate provides.

For NSView-based tables, this method will animate. To turn off the animation, create an NSAnimationContext grouping and set the duration to 0. Then call this method and end the grouping.

For NSCell-based tables, this method normally doesn't animate. However, it will animate if you call it inside a beginUpdates/endUpdates block.

Availability
  • Available in OS X v10.4 and later.
Related Sample Code
Declared In
NSTableView.h

noteNumberOfRowsChanged

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

- (void)noteNumberOfRowsChanged
Discussion

This method allows the receiver to update the scrollers in its scroll view without actually reloading data into the receiver. It’s useful for a data source that continually receives data in the background over a period of time, in which case the table view can remain responsive to the user while the data is received.

See the NSTableViewDataSource protocol specification for information on the messages an NSTableView object sends to its data source.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSTableView.h

numberOfColumns

Returns the number of columns in the receiver.

- (NSInteger)numberOfColumns
Return Value

The number of columns in the receiver.

Discussion

The value returned includes table columns that are currently hidden.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSTableView.h

numberOfRows

Returns the number of rows in the receiver.

- (NSInteger)numberOfRows
Return Value

The number of rows in the receiver.

Discussion

Typically you should not ask the table view how many rows it has; instead you should interrogate the table view's data source.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSTableView.h

numberOfSelectedColumns

Returns the number of selected columns.

- (NSInteger)numberOfSelectedColumns
Return Value

The number of selected columns.

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

numberOfSelectedRows

Returns the number of selected rows.

- (NSInteger)numberOfSelectedRows
Return Value

The number of selected rows.

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

performClickOnCellAtColumn:row:

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

- (void)performClickOnCellAtColumn:(NSInteger)column row:(NSInteger)row
Parameters
column

The column of the cell.

row

The row of the cell.

Discussion

Acquires the NSTableView, copies it, invokes performClick: or performClickWithFrame:inView: (if the cell is an NSPopUpButtonCell), and then updates the data source, if required. This method does not do any checks to see if the cell is enabled.

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

preparedCellAtColumn:row:

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

- (NSCell *)preparedCellAtColumn:(NSInteger)column row:(NSInteger)row
Parameters
column

The index in the tableColumns array for which to return the appropriate cell.

row

The row index for which to return the appropriate cell.

Return Value

New NSCell subclass instance to use for the specified row and column. The value for the cell is correctly set, and the delegate method tableView:willDisplayCell:forTableColumn:row: will have been called.

Discussion

You can override this method to do any additional cell set up that is required, or invoke it to retrieve a cell that has its contents configured for the specified column and row.

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

rectOfColumn:

Returns the rectangle containing the column at the specified index.

- (NSRect)rectOfColumn:(NSInteger)columnIndex
Parameters
columnIndex

The index in the tableColumns array of a column in the receiver.

Return Value

The rectangle containing the column at columnIndex. Returns NSZeroRect if columnIndex lies outside the range of valid column indexes for the receiver.

Discussion

You can use this method to update a single column more efficiently than sending the table view a reloadData message.

[aTableView setNeedsDisplayInRect:[aTableView rectOfColumn:column]];
Availability
  • Available in OS X v10.0 and later.
Declared In
NSTableView.h

rectOfRow:

Returns the rectangle containing the row at the specified index.

- (NSRect)rectOfRow:(NSInteger)rowIndex
Return Value

The rectangle containing the row at rowIndex. Returns NSZeroRect if rowIndex lies outside the range of valid row indexes for the receiver.

Discussion

You can use this method to update a single row more efficiently than sending the table view a reloadData message.

[aTableView setNeedsDisplayInRect:[aTableView rectOfRow:row]];
Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSTableView.h

registeredNibsByIdentifier

Returns a dictionary of all registered NIBs for NSView-based table view identifiers.

- (NSDictionary *)registeredNibsByIdentifier
Return Value

A dictionary containing the identifiers and associated NIBs.

Discussion

The keys are the identifiers, and the value of each key is the NSNib instance that is registered.

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

registerNib:forIdentifier:

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

- (void)registerNib:(NSNib *)nib forIdentifier:(NSString *)identifier
Parameters
nib

The NIB containing the view.

identifier

The identifier of the view to create.

Discussion

This method registers (or associates) nib with identifier so the table can instantiate views from it when a view with identifier is requested. This method is used when makeViewWithIdentifier:owner: is called, and there was no NIB created at design time for the specified identifier. This allows dynamic loading of NIBs that can be associated with the table.

To remove a previously associated NIB for identifier, pass in nil for the nib value.

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

reloadData

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

- (void)reloadData
Discussion

This method forces a redraw of all the visible cells in the receiver. If you want to update the value in a single cell, column, or row, it is more efficient to use frameOfCellAtColumn:row:, rectOfColumn:, or rectOfRow: in conjunction with the NSView method setNeedsDisplayInRect:. If you just want to update the scroller, use noteNumberOfRowsChanged; if the height of a set of rows changes, use noteHeightOfRowsWithIndexesChanged:.

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

reloadDataForRowIndexes:columnIndexes:

Reloads the data for only the specified rows and columns.

- (void)reloadDataForRowIndexes:(NSIndexSet *)rowIndexes columnIndexes:(NSIndexSet *)columnIndexes
Parameters
rowIndexes

The indexes of the rows to update.

columnIndexes

The indexes of the columns to update.

Discussion

For cells that are visible, the appropriate dataSource and delegate methods are called and the cells are redrawn.

For tables that support variable row heights, the row height is not re-queried from the delegate; it is your responsibility to invoke noteHeightOfRowsWithIndexesChanged: if a row height change is required.

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

removeRowsAtIndexes:withAnimation:

Removes the rows using the specified animation.

- (void)removeRowsAtIndexes:(NSIndexSet *)indexes withAnimation:(NSTableViewAnimationOptions)animationOptions
Parameters
indexes

An index set containing the rows to remove.

animationOptions

The animation displayed during the insert. See NSTableViewAnimationOptions for the possible values that can be combined using the C bitwise OR operator.

Discussion

This method deletes from the table the rows represented at indexes and automatically decreases numberOfRows by the count of indexes.

The row indexes should be with respect to the current state displayed in the table view, and not the final state, because the specified rows do not exist in the final state.

Calling this method multiple times within the same beginUpdates and endUpdates block is allowed, and changes are processed incrementally.

Changes are processed incrementally as the insertRowsAtIndexes:withAnimation:, removeRowsAtIndexes:withAnimation:, and the moveRowAtIndex:toIndex: methods are called. It is acceptable to delete row 0 multiple times, as long as there is still a row available.

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

removeTableColumn:

Removes the specified column from the receiver.

- (void)removeTableColumn:(NSTableColumn *)aTableColumn
Parameters
aTableColumn

The column to remove from the receiver.

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

rowAtPoint:

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

- (NSInteger)rowAtPoint:(NSPoint)aPoint
Parameters
aPoint

A point in the coordinate system of the receiver.

Return Value

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

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

rowForView:

Returns the index of the row for the specified view.

- (NSInteger)rowForView:(NSView *)view
Parameters
view

The view.

Return Value

The index of the row corresponding to the view. Returns -1 if view is not an instance of NSTableRowView or a subview of an instance of NSTableRowView. In other words, if view is not in a table view, this method returns -1. (Note that this method may also return -1 when a row is being animated away, because view no longer has a valid row.).

Discussion

This method is typically called in the action method for an NSButton (or NSControl) to find out what row (and column) the action should be performed on.

The implementation is O(n) where n is the number of visible rows, so this method should generally not be called within a loop.

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

rowHeight

Returns the height of each row in the receiver.

- (CGFloat)rowHeight
Return Value

The height of each row in the receiver.

Discussion

The default row height is 16.0.

The rowHeight is only used if the table's rowSizeStyle is set to NSTableViewRowSizeStyleCustom.

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

rowsInRect:

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

- (NSRange)rowsInRect:(NSRect)aRect
Parameters
aRect

A rectangle in the coordinate system of the receiver.

Return Value

A range of indexes for the receiver’s rows that lie wholly or partially within the horizontal boundaries of aRect. If the width or height of aRect is 0, returns an NSRange whose length is 0.

Discussion

The location of the range is the first such row’s index, and the length is the number of rows that lie in aRect.

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

rowSizeStyle

Returns the row size used by the tableview: small, medium, large, or on a custom row by row basis.

- (NSTableViewRowSizeStyle)rowSizeStyle
Return Value

The row style style. See NSTableViewRowSizeStyle for the supported options.

Discussion

The row size style can be modified on a row by row basis by invoking the delegate method tableView:heightOfRow:, if implemented.

The rowSizeStyle defaults to NSTableViewRowSizeStyleCustom. NSTableViewRowSizeStyleCustom indicates to use the rowHeight of the table, instead of the pre-determined system values.

Generally, rowSizeStyle should always be NSTableViewRowSizeStyleCustom except for "source lists". To implement variable row heights, set the value to NSTableViewRowSizeStyleCustom and implement tableView:heightOfRow: in the delegate.

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

rowViewAtRow:makeIfNecessary:

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

- (id)rowViewAtRow:(NSInteger)row makeIfNecessary:(BOOL)makeIfNecessary
Parameters
row

The row index.

makeIfNecessary

YES if a view is required, NO if you want to update properties on a view, if one is available.

Return Value

An instance, or subclass, of NSTableRowView. Returning nil is also valid if makeIfNecessary is NO and the view did not exist.

Discussion

This method first attempts to return a currently displayed view in the visible area. If there is no visible view, and makeIfNecessary is YES, a prepared temporary view is returned. If makeIfNecessary is NO, and the view is not visible, nil is returned.

In general, makeIfNecessary should be YES if you require a resulting view, and NO if you want to update properties on a view only if it is available (generally this means it is visible).

An exception is thrown if row is not within the numberOfRows. The returned result should generally not be held onto for longer than the current run loop cycle. It’s better to call rowViewAtRow:makeIfNecessary: whenever a view is required.

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

scrollColumnToVisible:

Scrolls the view so the specified column is visible.

- (void)scrollColumnToVisible:(NSInteger)columnIndex
Parameters
columnIndex

The index of the column in the tableColumns array.

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

scrollRowToVisible:

Scrolls the view so the specified row is visible.

- (void)scrollRowToVisible:(NSInteger)rowIndex
Parameters
rowIndex

The row index.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSTableView.h

selectAll:

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

- (void)selectAll:(id)sender
Parameters
sender

Typically the object that sent the message.

Discussion

If the table allows multiple selection, this action method selects all rows or all columns, according to whether rows or columns were most recently selected. If nothing has been recently selected, this method selects all rows. If this table doesn’t allow multiple selection, this method does nothing.

If the selection does change, this method posts NSTableViewSelectionDidChangeNotification to the default notification center.

As a target-action method, selectAll: checks with the delegate before changing the selection.

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

selectColumnIndexes:byExtendingSelection:

Sets the column selection using indexes possibly extending the selection.

- (void)selectColumnIndexes:(NSIndexSet *)indexes byExtendingSelection:(BOOL)extend
Parameters
indexes

The column indexes to select.

extend

YES if the selection should be extended, NO if the current selection should be changed.

Discussion

Replaces the deprecated selectColumn:byExtendingSelection: method.

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

selectedColumn

Returns the index of the last column selected or added to the selection.

- (NSInteger)selectedColumn
Return Value

The index of the last column selected or added to the selection, or –1 if no column is selected.

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

selectedColumnIndexes

Returns an index set containing the indexes of the selected columns.

- (NSIndexSet *)selectedColumnIndexes
Return Value

An index set containing the indexes of the selected columns.

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

selectedRow

Returns the index of the last row selected or added to the selection.

- (NSInteger)selectedRow
Return Value

The index of the last row selected or added to the selection, or –1 if no row is selected.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSTableView.h

selectedRowIndexes

Returns an index set containing the indexes of the selected rows.

- (NSIndexSet *)selectedRowIndexes
Return Value

An index set containing the indexes of the selected rows.

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

selectionHighlightStyle

Returns the selection highlight style used by the receiver to indicate row and column selection.

- (NSTableViewSelectionHighlightStyle)selectionHighlightStyle
Return Value

The selection highlight style used by the receiver to use to indicate row and column selection. See NSTableViewSelectionHighlightStyle for the possible values.

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

selectRowIndexes:byExtendingSelection:

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

- (void)selectRowIndexes:(NSIndexSet *)indexes byExtendingSelection:(BOOL)extend
Parameters
indexes

The indexes to select.

extend

YES if the selection should be extended, NO if the current selection should be changed.

Discussion

Replaces the deprecated selectRow:byExtendingSelection: method.

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

setAllowsColumnReordering:

Controls whether the user can drag column headers to reorder columns.

- (void)setAllowsColumnReordering:(BOOL)flag
Parameters
flag

YES to allow the user to reorder columns, otherwise NO.

Discussion

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

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

setAllowsColumnResizing:

Controls whether the user can resize columns by dragging between headers.

- (void)setAllowsColumnResizing:(BOOL)flag
Parameters
flag

YES to allow the user to resize columns, otherwise NO.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSTableView.h

setAllowsColumnSelection:

Controls whether the user can select an entire column by clicking its header.

- (void)setAllowsColumnSelection:(BOOL)flag
Parameters
flag

YES to allow the user to select columns, otherwise NO.

Discussion

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

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

setAllowsEmptySelection:

Controls whether the receiver allows zero rows or columns to be selected.

- (void)setAllowsEmptySelection:(BOOL)flag
Parameters
flag

YES if an empty selection is allowed, otherwise NO.

Discussion

The default is YES.

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

setAllowsMultipleSelection:

Controls whether the user can select more than one row or column at a time.

- (void)setAllowsMultipleSelection:(BOOL)flag
Parameters
flag

YES to allow the user to select multiple rows or columns, otherwise NO.

Discussion

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

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

setAllowsTypeSelect:

Sets whether the receiver allows the user to type characters to select rows.

- (void)setAllowsTypeSelect:(BOOL)value
Parameters
value

YES if the receiver allows type selection, otherwise NO.

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

setAutosaveName:

Sets the name under which table information is automatically saved to name.

- (void)setAutosaveName:(NSString *)name
Parameters
name

The autosave name.

Discussion

If name is different from the current name, this method also reads in the saved information and sets the order and width of this table view’s columns to match. Setting nil as the name value will attempt to remove any previously stored state from the user defaults.

The table information is saved separately for each user and for each application that user uses. Note that even though a table view has an autosave name, it will only save table information if setAutosaveTableColumns: is set to YES.

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

setAutosaveTableColumns:

Sets whether the order and width of this table view’s columns are automatically saved.

- (void)setAutosaveTableColumns:(BOOL)flag
Parameters
flag

YES if the order and width of this table view’s columns are automatically saved, otherwise NO.

Discussion

If autosaveName returns nil, this setting is ignored and table information isn’t saved.

If flag is different from the current value, this method also reads in the saved information and sets the table options to match.

The following information is saved: the table column width, the table column order, any applied sort descriptors, and the table column hidden state (on OS X v 10.5 and later).

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

setBackgroundColor:

Sets the receiver’s background color to the specified color.

- (void)setBackgroundColor:(NSColor *)aColor
Parameters
aColor

The background color for the receiver.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSTableView.h

setColumnAutoresizingStyle:

Sets the column autoresizing style of the receiver to the specified style.

- (void)setColumnAutoresizingStyle:(NSTableViewColumnAutoresizingStyle)style
Parameters
style

The column autoresizing style for the receiver. For possible values, see rowSizeStyle.

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

setCornerView:

Sets the receiver’s corner view to the specified view.

- (void)setCornerView:(NSView *)aView
Parameters
aView

The corner view for the receiver.

Discussion

The default corner view merely draws a bezeled rectangle using a blank NSTableHeaderCell object, but you can replace it with a custom view that displays an image or with a control that can handle mouse events, such as a Select All button. Your custom corner view should be as wide as a vertical NSScroller object and as tall as the receiver’s header view.

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

setDataSource:

Sets the receiver’s data source to the specified object.

- (void)setDataSource:(id<NSTableViewDataSource>)anObject
Parameters
anObject

The data source for the receiver, which must implement the appropriate methods of the NSTableViewDataSource protocol.

Discussion

In a managed memory environment, the receiver maintains a weak reference to the data source (that is, it does not retain the data source, see “Communicating with Objects”). After setting the data source, this method invokes tile.

This method raises an NSInternalInconsistencyException if the delegate doesn’t respond to either numberOfRowsInTableView: or tableView:objectValueForTableColumn:row:.

Availability
  • Available in OS X v10.0 and later.
See Also
  • – dataSource
Declared In
NSTableView.h

setDelegate:

Sets the receiver’s delegate to the specified object.

- (void)setDelegate:(id<NSTableViewDelegate>)anObject
Parameters
anObject

The delegate for the receiver. The delegate must conform to the NSTableViewDelegate Protocol protocol.

Discussion

In a managed memory environment, the receiver maintains a weak reference to the delegate (that is, it does not retain the delegate, see “Communicating with Objects”).

Setting the delegate will implicitly reload the table view.

Special Considerations

When you call the tableview’s setDelegate: method, the delegate is automatically registered for the following notifications with the following delegate methods:

Setting the delegate to nil will cause these notifications to be disconnected. Rather than setting the delegate to nil and listening for notifications (and expecting NSTableView to still function correctly) you should instead implement the appropriate delegate method.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSTableView.h

setDoubleAction:

Sets the message selector sent to the target when the user double-clicks a cell or column header.

- (void)setDoubleAction:(SEL)aSelector
Parameters
aSelector

The message the table view sends to its target when the user double-clicks a cell or a column header.

Discussion

If the double action is set, double-clicking always invokes the selector. If the double action is not set, then the cell will edit after a delay.

The clickedRow and clickedColumn methods allow you to determine which row and column the double-click occurred in or if, rather than in a row, the double-click occurred in a column heading.

Note that if the table view uses Cocoa bindings and the Double Click Target binding is bound, both messages are invoked on their respective targets: First the Cocoa binding message is sent, then the setDoubleAction: message.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSTableView.h

setDraggingDestinationFeedbackStyle:

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

- (void)setDraggingDestinationFeedbackStyle:(NSTableViewDraggingDestinationFeedbackStyle)style
Parameters
style

The dragging feedback style. See NSTableViewDraggingDestinationFeedbackStyle for the possible values.

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

setDraggingSourceOperationMask:forLocal:

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

- (void)setDraggingSourceOperationMask:(NSDragOperation)mask forLocal:(BOOL)isLocal
Parameters
mask

The drag operation mask. See NSDragOperation for the supported values.

isLocal

YES if the destination is the same application, otherwise NO. In either case the specified mask value is archived and used.

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

setDropRow:dropOperation:

Retargets the proposed drop operation.

- (void)setDropRow:(NSInteger)row dropOperation:(NSTableViewDropOperation)operation
Parameters
row

The target row index.

operation

The drop operation. Supported values are specified by NSTableViewDropOperation.

Discussion

For example, to specify a drop on the second row, specify row as 1, and operation as NSTableViewDropOn. To specify a drop below the last row, specify row as [self numberOfRows] and operation as NSTableViewDropAbove.

Passing a value of –1 for row, and NSTableViewDropOn as the operation causes the entire table view to be highlighted rather than a specific row. This is useful if the data displayed by the receiver does not allow the user to drop items at a specific row location.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
  • iSpend
  • With and Without Bindings
Declared In
NSTableView.h

setFloatsGroupRows:

Sets whether the table view will draw grouped rows as floating.

- (void)setFloatsGroupRows:(BOOL)value
Parameters
value

The group float state. The default value is YES.

Discussion

Group rows can optionally appear to float. Group rows are rows that return YES when the the delegate method tableView:isGroupRow: is invoked.

This property is encoded and decoded in the NIB.

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

setFocusedColumn:

Sets the currently focused column to the specified index.

- (void)setFocusedColumn:(NSInteger)focusedColumn
Parameters
focusedColumn

The index of the column to focus, or -1 if there should be no focused column.

Discussion

This method will redisplay the previously focused column and (if required) the new focusedColumn.

The focused column has a focus ring drawn around the selectedRow that intersects with focusedColumn.

You should not override this method.

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

setGridColor:

Sets the color used to draw grid lines to the specified color.

- (void)setGridColor:(NSColor *)aColor
Parameters
aColor

The color to use to draw grid lines.

Discussion

The default color is gray.

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

setGridStyleMask:

Sets the grid style mask to specify if no grid lines, vertical grid lines, or horizontal grid lines should be displayed.

- (void)setGridStyleMask:(NSTableViewGridLineStyle)gridType
Parameters
gridType

The grid style mask. Possible values for gridType are described in “Grid styles.”

Availability
  • Available in OS X v10.3 and later.
Related Sample Code
Declared In
NSTableView.h

setHeaderView:

Sets the receiver’s header view to the specified header view.

- (void)setHeaderView:(NSTableHeaderView *)aHeaderView
Parameters
aHeaderView

The header view for the receiver.

Discussion

If aHeaderView is nil, the current header view is removed.

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

setHighlightedTableColumn:

Sets aTableColumn to be the currently highlighted column header.

- (void)setHighlightedTableColumn:(NSTableColumn *)aTableColumn
Parameters
aTableColumn

The table column to highlight.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSTableView.h

setIndicatorImage:inTableColumn:

Sets the indicator image of the specified column.

- (void)setIndicatorImage:(NSImage *)anImage inTableColumn:(NSTableColumn *)aTableColumn
Parameters
anImage

The indicator image for the column.

aTableColumn

The table column.

Discussion

The default sorting order indicators are available as named NSImage objects. These images are accessed using [NSImage imageNamed:] passing either @"NSAscendingSortIndicator" (the "^" icon), and @"NSDescendingSortIndicator" (the "v" icon).

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSTableView.h

setIntercellSpacing:

Sets the width and height between cells to those in the specified NSSize struct.

- (void)setIntercellSpacing:(NSSize)aSize
Parameters
aSize

An NSSize struct that defines the width and height between cells in the receiver.

Discussion

The receiver redisplays after the new value is set.

The default intercell spacing is (3.0, 2.0).

Table views normally have a 1 pixel separation between consecutively selected rows or columns. An intercell spacing of (1.0, 1.0) or greater is required if you want this separation. An intercell spacing of (0.0, 0.0) forces there to be no separation between consecutive selections.

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

setRowHeight:

Sets the height for rows to the specified value.

- (void)setRowHeight:(CGFloat)rowHeight
Parameters
rowHeight

The height for rows.

Discussion

After the height is set, this method invokes tile.

The rowHeight is only used if the table's rowSizeStyle is set to NSTableViewRowSizeStyleCustom.

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

setRowSizeStyle:

Sets the row size used by the tableview: small, medium, large, or on a custom row by row basis.

- (void)setRowSizeStyle:(NSTableViewRowSizeStyle)rowSizeStyle
Parameters
rowSizeStyle

The row style style. See NSTableViewRowSizeStyle for the supported options.

Discussion

If the row size style is NSTableViewRowSizeStyleCustom, it will use the rowHeight specified.

The row size style can be modified on a row by row basis by implanting the delegate method tableView:heightOfRow:.

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

setSelectionHighlightStyle:

Sets the selection highlight style used by the receiver to indicate row and column selection.

- (void)setSelectionHighlightStyle:(NSTableViewSelectionHighlightStyle)selectionHighlightStyle
Parameters
selectionHighlightStyle

The selection highlight style to use to indicate row and column selection. See NSTableViewSelectionHighlightStyle for the possible values.

Discussion

Setting the selection highlight style to Subclassing causes the receiver to draw its background using the source list style. It also sets the draggingDestinationFeedbackStyle to NSTableViewDraggingDestinationFeedbackStyleSourceList.

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

setSortDescriptors:

Sets the receiver’s sort descriptors.

- (void)setSortDescriptors:(NSArray *)array
Parameters
array

An array of NSSortDescriptor objects.

Discussion

A table column is considered sortable if it has a sort descriptor that specifies the sorting direction, a key to sort by, and a selector defining how to sort.

The array of sort descriptors is archived. Sort descriptors persist along with other column information if an autosave name is set.

Calling setSortDescriptors: may have the side effect of invoking the data source method tableView:sortDescriptorsDidChange:.

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

setUsesAlternatingRowBackgroundColors:

Sets whether the receiver uses the standard alternating row colors for its background.

- (void)setUsesAlternatingRowBackgroundColors:(BOOL)useAlternatingRowColors
Parameters
useAlternatingRowColors

YES to specify standard alternating row colors for the background, NO to specify a solid color.

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

setVerticalMotionCanBeginDrag:

Sets whether vertical motion is treated as a drag or selection change to flag.

- (void)setVerticalMotionCanBeginDrag:(BOOL)flag
Parameters
flag

YES if a vertical drag motion can begin a drag, otherwise NO.

Discussion

The default is YES. In this case a vertical drag will drag-select rows.

Note that horizontal motion is always a valid motion to begin a drag. Most often, you would want to disable vertical dragging when it’s expected that horizontal dragging is the natural motion.

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

shouldFocusCell:atColumn:row:

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

- (BOOL)shouldFocusCell:(NSCell *)cell atColumn:(NSInteger)column row:(NSInteger)row
Parameters
cell

The prepared cell to be focused upon.

column

The column of the cell.

row

The row of the cell.

Return Value

YES if the cell can be made the focused cell, otherwise NO.

Discussion

By default, only cells that are enabled can be focused. In addition, if the cell is an NSTextFieldCell, it can only be focused if it is selectable or editable, and the table view delegate responds YES to -tableView:shouldEditTableColumn:row:.

Subclasses can override this to further control which cells can and can’t be made focused.

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

sizeLastColumnToFit

Resizes the last column if there’s room so the receiver fits exactly within its enclosing clip view.

- (void)sizeLastColumnToFit
Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSTableView.h

sizeToFit

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

- (void)sizeToFit
Discussion

All columns are resized to the same size, up to a column's maximum size. This method then invokes tile.

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

sortDescriptors

Returns the receiver’s sort descriptors.

- (NSArray *)sortDescriptors
Return Value

Returns the table view’s array of NSSortDescriptor objects.

Availability
  • Available in OS X v10.3 and later.
Related Sample Code
Declared In
NSTableView.h

tableColumns

Returns an array containing the the NSTableColumn objects in the receiver.

- (NSArray *)tableColumns
Return Value

An array containing the the NSTableColumn objects in the receiver.

Discussion

The array returned by tableColumns contains all receiver’s columns, including those that are hidden.

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

tableColumnWithIdentifier:

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

- (NSTableColumn *)tableColumnWithIdentifier:(NSString *)anObject
Parameters
anObject

A column identifier.

Return Value

The NSTableColumn object for the first column whose identifier is equal to anObject, as compared using isEqual:, or nil if no columns are found with the specified identifier.

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

textDidBeginEditing:

Posts an NSControlTextDidBeginEditingNotification to the default notification center.

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

The notification posted by the field editor; see the NSText class specifications for more information on this text delegate method.

Discussion

For more details, see the NSControl class specification.

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

textDidChange:

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

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

The notification posted by the field editor.

Discussion

See the NSText class specification for more information on this text delegate method. For additional details, see the NSControl class specification.

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

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

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

The notification posted by the field editor.

Discussion

See the NSText class specification for more information on this text delegate method.

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

textShouldBeginEditing:

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

- (BOOL)textShouldBeginEditing:(NSText *)textObject
Parameters
textObject

The text object

Return Value

YES if editing of the text should begin, otherwise NO. Returns YES if the delegate does not implement control:textShouldBeginEditing:.

Discussion

See the NSText class specification for more information on this text delegate method.

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

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.

- (BOOL)textShouldEndEditing:(NSText *)textObject
Parameters
textObject

The NSText object for the cell.

Return Value

Returns the value of the delegate’s implementation of control:textShouldEndEditing:. If the delegate does not implement the method, returns YES if the cell’s new value is valid, otherwise NO.

Discussion

See the NSText class specification for more information on this text delegate method.

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

tile

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

- (void)tile
Discussion

Also resets cursor rectangles for the header view and line scroll amounts for the NSScrollView object.

Generally for performance it is not recommend to call this method. Instead, the table will call it automatically when necessary.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSTableView.h

usesAlternatingRowBackgroundColors

Returns a Boolean value that indicates whether the receiver uses the standard alternating row colors for its background.

- (BOOL)usesAlternatingRowBackgroundColors
Return Value

YES if the receiver uses standard alternating row colors for the background, NO if it uses a solid color.

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

verticalMotionCanBeginDrag

Returns whether vertical motion is treated as a drag or selection change.

- (BOOL)verticalMotionCanBeginDrag
Return Value

YES if a vertical drag motion can begin a drag, otherwise NO.

Discussion

The default is YES. In this case a vertical drag will drag-select rows.

Note that horizontal motion is always a valid motion to begin a drag.

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

viewAtColumn:row:makeIfNecessary:

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

- (id)viewAtColumn:(NSInteger)column row:(NSInteger)row makeIfNecessary:(BOOL)makeIfNecessary
Parameters
column

The index of the column in the tableColumns array.

row

The row index.

makeIfNecessary

YES if a view is required, NO if you want to update properties on a view, if one is available.

Return Value

An instance of NSView.

Discussion

This method first attempts to return an available view, which is generally in the visible area. If there is no available view, and makeIfNecessary is YES, a prepared temporary view is returned. If makeIfNecessary is NO, and the view is not available, nil will be returned.

In general, makeIfNecessary should be YES if you require a resulting view, and NO if you only want to update properties on a view only if it is available (generally this means it is visible).

An exception will be thrown if row is not within the numberOfRows. The returned result should generally not be held onto for longer than the current run loop cycle. Instead they should re-query the table view for the row view.

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

Constants

Specifying a Custom Row View In a NIB

The NSTableViewRowViewKey is the key that NSView-based table view instances use to identify the NIB 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.

NSString *const NSTableViewRowViewKey;
Constants
NSTableViewRowViewKey

The key associated with the identifier in the NIB containing the template row view.

Available in OS X v10.7 and later.

Declared in NSTableView.h.

Special Considerations

This constant is only applicable to NSView-based table views.

NSTableViewDraggingDestinationFeedbackStyle

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

enum {
   NSTableViewDraggingDestinationFeedbackStyleNone = -1,
   NSTableViewDraggingDestinationFeedbackStyleRegular = 0,
   NSTableViewDraggingDestinationFeedbackStyleSourceList = 1,
   NSTableViewDraggingDestinationFeedbackStyleGap = 2
};
#endif
typedef NSInteger NSTableViewDraggingDestinationFeedbackStyle;
Constants
NSTableViewDraggingDestinationFeedbackStyleNone

Provides no feedback when the user drags over the table view. This option exists to allow subclasses to implement their dragging destination highlighting, or to make it not show anything all.

Available in OS X v10.6 and later.

Declared in NSTableView.h.

NSTableViewDraggingDestinationFeedbackStyleRegular

Draws a solid round-rect background on drop target rows, and an insertion marker between rows. This style should be used in most cases.

Available in OS X v10.6 and later.

Declared in NSTableView.h.

NSTableViewDraggingDestinationFeedbackStyleSourceList

Draws an outline on drop target rows, and an insertion marker between rows. This style will automatically be set for source lists when the table’s setSelectionHighlightStyle: is set to NSTableViewDraggingDestinationFeedbackStyleSourceList. This is the standard look for Source Lists, but may be used in other areas as needed.

Available in OS X v10.6 and later.

Declared in NSTableView.h.

NSTableViewDraggingDestinationFeedbackStyleGap

Provides a gap insertion when dragging over the table. Note that this style is only officially supported for NSView-based table views, but may partially work in Cell Based TableViews. The decision to use the gap style (compared to another style) can be made in tableView:draggingSession:willBeginAtPoint:forRowIndexes:, or it can dynamically be changed.

Available in OS X v10.9 and later.

Declared in NSTableView.h.

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

NSTableViewDropOperation

NSTableView defines these constants to specify drop operations.

enum {
   NSTableViewDropOn,
   NSTableViewDropAbove
};
typedef NSUInteger NSTableViewDropOperation;
Constants
NSTableViewDropOn

Specifies that the drop should occur on the specified row.

Available in OS X v10.0 and later.

Declared in NSTableView.h.

NSTableViewDropAbove

Specifies that the drop should occur above the specified row.

Available in OS X v10.0 and later.

Declared in NSTableView.h.

Discussion

For example, given a table with n rows (numbered with row 0 at the top visually), a row of n–1 and operation of NSTableViewDropOn would specify a drop on the last row. To specify a drop below the last row, you use a row of n and NSTableViewDropAbove for the operation.

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

Grid styles

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

enum {
   NSTableViewGridNone                    = 0,
   NSTableViewSolidVerticalGridLineMask   = 1 << 0,
   NSTableViewSolidHorizontalGridLineMask = 1 << 1,
   NSTableViewDashedHorizontalGridLineMask = 1 << 3,
};
typedef NSUInteger NSTableViewGridLineStyle;
Constants
NSTableViewGridNone

Specifies that no grid lines should be displayed.

Available in OS X v10.3 and later.

Declared in NSTableView.h.

NSTableViewSolidVerticalGridLineMask

Specifies that vertical grid lines should be displayed.

Available in OS X v10.3 and later.

Declared in NSTableView.h.

NSTableViewSolidHorizontalGridLineMask

Specifies that horizontal grid lines should be displayed.

Available in OS X v10.3 and later.

Declared in NSTableView.h.

NSTableViewDashedHorizontalGridLineMask

Specifies that the horizontal grid lines should be drawn dashed.

Available in OS X v10.7 and later.

Declared in NSTableView.h.

NSTableViewColumnAutoresizingStyle

The following constants specify the autoresizing styles. These constants are used by columnAutoresizingStyle and setColumnAutoresizingStyle:.

enum {
   NSTableViewNoColumnAutoresizing = 0,
   NSTableViewUniformColumnAutoresizingStyle,
   NSTableViewSequentialColumnAutoresizingStyle,
   NSTableViewReverseSequentialColumnAutoresizingStyle,
   NSTableViewLastColumnOnlyAutoresizingStyle,
   NSTableViewFirstColumnOnlyAutoresizingStyle
};
typedef NSUInteger NSTableViewColumnAutoresizingStyle;
Constants
NSTableViewNoColumnAutoresizing

Disable table column autoresizing.

Available in OS X v10.4 and later.

Declared in NSTableView.h.

NSTableViewUniformColumnAutoresizingStyle

Autoresize all columns by distributing space equally, simultaneously.

Available in OS X v10.4 and later.

Declared in NSTableView.h.

NSTableViewSequentialColumnAutoresizingStyle

Autoresize each table column sequentially, from the last auto-resizable column to the first auto-resizable column; proceed to the next column when the current column has reached its minimum or maximum size.

Available in OS X v10.4 and later.

Declared in NSTableView.h.

NSTableViewReverseSequentialColumnAutoresizingStyle

Autoresize each table column sequentially, from the first auto-resizable column to the last auto-resizable column; proceed to the next column when the current column has reached its minimum or maximum size.

Available in OS X v10.4 and later.

Declared in NSTableView.h.

NSTableViewLastColumnOnlyAutoresizingStyle

Autoresize only the last table column.

When that table column can no longer be resized, stop autoresizing. Normally you should use one of the sequential autoresizing modes instead.

Available in OS X v10.4 and later.

Declared in NSTableView.h.

NSTableViewFirstColumnOnlyAutoresizingStyle

Autoresize only the first table column.

When that table column can no longer be resized, stop autoresizing. Normally you should use one of the sequential autoresizing modes instead.

Available in OS X v10.4 and later.

Declared in NSTableView.h.

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

NSTableViewSelectionHighlightStyle

The following constants specify the selection highlight styles. These constants are used by setSelectionHighlightStyle: and selectionHighlightStyle.

   
enum {
   NSTableViewSelectionHighlightStyleNone = -1,
   NSTableViewSelectionHighlightStyleRegular = 0,
   NSTableViewSelectionHighlightStyleSourceList = 1,
};
typedef NSInteger NSTableViewSelectionHighlightStyle;
Constants
NSTableViewSelectionHighlightStyleNone

Displays no highlight style at all.

Available in OS X v10.6 and later.

Declared in NSTableView.h.

NSTableViewSelectionHighlightStyleRegular

The regular highlight style of NSTableView. On OS X v10.7 a light blue (returned by sending NSColor a alternateSelectedControlColor message) or light gray color (returned by sending NSColor a secondarySelectedControlColor message).

Available in OS X v10.5 and later.

Declared in NSTableView.h.

NSTableViewSelectionHighlightStyleSourceList

The source list style of NSTableView. On 10.5, a light blue gradient is used to highlight selected rows.

Note: When using this style, cell subclasses that implement drawsBackground must set the value to NO. Otherwise, the cells will draw over the tableview’s highlighting.

Available in OS X v10.5 and later.

Declared in NSTableView.h.

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

No Animation Effects

Specifies that no animation effect should be used by the table. This constant is used by the methods insertRowsAtIndexes:withAnimation: and removeRowsAtIndexes:withAnimation:.

enum {
   NSTableViewAnimationEffectNone = 0x0,
};
Constants
NSTableViewAnimationEffectNone

Specifies no animation effect should be used. Specifying any animation negates this effect.

Available in OS X v10.7 and later.

Declared in NSTableView.h.

Row Animation Effects

Optional constant that specifies that the tableview will use a fade for row or column removal. The effect can be combined with any NSTableViewAnimationOptions constant.

enum {
   NSTableViewAnimationEffectFade = 0x1,
   NSTableViewAnimationEffectGap = 0x2,
};
Constants
NSTableViewAnimationEffectFade

Specifies that the tableview will use a fade for row or column removal. The effect can be combined with any NSTableViewAnimationOptions constant.

Available in OS X v10.7 and later.

Declared in NSTableView.h.

NSTableViewAnimationEffectGap

Creates a gap for newly inserted rows. This is useful for drag and drop animations that animate to a newly opened gap and should be used in the delegate method tableView:acceptDrop:row:dropOperation:.

Available in OS X v10.7 and later.

Declared in NSTableView.h.

NSTableViewAnimationOptions

Optional animation slide effects used when inserting or removing rows. Currently only a single option may be selected. This effect can be combined with the “Row Animation Effects” constants. This constant is used by the methods Getting and Setting Row Size Styles and Column Management.

enum {
   NSTableViewAnimationSlideUp = 0x10,
   NSTableViewAnimationSlideDown = 0x20,
   NSTableViewAnimationSlideLeft = 0x30,
   NSTableViewAnimationSlideRight = 0x40,
};
typedef NSUInteger NSTableViewAnimationOptions;
Constants
NSTableViewAnimationSlideUp

Animates a row insertion or removal by sliding upward.

Available in OS X v10.7 and later.

Declared in NSTableView.h.

NSTableViewAnimationSlideDown

Animates a row insertion or removal by sliding downward.

Available in OS X v10.7 and later.

Declared in NSTableView.h.

NSTableViewAnimationSlideLeft

Animates a row insertion by sliding from the left. Animates a row removal by sliding towards the left.

Available in OS X v10.7 and later.

Declared in NSTableView.h.

NSTableViewAnimationSlideRight

Animates a row insertion by sliding from the right. Animates a row removal by sliding towards the right.

Available in OS X v10.7 and later.

Declared in NSTableView.h.

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

NSTableViewRowSizeStyle

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

enum {
   NSTableViewRowSizeStyleDefault = -1,
   NSTableViewRowSizeStyleCustom = 0,
   NSTableViewRowSizeStyleSmall = 1,
   NSTableViewRowSizeStyleMedium = 2,
   NSTableViewRowSizeStyleLarge = 3,
};
typedef NSInteger NSTableViewRowSizeStyle;
Constants
NSTableViewRowSizeStyleDefault

The table will use the system default layout size: small, medium or large.

Available in OS X v10.7 and later.

Declared in NSTableView.h.

NSTableViewRowSizeStyleCustom

The table will use the rowHeight or invoke the delegate method tableView:heightOfRow:, if implemented. The cell layout is not changed.

Available in OS X v10.7 and later.

Declared in NSTableView.h.

NSTableViewRowSizeStyleSmall

The table will use a row height specified for a small table. It is required that the size be fully tested and supported if NSTableViewRowSizeStyleCustom is not used.

Available in OS X v10.7 and later.

Declared in NSTableView.h.

NSTableViewRowSizeStyleMedium

The table will use a row height specified for a medium table. It is required that the size be fully tested and supported if NSTableViewRowSizeStyleCustom is not used.

Available in OS X v10.7 and later.

Declared in NSTableView.h.

NSTableViewRowSizeStyleLarge

The table will use a row height specified for a large table. It is required that the size be fully tested and supported if NSTableViewRowSizeStyleCustom is not used.

Available in OS X v10.7 and later.

Declared in NSTableView.h.

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

Notifications

NSTableViewColumnDidMoveNotification

Posted whenever a column is moved by user action in an NSTableView object. The notification object is the table view in which a column moved. The userInfo dictionary contains the following information:

Key

Value

@"NSOldColumn"

An NSNumber object containing the integer value of the column’s original index.

@"NSNewColumn"

An NSNumber object containing the integer value of the column’s present index.

Availability
See Also
Declared In
NSTableView.h

NSTableViewColumnDidResizeNotification

Posted whenever a column is resized in an NSTableView object. The notification object is the table view in which a column was resized. The userInfo dictionary contains the following information:

Key

Value

@"NSTableColumn"

The column that was resized.

@"NSOldWidth"

An NSNumber containing the integer value of the column’s original width.

Availability
Declared In
NSTableView.h

NSTableViewSelectionDidChangeNotification

Posted after an NSTableView object's selection changes. The notification object is the table view whose selection changed. This notification does not contain a userInfo dictionary.
Availability
Declared In
NSTableView.h

NSTableViewSelectionIsChangingNotification

Posted as an NSTableView object's selection changes (while the mouse button is still down). Note that the notification is sent only for mouse events that change the table’s selection, not keyboard events. The notification object is the table view whose selection is changing. This notification does not contain a userInfo dictionary.
Availability
Declared In
NSTableView.h