Inherits from: NSControl : NSView : NSResponder : NSObject
Package: com.apple.yellow.application
dataSource | Returns the object providing the data that the NSTableView displays. |
tableColumns | Returns the NSTableColumn objects representing attributes for the NSTableView. |
selectedColumn | Returns the index of the selected column. |
selectedRow | Returns the index of the selected column. |
numberOfRows | Returns the number of rows in the NSTableView. |
reloadData | Informs the NSTableView that data has changed and needs to be retrieved and displayed again. |
An NSTableView displays data for a set of related records, with rows representing individual records and columns representing the attributes of those records. A record is a set of values for a particular real-world entity, such as an employee or a bank account. For example, in a table of employee records, each row represents one employee, and the columns represent such attributes as the first and last name, address, salary, and so on. An NSTableView is usually displayed in an NSScrollView, like this:
In this illustration, the NSTableView itself is only the portion displaying values. The header is drawn by two auxiliary views: the column headers by the header view, and the blank square above the vertical scroller by the corner view. The roles of these two auxiliary views are discussed in ""Auxiliary Components"."
The user selects rows or columns in the table by clicking, and edits individual cells by double-clicking. The user can also rearrange columns by dragging the column headers and can resize the columns by dragging the divider between two column headers. You can configure the table's parameters so that the user can select more than one row or column (or have none selected), so that the user isn't allowed to edit particular columns or rearrange them, and so on. You can also specify an action message to be sent when the user double-clicks something other than an editable cell.
Unlike most NSControls, an NSTableView doesn't store or cache the data it displays. Instead, it gets all of its data from an object that you provide, called its data source. Your data source object can store records in any way, but it must be able to identify them by integer index and must implement methods to provide the following information: how many records the data source contains, and what the value is for a particular record's attribute. If you want to allow the user to edit the records, you must also provide a method for changing the value of an attribute. These methods are described in the NSTableDataSource informal protocol specification.
A record attribute is indicated by an object called its identifier, which is associated with a column in the NSTableView, as described in ""Auxiliary Components"." Because a column can be reordered, its index can't be used to identify a record attribute. Instead, the data source uses the column's identifier as a key to retrieve the value for a column's attribute. The identifier can be any kind of object that uniquely identifies attributes for the data source. For example, if you specify identifiers as NSStrings containing the names of attributes, such as "Last Name", "Address", and so on, the data source object can use these strings as keys into NSDictionary objects. See the NSTableDataSource informal protocol specification for an example of how to use identifiers.
As indicated earlier, an NSTableView is usually displayed in an NSScrollView along with its two auxiliary views, the corner view and the header view. The corner view is by default a simple view that merely fills in the corner above the vertical scroller. You can replace the default corner view with a custom view; for example, a button that sorts based on the selected column. The header view is usually an instance of the NSTableHeaderView class, which draws the column headers and handles column selection, rearranging, and resizing. NSScrollView queries any document view it's given for the cornerView and headerView methods, and if the document view responds and returns objects for them, the NSScrollView automatically tiles them along with its scrollers and the document view.
The NSTableView and the NSTableHeaderView both need access to information about columns (such as their width), so this information is encapsulated in NSTableColumn objects. An NSTableColumn stores its column's width, and determines whether the user can resize the column or edit its cells. It also holds an NSCell object that the NSTableHeaderView uses to draw the column header, and an NSCell object that the NSTableView uses to draw values in the column (it reuses the same NSCell for each row in the column). Finally, the NSTableColumn holds the attribute identifier mentioned in ""Providing Data for Display"."
The cell for each column header is by default an instance of the NSTableHeaderCell class; it's used by the NSTableHeaderView to draw the column's header. An NSTableHeaderCell contains the title displayed over the column, as well as the font and color for that title. You use the API of its superclasses, NSTextFieldCell and NSCell, to set a column's title and to specify display attributes for that title (font, alignment, and so on). In addition, you can use the NSCell method setImage: to make the NSTableHeaderCell display an image instead of a title. To remove the image and restore the title, use the NSCell method setStringValue:.
The data cell for the column values is typically an instance of NSTextFieldCell, but can be an instance of any NSCell subclass, such as NSImageCell. This object is used to draw all values in the column and determines the font, alignment, text color, and other such display attributes for those values. You can customize the presentation of various kinds of values by assigning an NSFormatter to the cell. For example, to properly display NSDate values in a column, assign its data cell an NSDateFormatter.
NSTableView adds a handful of delegate messages to those defined by its superclass, NSControl. These methods give the delegate control over the appearance of individual cells in the table, over changes in selection, and over editing of cells. Delegate methods that request permission to alter the selection or edit a value are invoked during user actions that affect the NSTableView, but are not invoked by programmatic changes to the view. When making changes programmatically, you decide whether you want the delegate to intervene and, if so, send the appropriate message (checking first that the delegate responds to that message). Because the delegate methods involve the actual data displayed by the NSTableView, the delegate is typically the same object as the data source.
tableViewWillDisplayCell informs the delegate that the NSTableView is about to draw a particular cell. The delegate can modify the NSCell provided to alter the display attributes for that cell; for example, making uneditable values display in italic or gray text (as in the figure above).
tableViewShouldSelectRow and tableViewShouldSelectTableColumn give the delegate control over whether the user can select a particular row or column (though the user can still reorder columns). This is useful for disabling particular rows or columns. For example, in a database client application, when another user is editing a record you might want all other users not to be able to select it.
selectionShouldChangeInTableView allows the delegate to deny a change in selection; for example, if the user is editing a cell and enters an improper value, the delegate can prevent the user from selecting or editing any other cells until a proper value has been entered into the original cell.
tableViewShouldEditLocation asks the delegate whether it's okay to edit a particular cell. The delegate can approve or deny the request.
In addition to these methods, the delegate is also automatically registered to receive messages corresponding to NSTableView notifications. These inform the delegate when the selection changes and when a column is moved or resized:
Delegate Message | Notification |
tableViewColumnDidMove | NSTableViewColumnDidMoveNotification |
tableViewColumnDidResize | NSTableViewColumnDidResizeNotification |
tableViewSelectionDidChange | NSTableViewSelectionDidChangeNotification |
tableViewSelectionIsChanging | NSTableViewSelectionIsChangingNotification |
- Creating an instance
- initWithFrame:
- Setting the data source
- setDataSource
- dataSource
- Loading data
- reloadData
- Target-action behavior
- setDoubleAction
- doubleAction
- clickedColumn
- clickedRow
- Configuring behavior
- setAllowsColumnReordering
- allowsColumnReordering
- setAllowsColumnResizing
- allowsColumnResizing
- setAllowsMultipleSelection
- allowsMultipleSelection
- setAllowsEmptySelection
- allowsEmptySelection
- setAllowsColumnSelection
- allowsColumnSelection
- Setting display attributes
- setIntercellSpacing
- intercellSpacing
- setRowHeight
- rowHeight
- setBackgroundColor
- backgroundColor
- Manipulating columns
- addTableColumn
- removeTableColumn
- moveColumnToColumn
- tableColumns
- columnWithIdentifier
- tableColumnWithIdentifier
- Selecting columns and rows
- selectColumn
- selectRow
- deselectColumn
- deselectRow
- numberOfSelectedColumns
- numberOfSelectedRows
- selectedColumn
- selectedRow
- isColumnSelected
- isRowSelected
- selectedColumnEnumerator
- selectedRowEnumerator
- selectAll
- deselectAll
- Getting the dimensions of the table
- numberOfColumns
- numberOfRows
- Setting grid attributes
- setDrawsGrid
- drawsGrid
- setGridColor
- gridColor
- Editing cells
- editLocation
- editedRow
- editedColumn
- Setting auxiliary views
- setHeaderView
- headerView
- setCornerView
- cornerView
- Layout support
- rectOfColumn
- rectOfRow
- columnsInRect
- rowsInRect
- columnAtPoint
- rowAtPoint
- frameOfCellAtLocation
- setAutoresizesAllColumnsToFit
- autoresizesAllColumnsToFit
- sizeLastColumnToFit
- sizeToFit
- noteNumberOfRowsChanged
- tile
- Drawing
- drawRow
- drawGridInClipRect
- highlightSelectionInClipRect
- Scrolling
- scrollRowToVisible
- scrollColumnToVisible
- Text delegate methods
- textShouldBeginEditing
- textDidBeginEditing
- textDidChange
- textShouldEndEditing
- textDidEndEditing
- Persistence
- autosaveName
- autosaveTableColumns
- setAutosaveName
- setAutosaveTableColumns
- Setting the delegate
- setDelegate
- delegate
public NSTableView(NSRect frameRect)
It's usually more convenient to create an NSTableView using Interface Builder. Interface Builder lets you create an NSTableView already embedded in an NSScrollView, add and name the columns, and set up a data source. <<xref to IB/topics doc?>>
public void addTableColumn(NSTableColumn aColumn)
See Also: sizeToFitsizeLastColumnToFit, removeTableColumn
public boolean allowsColumnReordering()
true
if
the receiver allows the user to rearrange columns by dragging their
headers, false
otherwise. The
default is true
. You can rearrange columns
programmatically regardless of this setting.See Also: moveColumnToColumn, setAllowsColumnReordering
public boolean allowsColumnResizing()
true
if
the receiver allows the user to resize columns by dragging between
their headers, false
otherwise. The
default is true
. You can resize columns
programmatically regardless of this setting.See Also: - setWidth: (NSTableColumn), setAllowsColumnResizing
public boolean allowsColumnSelection()
true
if
the receiver allows the user to select columns by clicking their headers, false
otherwise. The
default is true
. You can select columns programmatically
regardless of this setting.See Also: selectColumn, allowsColumnReordering, setAllowsColumnSelection
public boolean allowsEmptySelection()
true
if
the receiver allows the user to select zero columns or rows, false
otherwise. The
default is true
.You can not
set an empty selection programmatically if this setting is false
, unlike
with the other settings that affect selection behavior.
See Also: deselectAll, deselectColumn, deselectRow, setAllowsEmptySelection
public boolean allowsMultipleSelection()
true
if
the receiver allows the user to select more than one column or row
at a time, false
otherwise. The
default is false
. You can select
multiple columns or rows programmatically regardless of this setting.See Also: selectColumn, selectRow, setAllowsMultipleSelection
public boolean autoresizesAllColumnsToFit()
true
if
the receiver proportionally resizes its columns to fit when its superview's
frame changes, false
if it only resizes
the last column.See Also: sizeToFitsetAutoresizesAllColumnsToFit, sizeLastColumnToFit
public String autosaveName()
null
.
The table information is saved separately for each user and for
each application that user uses. Note that even when a table view has an autosave name, it may not be saving table information automatically . To check whether table information is being saved automatically, use autosaveTableColumns.
See Also: autosaveTableColumns, setAutosaveName
public boolean autosaveTableColumns()
The
table information is saved separately for each user and for each application
that user uses. Note that if autosaveName returns null
,
this setting is ignored and table information isn't saved.
See Also: autosaveName, setAutosaveTableColumns, setAutosaveName
public NSColor backgroundColor()
See Also: setBackgroundColor
public int clickedColumn()
See Also: clickedRow, - setAction: (NSControl), setDoubleAction
public int clickedRow()
See Also: clickedColumn, - setAction: (NSControl), setDoubleAction
public int columnAtPoint(NSPoint aPoint)
See Also: rowAtPoint
public NSRange columnsInRect(NSRect aRect)
See Also: rowsInRect
public int columnWithIdentifier(Object anObject)
See Also: tableColumnWithIdentifier
public NSView cornerView()
See Also: headerView
public Object dataSource()
See Also: setDataSource
public Object delegate()
See Also: setDelegate
public void deselectAll(Object sender)
As a target-action method, deselectAll checks with the delegate before changing the selection, using selectionShouldChangeInTableView:.
See Also: allowsEmptySelection, selectAll, selectColumn
public void deselectColumn(int columnIndex)
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.
See Also: selectedColumn, allowsEmptySelection, selectRow
public void deselectRow(int rowIndex)
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.
See Also: selectedRow, allowsEmptySelection
public NSSelector doubleAction()
See Also: - action (NSControl) - target (NSControl), setDoubleAction
public void drawGridInClipRect(NSRect aRect)
Subclasses can override this method to draw grid lines other than the standard ones.
See Also: gridColor, setIntercellSpacing, drawsGrid, drawRow, highlightSelectionInClipRect
public void drawRow(int rowIndex, NSRect clipRect)
Subclasses can override this method to customize their appearance.
See Also: columnsInRect, highlightSelectionInClipRect, drawGridInClipRect
public boolean drawsGrid()
true
if
the receiver draws grid lines around cells, false
if
it doesn't. The default is true
.See Also: gridColor, drawGridInClipRect, setDrawsGrid
public void editLocation(int columnIndex, int rowIndex, NSEvent theEvent, boolean flag)
true
. 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 null
when
starting an edit programmatically.This method scrolls the receiver so that the cell is visible, sets up the field editor, and sends selectWithFrame:inView:editor:delegate:start:length: and editWithFrame:inView:editor:delegate:event: to the field editor's NSCell object with the NSTableView as the text delegate.
See Also: editedColumn, editedRow
public int editedColumn()
public int editedRow()
public NSRect frameOfCellAtLocation(int columnIndex, int rowIndex)
NSZeroRect
if columnIndex or rowIndex are
greater than the number of columns or rows in the NSTableView. The result of this method is used in a drawWithFrame:inView: message to the NSTableColumn's data cell.
See Also: rectOfColumn, rectOfRow
public NSColor gridColor()
See Also: drawsGrid, drawGridInClipRect, setGridColor
public NSTableHeaderView headerView()
null
if
the NSTableView has no header view. See the class
description and the NSTableHeaderView class specification for more
information.See Also: setHeaderView
public void highlightSelectionInClipRect(NSRect clipRect)
Subclasses can override this method to change the manner in which they highlight selections.
See Also: drawGridInClipRect
public NSSize intercellSpacing()
See Also: setDrawsGrid, setIntercellSpacing
public boolean isColumnSelected(int columnIndex)
true
if
the column at columnIndex is selected, false
otherwise.See Also: selectedColumn, selectedColumnEnumerator, selectColumn
public boolean isRowSelected(int rowIndex)
true
if
the row at rowIndex is selected, false
otherwise.See Also: selectedRow, selectedRowEnumerator, selectRow
public void moveColumnToColumn(int columnIndex, int newIndex)
This method posts NSTableViewColumnDidMoveNotification to the default notification center.
public void noteNumberOfRowsChanged()
See the NSTableDataSource informal protocol specification for information on the messages an NSTableView sends to its data source.
See Also: reloadData, - numberOfRowsInTableView: (NSTableDataSource informal protocol)
public int numberOfColumns()
See Also: numberOfRows
public int numberOfRows()
See Also: numberOfColumns, - numberOfRowsInTableView: (NSTableDataSource informal protocol)
public int numberOfSelectedColumns()
See Also: numberOfSelectedRows, selectedColumnEnumerator
public int numberOfSelectedRows()
See Also: numberOfSelectedColumns, selectedRowEnumerator
public NSRect rectOfColumn(int columnIndex)
See Also: frameOfCellAtLocation, rectOfRow, - headerRectOfColumn: (NSTableHeaderView)
public NSRect rectOfRow(int rowIndex)
See Also: frameOfCellAtLocation, rectOfColumn
public void reloadData()
See Also: noteNumberOfRowsChanged
public void removeTableColumn(NSTableColumn aTableColumn)
See Also: sizeToFitsizeLastColumnToFit, addTableColumn
public int rowAtPoint(NSPoint aPoint)
See Also: columnAtPoint
public float rowHeight()
See Also: setRowHeight
public NSRange rowsInRect(NSRect aRect)
See Also: columnsInRect
public void scrollColumnToVisible(int columnIndex)
See Also: scrollRowToVisible, - scrollToPoint: (NSClipView)
public void scrollRowToVisible(int rowIndex)
See Also: scrollColumnToVisible, - scrollToPoint: (NSClipView)
public void selectAll(Object sender)
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.
See Also: allowsMultipleSelection, deselectAll, selectColumn
public void selectColumn(int columnIndex, boolean flag)
false
,
deselects all before selecting the new column. Throws an exception if
multiple selection isn't allowed and flag is true
.
Posts NSTableViewSelectionDidChangeNotification to the default notification center
if the selection does in fact change.This method doesn't check with the delegate before changing the selection. If the user is editing a cell, editing is simply forced to end and the selection is changed.
See Also: allowsMultipleSelection, allowsColumnSelection, deselectColumn, selectedColumn, selectRow
public int selectedColumn()
See Also: selectedColumnEnumerator, numberOfSelectedColumns, selectColumn, deselectColumn
public NSEnumerator selectedColumnEnumerator()
See Also: numberOfSelectedColumns, selectedColumn, selectedRowEnumerator
public int selectedRow()
See Also: selectedRowEnumerator, numberOfSelectedRows, selectRow, deselectRow
public NSEnumerator selectedRowEnumerator()
See Also: numberOfSelectedRows, selectedRow, selectedColumnEnumerator
public void selectRow(int rowIndex, boolean flag)
false
,
deselects all before selecting the new row. Throws an exception if
multiple selection isn't allowed and flag is true
.
Posts NSTableViewSelectionDidChangeNotification to the default notification
center if the selection does in fact change.This method doesn't check with the delegate before changing the selection. If the user is editing a cell, editing is simply forced to end and the selection is changed.
See Also: allowsMultipleSelection, deselectRow, selectedRow, selectColumn
public void setAllowsColumnReordering(boolean flag)
true
the
user can reorder columns; if flag is false
the
user can't. The default is true
.
You can rearrange columns programmatically regardless of this setting.See Also: moveColumnToColumn, allowsColumnReordering
public void setAllowsColumnResizing(boolean flag)
true
the
user can resize columns; if flag is false
the
user can't. The default is true
.
You can resize columns programmatically regardless of this setting.See Also: - setWidth: (NSTableColumn), allowsColumnResizing
public void setAllowsColumnSelection(boolean flag)
true
the
user can select columns; if flag is false
the
user can't. The default is true
.
You can select columns programmatically regardless of this setting.See Also: selectColumn, setAllowsColumnReordering, allowsColumnSelection
public void setAllowsEmptySelection(boolean flag)
true
empty
selection is allowed; if flag is false
it
isn't. The default is true
.You can not set an empty selection programmatically if empty selection is disallowed, unlike with the other settings that affect selection behavior.
See Also: deselectAll, deselectColumn, deselectRow, allowsEmptySelection
public void setAllowsMultipleSelection(boolean flag)
true
the
user can select multiple rows or columns; if flag is false
the user
can't. The default is false
. You
can select multiple columns or rows programmatically regardless
of this setting.See Also: selectColumn, selectRow, allowsMultipleSelection
public void setAutoresizesAllColumnsToFit(boolean flag)
true
,
the difference in width is distributed among the receiver's table
columns; if flag is , only the last
column is resized to fit.See Also: sizeToFitautoresizesAllColumnsToFit, sizeLastColumnToFit
public void setAutosaveName(String name)
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 may not be saving table information automatically . To set whether table information is being saved automatically, use setAutosaveTableColumns.
See Also: autosaveName, setAutosaveTableColumns
public void setAutosaveTableColumns(boolean flag)
The
table information is saved separately for each user and for each application
that user uses. Note that if autosaveName returns null
,
this setting is ignored and table information isn't saved.
See Also: autosaveTableColumns, setAutosaveName
public void setBackgroundColor(NSColor aColor)
See Also: - setNeedsDisplay: (NSView), backgroundColor
public void setCornerView(NSView aView)
See Also: setHeaderView, cornerView
public void setDataSource(Object anObject)
This method throws an exception if anObject doesn't respond to either numberOfRowsInTableView: or tableView:objectValueForTableColumn:row:.
See Also: dataSource
public void setDelegate(Object anObject)
See Also: delegate
public void setDoubleAction(NSSelector aSelector)
See Also: - setAction: (NSControl) - setTarget: (NSControl), doubleAction
public void setDrawsGrid(boolean flag)
true
it
does; if flag is false
it
doesn't. The default is true
.See Also: setGridColor, drawGridInClipRect, drawsGrid
public void setGridColor(NSColor aColor)
See Also: setDrawsGrid, drawGridInClipRect, gridColor
public void setHeaderView(NSTableHeaderView aHeaderView)
See Also: setCornerView, headerView
public void setIntercellSpacing(NSSize aSize)
See Also: intercellSpacing
public void setRowHeight(float rowHeight)
See Also: rowHeight
public void sizeLastColumnToFit()
See Also: setAutoresizesAllColumnsToFit, - minWidth (NSTableColumn) - maxWidth (NSTableColumn)
public NSArray tableColumns()
public NSTableColumn tableColumnWithIdentifier(Object anObject)
equals
, or null
if
no columns are found with the specified identifier.See Also: columnWithIdentifier
public void textDidBeginEditing(NSNotification aNotification)
See Also: textShouldBeginEditing
public void textDidChange(NSNotification aNotification)
public void textDidEndEditing(NSNotification aNotification)
See Also: textShouldEndEditing
public boolean textShouldBeginEditing(NSText textObject)
true
to
allow editing if the delegate doesn't respond to that method. See
the NSText class specifications for more information on this text
delegate method.See Also: textDidBeginEditing
public boolean textShouldEndEditing(NSText textObject)
See Also: textDidEndEditing
public void tile()
See Also: - setNeedsDisplay: (NSView)
public abstract boolean selectionShouldChangeInTableView(NSTableView aTableView)
true
to
permit aTableView to change its selection
(typically a row being edited), false
to
deny permission. The user can select and edit
different cells within the same row, but can't select another
row unless the delegate approves. The delegate can implement this
method for complex validation of edited rows based on the values
of any of their cells.public abstract boolean tableViewShouldEditLocation(NSTableView aTableView, NSTableColumn aTableColumn, int rowIndex)
true
to
permit aTableView to edit the cell
at rowIndex in aTableColumn, false
to
deny permission. The delegate can implement this method
to disallow editing of specific cells.public abstract boolean tableViewShouldSelectRow(NSTableView aTableView, int rowIndex)
true
to
permit aTableView to select the row at rowIndex, false
to deny
permission. The delegate can implement this method
to disallow selection of particular rows.public abstract boolean tableViewShouldSelectTableColumn(NSTableView aTableView, NSTableColumn aTableColumn)
true
to
permit aTableView to select aTableColumn, false
to
deny permission. The delegate can implement this
method to disallow selection of particular columns.public abstract void tableViewWillDisplayCell(NSTableView aTableView, Object aCell, NSTableColumn aTableColumn, int rowIndex)
public abstract void tableViewColumnDidMove(NSNotification aNotification)
public abstract void tableViewColumnDidResize(NSNotification aNotification)
public abstract void tableViewSelectionDidChange(NSNotification aNotification)
public abstract void tableViewSelectionIsChanging(NSNotification aNotification)
Posted whenever a column is moved by user action in the NSTableView. The notification object is the NSTableView in which a column moved. The userInfo dictionary contains these keys and values:
Key | Value |
NSOldColumn | The column's original index (a number) |
NSNewColumn | The column's present index (a number) |
See Also: moveColumnToColumn
Posted whenever a column is resized in the NSTableView. The notification object is the NSTableView in which a column was resized. The userInfo dictionary contains these keys and values:
Key | Value |
NSOldWidth | The column's original width (a number) |
Posted after the NSTableView's selection changes. The notification
object is the NSTableView whose selection changed. The userInfo dictionary
is null
.
Posted as the NSTableView's selection changes (while the
mouse is still down). The notification object is the NSTableView
whose selection is changing. The userInfo dictionary
is null
.