NSTableColumn Class Reference

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

Overview

The NSTableColumn class stores the display characteristics and identifier for a column in an NSTableView instance. A table column object determines the width (including the maximum and minimum widths) of its column in the table view and specifies the column’s resizing and editing behavior.

A table column stores two cell objects: the header cell, which is used to draw the column header, and the data cell, which is used to draw the values for each row. In a cell-based table, you can control the display of the column by specifying subclasses of NSCell to use and by setting the font and other display characteristics for these cells. For example, you can use an NSTextFieldCell to display string values or substitute an NSImageCell to display pictures.

Tasks

Creating a Table Column

Setting the Table View

Controlling Size

Setting Component Cells

Setting the Identifier

Controlling Editability in a Cell-Based Table

Sorting

Setting Column Visibility

Setting Tooltips

Deprecated Methods

Instance Methods

dataCell

Returns the cell prototype object used to draw individual cells.

- (id)dataCell
Return Value

The NSCell subclass used as the prototype for table column cells.

Discussion

When using a cell-based table view with Cocoa bindings, the bindings infrastructure may directly call this method to access bindings and properties set on the cell.

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

dataCellForRow:

Returns the cell object used to display values in the specified row of the table column.

- (id)dataCellForRow:(NSInteger)row
Parameters
row

The table column row.

Return Value

The data cell object.

Discussion

Returns the NSCell object used by the table view to draw values for the receiver. The table view calls this method when drawing the row, so you shouldn’t need to call it directly. By default, this method just calls dataCell.

To enable per-row customization of the cell used by the table column, you can override this method or use the NSTableViewDelegate method tableView:dataCellForTableColumn:row:. In both cases, the cell that’s returned should properly implement copyWithZone:, because the table view may copy the cell during certain operations.

Subclasses should be prepared for this method to be called with row equal to –1 in cases where no actual row is involved but the table view needs to get some generic cell information.

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

headerCell

Returns the cell used to draw the table column’s header.

- (id)headerCell
Return Value

The header cell.

Discussion

You can set the table column title by calling setStringValue: on headerCell.

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

headerToolTip

Returns the string that’s displayed in a help tag.

- (NSString *)headerToolTip
Return Value

The string displayed in a help tag (also known as a tooltip). The default value is nil.

Discussion

If headerToolTip isn’t nil, the string is displayed in a help tag when the pointer pauses over the header of the table column; if headerToolTip is nil, no help tag is displayed.

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

identifier

Returns the identifier string.

- (NSString *)identifier
Return Value

The table column identifier string.

Discussion

This string is used by the data source to identify the table column.

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

initWithIdentifier:

Initializes a newly created table column with a string identifier.

- (id)initWithIdentifier:(NSString *)identifier
Parameters
identifier

The string identifier for the column.

Return Value

An initialized table column instance with an NSTextFieldCell instance as its default cell.

Discussion

To set the column title in a cell-based table, you can call setStringValue: on the column’s headerCell.

This method is the designated initializer for the NSTableColumn class.

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

isEditable

Returns whether a cell-based table’s column cells are user editable.

- (BOOL)isEditable
Return Value

YES if the user can edit cells in the cell-based table’s column; NO otherwise. The default value is YES.

Discussion

To initiate editing programmatically regardless of this setting, use the NSTableView editColumn:row:withEvent:select: method.

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

isHidden

Returns whether the table column is hidden.

- (BOOL)isHidden
Return Value

YES if the table column is hidden; NO otherwise. The default value is NO.

Discussion

The hidden state is stored when the table view autosaves the table column state.

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

maxWidth

Returns the table column’s maximum width.

- (CGFloat)maxWidth
Return Value

The maximum width of the table column, in points. The default value is MAXFLOAT.

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

minWidth

Returns the table column’s minimum width.

- (CGFloat)minWidth
Return Value

The minimum width of the table column, in points. The default value is 10.0.

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

resizingMask

Returns the table column’s resizing mask.

- (NSUInteger)resizingMask
Return Value

Returns the resizing mask that specifies the table column’s resizability. The default value is NSTableColumnUserResizingMask | NSTableColumnAutoresizingMask.

Discussion

See “Resizing Modes” for a description of the resizing mask constants.

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

setDataCell:

Sets the cell prototype used by the table column to draw individual cells.

- (void)setDataCell:(NSCell *)aCell
Parameters
aCell

A cell to use as the cell prototype.

Discussion

You can use this method to control the font, alignment, and other text attributes for the table column contents.

You can also assign a cell that displays things other than text—for example, you can display images by setting the cell to NSImageCell.

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

setEditable:

Sets whether the user can edit cells in a cell-based table’s column.

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

YES if the cell in the table column of a cell-based table view is editable, NO if the cell is not editable.

Discussion

To initiate editing programmatically regardless of this setting, use the NSTableView editColumn:row:withEvent:select: method.

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

