Inherits From:
NSTableView : NSView : NSResponder : NSObject
Conforms To:
NSCoding (NSResponder)
NSObject (NSObject)
Declared In:
AppKit/NSOutlineView.h
- dataSource: | Returns the object that provides the data to be displayed (method of NSTableView). |
- numberOfRows: | Returns the number of rows in the NSOutlineView (method of NSTableView). |
- collapseItem: | Causes an item to be collapsed. |
- expandItem: | Causes an item to be expanded. |
- reloadItem:reloadChildren: | Informs the NSOutlineView that data for an item has changed and needs to be retrieved and redisplayed. |
Before reading about NSOutlineView, you should read the documentation for its parent class, NSTableView. An NSOutlineView displays data for a set of related items, with rows representing individual items and columns representing the attributes of those items. As with an NSTableView, each item in an outline view represents a set of values for a particular real-world entity, such as an employee or a bank account. In addition, NSOutlineView provides the ability to expand or collapse rows containing hierarchical data.
An item in an NSOutlineView is expandable if it can contain other items. An expandable item is distinguished visually by an expansion symbol that varies according to the operating system. On the Macintosh, for example, an expandable item contains an outline triangle, which points to the right when the item is collapsed and points down when the item is expanded. Clicking on the outline triangle causes it to change position. It also causes the item to be expanded or collapsed, depending on the new state of the outline triangle. An item can be expanded even if it contains no items.
Items inside an expanded item are indented. As a user expands or collapses nested items, the width of the column is expanded or contracted so that it is just wide enough to display the widest item, based on the width of the items and their indentation in the hierarchy. Justification follows the current system justification. Note that an item may consist of text, an image, or anything else that can be drawn by a subclass of NSCell.
An NSOutlineView is typically displayed in an NSScrollView, as shown below.
In this illustration, the NSOutlineView consists of just the rows and columns that display values. The header is drawn by two auxiliary views: a header view that draws the column headers and a corner view that draws the blank square above the vertical scroller. These auxiliary views are described in the documentation for NSTableView.
The NSTableView class also provides methods for working with data, responding to mouse clicks, setting grid attributes, editing cells, and performing other operations. For full information on these methods, see the documentation for NSTableView.
Delegate methods that request permission to alert the selection or edit a value are invoked during user actions that affect the NSOutlineView, 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, you send the appropriate message (checking first that the delegate responds to that message). Because the delegate methods involve the actual data displayed by the NSOutlineView, the delegate is typically the same object as the data source, though this is not a requirement.
NSOutlineView redefines these delegate messages based on similar messages in NSTableView:
outlineView:willDisplayCell:forTableColumn:item:
informs the delegate that the NSOutlineView is about to draw the cell specified by the passed column and item. 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.
outlineView:shouldSelectItem:
and outlineView:shouldSelectTableColumn:
give the delegate control over whether the user can select a specified row or column (though the user can still reorder columns). This is useful for disabling a specified row or column. For example, in a database client application, when a user is editing a record you might want to not allow other users to select the same row.
selectionShouldChangeInOutlineView:
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.
outlineView:shouldEditTableColumn:item:
asks the delegate whether it's okay to edit the cell specified by the passed column and item. The delegate can approve or deny the request.
NSOutlineView defines these additional delegate messages:
outlineView:shouldExpandItem:
asks the delegate whether it's okay to expand the specified item.
outlineView:willExpandItem:
informs the delegate that the NSOutlineView is about to expand the specified item.
outlineView:shouldCollapseItem:
asks the delegate whether it's okay to collapse the specified item.
outlineView:willCollapseItem:
informs the delegate that the NSOutlineView is about to expand the specified item.
outlineView:willDisplayOutlineCell:forTableColumn:item:
informs the delegate that the outline view is about to display the cell that includes the expansion symbol.
In addition to these methods, the delegate is automatically registered to receive messages corresponding to NSOutlineView notifications. These inform the delegate when the selection changes or is about to change, when a column is moved or resized, and when an item is expanded or collapsed:
Delegate Message | Notification |
---|---|
outlineViewColumnDidMove:
| NSOutlineViewColumnDidMoveNotification |
outlineViewColumnDidResize:
| NSOutlineViewColumnDidResizeNotification |
outlineViewSelectionDidChange:
| NSOutlineViewSelectionDidChangeNotification |
outlineViewSelectionIsChanging:
| NSOutlineViewSelectionIsChangingNotification |
outlineViewItemDidExpand:
| NSOutlineViewItemDidExpandNotification |
outlineViewItemDidCollapse:
| NSOutlineViewItemDidCollapseNotification |
collapseItem:
(id)item
Collapses item if item is expanded and expandable, otherwise does nothing. If collapsing takes place, posts item collapse notification.
See also:
- expandItem:
collapseItem:
(id)itemcollapseChildren:
(BOOL)collapseChildren
If collapseChildren is set to NO, collapses item only (identical to collapseItem:
). If collapseChildren is set to YES, recursively collapses item and its children. For each item that is collapsed, posts item collapsed notification.
See also:
- collapseItem:
expandItem:
(id)item
Expands item if item is expandable and is not already expanded; otherwise, does nothing. If expanding takes place, posts item expanded notification.
See also:
- collapseItem:
expandItem:
(id)itemexpandChildren:
(BOOL)expandChildren
If expandChildren is set to NO, expands item only (identical to expandItem:
). If expandChildren is set to YES, recursively expands item and its children. For each item that is expanded, posts item expanded notification.
See also:
- collapseItem:collapseChildren:
indentationMarkerFollowsCell
Returns YES if the expansion symbol in an expanded item is displayed in the cell with the item and NO if the symbol is displayed system-justified in the column. The default is YES.
See also:
- setIndentationMarkerFollowsCell:
indentationPerLevel
Returns current indentation per level, in points.
See also:
- setIndentationPerLevel:
initWithFrame:
(NSRect)frameRect
Initializes a newly allocated NSOutlineView with frameRect as its frame rectangle. This method is the designated initializer for the NSOutlineView class. It calls the initWithFrame:
method of its superclass, NSTableView, then performs initialization specific to the outline view. It returns self
.
The new NSOutlineView has a header view but has no columns; you can create NSTableColumn objects, set their titles and attributes, and add them to the new view with addTableColumn:
. You must also set the NSOutlineView up in an NSScrollView with NSScrollView's setDocView:
method. For more information, see the documentation for the NSTableView class.
It's usually more convenient to create an NSOutlineView using Interface Builder, which allows you to create an NSOutlineView already embedded in an NSScrollView, add and name the columns, and set up a data source. <<Interface Builder support for NSOutlineView may not be available in this release.>>
isExpandable:
(id)item
Returns YES if item is expandable-that is, item can contain other items.
See also:
- expandItem:
, - isItemExpanded:
isItemExpanded
:(id)item
Returns YES if item is expanded.
See also:
- expandItem:
, - isExpandable:
itemAtRow:
(int)row
Returns the item associated with row.
See also:
- rowForItem:
levelForItem:
(id)item
Returns the indentation level for item.
See also:
- indentationPerLevel
, - levelForRow:
levelForRow:
(int)row
Returns the indentation level for row.
See also:
- indentationPerLevel
, - levelForItem:
numberOfRows
Returns the number of rows in the NSOutlineView.
numberOfRows
Returns the number of rows in the NSOutlineView.
outlineTableColumn
Returns the table column in which hierarchical data is displayed.
See also:
- setOutlineTableColumn:
,
)reloadItem:
(id)item
Reloads and redisplays the data for item.
See also:
- reloadItem:reloadChildren:
)reloadItem:
(id)item
reloadChildren:
(BOOL)reloadChildren
If reloadChildren is set to NO, reloads and redisplays the data for item only (identical to reloadItem:
). If reloadChildren is set to YES, recursively reloads and redisplays the data for item and its children. It is not necessary, or efficient, to reload children if the item is not expanded.
See also:
- reloadItem:
rowForItem:
(id)item
Returns the row associated with item.
See also:
- itemAtRow:
setIndentationMarkerFollowsCell:
(BOOL)drawInCell
Sets whether the expansion symbol in an item should be displayed in the cell with the item or left-justified in the column. The default is YES (the symbol is displayed in the cell).
See also:
- indentationMarkerFollowsCell
setIndentationPerLevel:
(float)newIndentLevel
Sets indentation per level, in points, to newIndentLevel.
See also:
- indentationPerLevel
setOutlineTableColumn:
(NSTableColumn *)outlineTableColumn
Sets the table column in which hierarchical data is displayed to outlineTableColumn.
See also:
- outlineTableColumn
Methods Implemented By the Delegate
outlineView:
(NSOutlineView *)outlineViewshouldCollapseItem:
(id)item
Returns YES to permit outlineView to collapse item, NO to deny permission. The delegate can implement this method to disallow collapsing of specific items.
outlineView:
(NSOutlineView *)outlineViewshouldEditTableColumn:
(NSTableColumn *)tableColumnitem:
(id)item
Returns YES to permit outlineView to edit the cell specified by tableColumn and item, NO to deny permission. The delegate can implement this method to disallow editing of specific cells.
outlineView:
(NSOutlineView *)outlineViewshouldExpandItem:
(id)item
Returns YES to permit outlineView to expand item, NO to deny permission. The delegate can implement this method to disallow expanding of specific items.
outlineView:
(NSOutlineView *)outlineViewshouldSelectItem:
(id)item
Returns YES to permit outlineView to select item, NO to deny permission. The delegate can implement this method to disallow selection of particular items.
outlineView:
(NSOutlineView *)outlineViewshouldSelectTableColumn:
(NSTableColumn *)tableColumn
Returns YES to permit outlineView to select tableColumn, NO to deny permission. The delegate can implement this method to disallow selection of specific columns.
outlineView:
(NSOutlineView *)outlineViewwillCollapseItem:
(id)item
Informs the delegate that outlineView is about to collapse item.
outlineView:
(NSOutlineView *)outlineViewwillDisplayCell:
(id)cellforTableColumn:
(NSTableColumn *)tableColumnitem:
(id)item
Informs the delegate that outlineView is about to display the cell specified by tableColumn and item. The delegate can modify cell to alter its display attributes; for example, making uneditable values display in italic or gray text.
outlineView:
(NSOutlineView *)outlineViewwillDisplayOutlineCell:
(id)cellforTableColumn:
(NSTableColumn *)tableColumnitem:
(id)item
Informs the delegate that outlineView is about to display cell (the cell used to draw the expansion symbol) for the column and item specified by tableColumn and item. The delegate can modify cell to alter its display attributes.
outlineView:
(NSOutlineView *)outlineView willExpandItem:
(id)item
Informs the delegate that outlineView is about to expand item.
selectionShouldChangeInOutlineView:
(NSOutlineView *)outlineView
Returns YES to permit outlineView to change its selection (typically a row being edited), NO to deny permission. 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. The delegate can implement this method for complex validation of edited rows based on the values of any of their cells.
This notification contains a notification object and a userInfo dictionary. The notification object is the NSOutlineView in which a column moved. The userInfo dictionary contains these keys and values:
Key | Value |
---|---|
NSOldColumn | The column's original index (an NSNumber) |
NSNewColumn | The column's present index (an NSNumber) |
See also:
- moveColumn:toColumn:
(NSTableView)
This notification contains a notification object and a userInfo dictionary. The notification object is the NSOutlineView in which a column was resized. The userInfo dictionary contains these keys and values:
Key | Value |
---|---|
NSOldWidth | The column's original width (an NSNumber) |
This notification contains a notification object and a userInfo dictionary. The notification object is the NSOutlineView in which an item was collapsed. The userInfo dictionary contains these keys and values:
Key | Value |
---|---|
NSObject | The item that was collapsed (an id )
|
This notification contains a notification object and a userInfo dictionary. The notification object is the NSOutlineView in which an item was expanded. The userInfo dictionary contains these keys and values:
Key | Value |
---|---|
NSObject | The item that was expanded (an id )
|
This notification contains a notification object but no userInfo dictionary. The notification object is the NSOutlineView whose selection changed.
This notification contains a notification object but no userInfo dictionary. The notification object is the NSOutlineView whose selection is changing.