setHeaderCell:

Sets the cell used to draw the table column’s header.

- (void)setHeaderCell:(NSCell *)aCell
Parameters
aCell

The cell to use as the table column header. This value must not be nil. It’s recommended that aCell be an instance or subclass of NSTableHeaderCell.

Discussion

This method is only valid for cell-based table views.

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

setHeaderToolTip:

Sets the string that’s displayed in a help tag.

- (void)setHeaderToolTip:(NSString *)string
Parameters
string

A string that contains the text to display in a help tag (also known as a tooltip). If no string is set, the table column header doesn’t display a help tag.

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

setHidden:

Sets whether the table column is hidden.

- (void)setHidden:(BOOL)aFlag
Parameters
aFlag

YES if the table column is to be hidden; NO otherwise.

Discussion

Columns that are hidden still exist in the table view object’s tableColumns array and are included in the table view’s numberOfColumns count.

The hidden state is stored when the table view autosaves the table column state.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
NSTableColumn.h

setIdentifier:

Sets the table column’s identifier to the specified string.

- (void)setIdentifier:(NSString *)aString
Parameters
aString

The column identifier string.

Discussion

This string is used by the data source to identify the table column.

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

setMaxWidth:

Sets the table column’s maximum width.

- (void)setMaxWidth:(CGFloat)maxWidth
Parameters
maxWidth

The maximum width of the table column, in points.

Discussion

If the table column’s current width is greater than maxWidth, the width is set to the maxWidth value.

The table column width can’t be greater than maxWidth, whether the column is resized by the user or programmatically.

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

setMinWidth:

Sets the table column’s minimum width.

- (void)setMinWidth:(CGFloat)minWidth
Parameters
minWidth

The minimum table column width, in points.

Discussion

If the table column’s current width is less than minWidth, the width is set to the minWidth value.

The table column width can’t be less than minWidth, whether the column is resized by the user or programmatically.

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

setResizingMask:

Sets the table column’s resizability.

- (void)setResizingMask:(NSUInteger)resizingMask
Parameters
resizingMask

The resizing mask that specifies the resizability of the table column. See “Resizing Modes” for possible values. Values can be combined using the C bitwise OR operator. If resizingMask is 0, the column is not resizable.

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

setSortDescriptorPrototype:

Sets the table column’s sort descriptor prototype.

- (void)setSortDescriptorPrototype:(NSSortDescriptor *)sortDescriptor
Parameters
sortDescriptor

The sort descriptor prototype.

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 that defines how to sort.

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

setTableView:

Sets the table view that contains the table column.

- (void)setTableView:(NSTableView *)aTableView
Parameters
aTableView

The table view.

Discussion

You should never need to call this method; it’s called automatically when you add a table column to a table view using the NSTableView class’s method addTableColumn:.

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

setWidth:

Sets the table column’s width to the specified value.

- (void)setWidth:(CGFloat)newWidth
Parameters
newWidth

The new column width, in points.

Discussion

If newWidth exceeds the minimum or maximum width, it’s adjusted to the appropriate limiting value.

This method posts NSTableViewColumnDidResizeNotification on behalf of the table column’s NSTableView and marks the table view as needing display.

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

sizeToFit

Resizes the table column to fit the width of its header cell.

- (void)sizeToFit
Discussion

If the table column’s maximum width is less than the width of the header, the maximum is increased to the header’s width. Similarly, if the table column’s minimum width is greater than the width of the header, the minimum is reduced to the header’s width.

If this method causes the table column’s width to change, the column’s table view is marked as needing display.

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

sortDescriptorPrototype

Returns the table column’s sort descriptor prototype.

- (NSSortDescriptor *)sortDescriptorPrototype
Return Value

The sort descriptor prototype.

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

tableView

Returns the table view that the column belongs to.

- (NSTableView *)tableView
Return Value

The NSTableView instance that contains the table column.

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

width

Returns the table column’s width.

- (CGFloat)width
Return Value

The width of the table column, in points. The default value is 100.0.

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

Constants

Resizing Modes

These constants specify the resizing modes for a table column. The values are passed as the parameter to the setResizingMask: method.

enum {
   NSTableColumnNoResizing = 0,
   NSTableColumnAutoresizingMask = ( 1 << 0 ),
   NSTableColumnUserResizingMask = ( 1 << 1 )
};
Constants
NSTableColumnNoResizing

Prevents the table column from resizing.

Available in OS X v10.4 and later.

Declared in NSTableColumn.h.

NSTableColumnAutoresizingMask

Allows the table column to resize automatically in response to resizing the table view. The resizing behavior for the table view is set using the NSTableView method setColumnAutoresizingStyle:.

Available in OS X v10.4 and later.

Declared in NSTableColumn.h.

NSTableColumnUserResizingMask

Allows the table column to be resized by the user.

Available in OS X v10.4 and later.

Declared in NSTableColumn.h.