| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/AppKit.framework |
| Availability | Available in Mac OS X v10.0 and later. |
| Declared in | NSOutlineView.h |
| Companion guides | |
| Related sample code |
NSOutlineView is a subclass of NSTableView that uses a row-and-column format to display hierarchical data that can be expanded and collapsed, such as directories and files in a file system. A user can expand and collapse rows, edit values, and resize and rearrange columns.
Important: Like a table view, an outline 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). See the NSOutlineViewDataSource protocol, which declares the methods that an NSOutlineView object uses to access the contents of its data source object.
An outline view has the following features:
A user can expand and collapse rows.
Each item in the outline view must be unique. In order for the collapsed state to remain consistent between reloads the item's pointer must remain the same.
The view gets data from a data source (see the NSOutlineViewDataSource informal protocol).
The view retrieves only the data that needs to be displayed.
The following are commonly-used methods:
numberOfRows | Returns the number of rows in the receiver. |
collapseItem: | Collapses a given item. |
expandItem: | Expands a given item. |
reloadItem:reloadChildren: | Reloads a given item and, optionally, its children. |
The NSOutlineView provides a number of customization features through delegation. The majority of the delegate methods are declared in the NSOutlineViewDelegate Protocol protocol. However, due to an error in the transition, some delegate methods are still an informal protocol and appear in this document as delegate methods. All these methods are NSNotificationCenter oriented and are the following methods:
These methods will migrate to the NSOutlineViewDelegate Protocol protocol in the version of Mac OS X following Mac OS X v 10.6.
– isExpandable:
– isItemExpanded:
– outlineViewItemWillExpand: delegate method
– outlineViewItemDidExpand: delegate method
– outlineViewItemWillCollapse: delegate method
– outlineViewItemDidCollapse: delegate method
– outlineViewSelectionIsChanging: delegate method
– outlineViewSelectionDidChange: delegate method
– setOutlineTableColumn:
– outlineTableColumn
– autoresizesOutlineColumn
– setAutoresizesOutlineColumn:
– outlineViewColumnDidMove: delegate method
– outlineViewColumnDidResize: delegate method
– levelForItem:
– levelForRow:
– setIndentationPerLevel:
– indentationPerLevel
– setIndentationMarkerFollowsCell:
– indentationMarkerFollowsCell
Returns a Boolean value that indicates whether the receiver automatically resizes its outline column when the user expands or collapses items.
- (BOOL)autoresizesOutlineColumn
YES if the outline column is automatically resized, otherwise NO.
The outline column contains the cells with the expansion symbols and is generally the first column. The default is YES.
NSOutlineView.hReturns a Boolean value that indicates whether the expanded items in the receiver are automatically saved.
- (BOOL)autosaveExpandedItems
YES if when an item is expanded, the outline view displays the previous expanded state of its contained items, otherwise NO.
The outline view information is saved separately for each user and for each application that user uses. Note that if autosaveName returns nil, this setting is ignored, and outline information isn’t saved.
Starting in Mac OS X version 10.5, the value for autosaveExpandedItems is saved out in the nib file. The default value is NO.
– autosaveName (NSTableView)– autosaveTableColumns (NSTableView)– setAutosaveExpandedItems:NSOutlineView.hCollapses a given item.
- (void)collapseItem:(id)item
An item in the receiver.
If item is not expanded or not expandable, does nothing
If collapsing takes place, posts item collapse notification.
NSOutlineView.hCollapses a given item and, optionally, its children.
- (void)collapseItem:(id)item collapseChildren:(BOOL)collapseChildren
An item in the receiver.
Starting in Mac OS X version 10.5, passing 'nil' will collapse each item under the root in the outline view.
If YES, recursively collapses item and its children. If NO, collapses item only (identical to collapseItem:).
For example, this method is invoked with the collapseChildren parameter set to YES when a user Option-clicks the disclosure triangle for an item in the outline view (to collapse the item and all its contained items).
For each item collapsed, posts an item collapsed notification.
NSOutlineView.hReturns the object that provides the data displayed by the receiver.
- (id < NSOutlineViewDataSource >)dataSource
The object that provides the data displayed by the receiver.
See Writing an Outline View Data Source and the NSOutlineViewDataSource Protocol Reference informal protocol specification for more information.
NSOutlineView.hReturns the receiver’s delegate.
- (id < NSOutlineViewDelegate >)delegate
The receiver’s delegate.
NSOutlineView.hExpands a given item.
- (void)expandItem:(id)item
An item in the receiver.
If item is not expandable or is already expanded, does nothing.
If expanding takes place, posts an item expanded notification.
NSOutlineView.hExpands a specified item and, optionally, its children.
- (void)expandItem:(id)item expandChildren:(BOOL)expandChildren
An item in the receiver.
Starting in Mac OS X version 10.5, passing 'nil' will expand each item under the root in the outline view.
If YES, recursively expands item and its children. If NO, expands item only (identical to expandItem:).
For example, this method is invoked with the expandChildren parameter set to YES when a user Option-clicks the disclosure triangle for an item in the outline view (to expand the item and all its contained items).
For each item expanded, posts an item expanded notification.
NSOutlineView.hReturns the frame of the outline cell for a given row.
- (NSRect)frameOfOutlineCellAtRow:(NSInteger)row
The index of the row for which to return the frame.
The frame of the outline cell for the row at index row, considering the current indentation and the value returned by indentationMarkerFollowsCell. If the row at index row is not an expandable row, returns NSZeroRect.
You can override this method in a subclass to return a custom frame for the outline button cell. If your override returns an empty rect, no outline cell is drawn for that row. You might do that, for example, so that the disclosure triangle will not be shown for a row that should never be expanded.
NSOutlineView.hReturns a Boolean value that indicates whether the indentation marker symbol displayed in the outline column should be indented along with the cell contents, or always displayed left-justified in the column.
- (BOOL)indentationMarkerFollowsCell
YES if the indentation marker is indented along with the cell contents, otherwise NO.
The default is YES.
NSOutlineView.hReturns the current indentation per level.
- (CGFloat)indentationPerLevel
The current indentation per level, in points.
NSOutlineView.hReturns a Boolean value that indicates whether a given item is expandable.
- (BOOL)isExpandable:(id)item
An item in the receiver.
YES if item is expandable—that is, item can contain other items, otherwise NO.
NSOutlineView.hReturns a Boolean value that indicates whether a given item is expanded.
- (BOOL)isItemExpanded:(id)item
An item in the receiver.
YES if item is expanded, otherwise NO.
NSOutlineView.hReturns the item associated with a given row.
- (id)itemAtRow:(NSInteger)row
The index of a row in the receiver.
The item associated with row.
NSOutlineView.hReturns the indentation level for a given item.
- (NSInteger)levelForItem:(id)item
An item in the receiver.
The indentation level for item. If item is nil (which is the root item), returns –1.
The levels are zero-based—that is, the first level of displayed items is level 0.
NSOutlineView.hReturns the indentation level for a given row.
- (NSInteger)levelForRow:(NSInteger)row
The index of a row in the receiver.
The indentation level for row. For an invalid row, returns –1.
The levels are zero-based—that is, the first level of displayed items is level 0.
NSOutlineView.hReturns the table column in which hierarchical data is displayed.
- (NSTableColumn *)outlineTableColumn
The table column in which hierarchical data is displayed.
Each level of hierarchical data is indented by the amount specified by indentationPerLevel (the default is 16.0), and decorated with the indentation marker (disclosure triangle) on rows that are expandable.
Starting in Mac OS X version 10.5, outline table column data is saved in encodeWithCoder: and restored in initWithCoder:.
NSOutlineView.hReturns the parent for a given item.
- (id)parentForItem:(id)item
The item for which to return the parent.
The parent for item, or nil if the parent is the root.
NSOutlineView.hReloads and redisplays the data for item.
- (void)reloadItem:(id)item
The item to reload and display
This method may cause the outline view to change it’s selection unexpectedly.
In Mac OS X v 10.6 and earlier, this method will not invoke the outlineViewSelectionDidChange: delegate method.
NSOutlineView.hReloads a given item and, optionally, its children.
- (void)reloadItem:(id)item reloadChildren:(BOOL)reloadChildren
An item in the receiver.
Starting in Mac OS X version 10.5, passing 'nil' will reload everything under the root in the outline view.
If YES, recursively reloads item and its children. If NO, reloads item only (identical to reloadItem:).
It is not necessary, or efficient, to reload children if the item is not expanded.
NSOutlineView.hReturns the row associated with a given item.
- (NSInteger)rowForItem:(id)item
An item in the receiver.
The row associated with item, or –1 if item is nil or cannot be found.
NSOutlineView.hSets whether the receiver automatically resizes its outline column when the user expands or collapses an item.
- (void)setAutoresizesOutlineColumn:(BOOL)resize
YES if the outline column is automatically resized, otherwise NO.
The outline column contains the cells with the expansion symbols and is generally the first column. The default is YES.
NSOutlineView.hSets whether the expanded items in the receiver are automatically saved.
- (void)setAutosaveExpandedItems:(BOOL)flag
If flag is different from the current value, this method also reads in the saved information and sets the outline view’s options to match. YES indicates that when an item is expanded, the outline view displays the previous expanded state of its contained items.
The outline information is saved separately for each user and for each application that user uses.
If autosaveName returns nil or if you haven’t implemented the data source methods outlineView:itemForPersistentObject: and outlineView:persistentObjectForItem:, this setting is ignored, and expanded item information isn’t saved.
Note that you can have separate settings for autosaveExpandedItems and autosaveTableColumns, so you could, for example, save expanded item information, but not table column positions.
Starting in Mac OS X version 10.5, the value for autosaveExpandedItems is saved out in the nib file. The default value is NO.
– autosaveExpandedItems– setAutosaveTableColumns: (NSTableView)NSOutlineView.hSets the receiver’s data source to a given object.
- (void)setDataSource:(id < NSOutlineViewDataSource >)anObject
The data source for the receiver. The object must implement the appropriate methods of the NSOutlineViewDataSource Protocol Reference informal protocol.
The receiver maintains a weak reference to the data source (see Communicating With Objects). After setting the data source, this method invokes tile.
This method raises an NSInternalInconsistencyException if anObject doesn’t respond to all of outlineView:child:ofItem:, outlineView:isItemExpandable:, outlineView:numberOfChildrenOfItem:, and outlineView:objectValueForTableColumn:byItem:.
NSOutlineView.hSets the receiver’s delegate.
- (void)setDelegate:(id < NSOutlineViewDelegate >)anObject
The delegate for the receiver. The delegate must conform to the NSOutlineViewDelegate Protocol protocol.
NSOutlineView.hUsed to “retarget” a proposed drop.
- (void)setDropItem:(id)item dropChildIndex:(NSInteger)index
For example, to specify a drop on an item I, you specify item as 1 and index as NSOutlineViewDropOnItemIndex. To specify a drop between child 2 and 3 of item I, you specify item as I and index as 3 (children are a zero-based index). To specify a drop on an unexpandable item 1, you specify item as I and index as NSOutlineViewDropOnItemIndex.
NSOutlineView.hSets whether the indentation marker symbol displayed in the outline column should be indented along with the cell contents, or always displayed left-justified in the column.
- (void)setIndentationMarkerFollowsCell:(BOOL)drawInCell
The default is YES, the indentation marker is indented along with the cell contents.
NSOutlineView.hSets the per-level indentation.
- (void)setIndentationPerLevel:(CGFloat)newIndentLevel
The indentation per level, in points.
NSOutlineView.hSets the table column in which hierarchical data is displayed.
- (void)setOutlineTableColumn:(NSTableColumn *)outlineTableColumn
The table column in which hierarchical data is displayed.
Starting in Mac OS X version 10.5, outline table column data is saved in encodeWithCoder: and restored in initWithCoder:.
NSOutlineView.hReturns a Boolean value that indicates whether autoexpanded items should return to their original collapsed state.
- (BOOL)shouldCollapseAutoExpandedItemsForDeposited:(BOOL)deposited
YES if autoexpanded items should return to their original collapsed state, otherwise NO.
Override this method to provide custom behavior. deposited tells whether or not the drop terminated due to a successful drop.
This method is called in a variety of situations. For example, it is sent shortly after outlineView:acceptDrop:item:childIndex: is processed and also if the drag exits the outline view (exiting the view is treated the same as a failed drop).
NSOutlineView.hInvoked when notification is posted—that is, whenever the user moves a column in the outline view.
- (void)outlineViewColumnDidMove:(NSNotification *)notification
This method is invoked as a result of posting an NSOutlineViewColumnDidMoveNotification.
NSOutlineView.hInvoked when notification is posted—that is, whenever the user resizes a column in the outline view.
- (void)outlineViewColumnDidResize:(NSNotification *)notification
This method is invoked as a result of posting an NSOutlineViewColumnDidResizeNotification.
NSOutlineView.hInvoked when notification is posted—that is, whenever the user collapses an item in the outline view.
- (void)outlineViewItemDidCollapse:(NSNotification *)notification
This method is invoked as a result of posting an NSOutlineViewItemDidCollapseNotification.
NSOutlineView.hInvoked when notification is posted—that is, whenever the user expands an item in the outline view.
- (void)outlineViewItemDidExpand:(NSNotification *)notification
This method is invoked as a result of posting an NSOutlineViewItemDidExpandNotification.
NSOutlineView.hInvoked when notification is posted—that is, whenever the user is about to collapse an item in the outline view.
- (void)outlineViewItemWillCollapse:(NSNotification *)notification
This method is invoked as a result of posting an NSOutlineViewItemWillCollapseNotification.
NSOutlineView.hInvoked when notification is posted—that is, whenever the user is about to expand an item in the outline view.
- (void)outlineViewItemWillExpand:(NSNotification *)notification
This method is invoked as a result of posting an NSOutlineViewItemWillExpandNotification.
NSOutlineView.hInvoked when notification is posted—that is, immediately after the outline view’s selection has changed.
- (void)outlineViewSelectionDidChange:(NSNotification *)notification
This method is invoked as a result of posting an NSOutlineViewSelectionDidChangeNotification.
NSOutlineView.hInvoked when notification is posted—that is, whenever the outline view’s selection changes.
- (void)outlineViewSelectionIsChanging:(NSNotification *)notification
This method is invoked as a result of posting an NSOutlineViewSelectionIsChangingNotification.
NSOutlineView.hThis constant defines an index that allows you to drop an item directly on a target.
enum {
NSOutlineViewDropOnItemIndex = -1
};
NSOutlineViewDropOnItemIndexMay be used as a valid child index of a drop target item.
In this case, the drop will happen directly on the target item.
Available in Mac OS X v10.0 and later.
Declared in NSOutlineView.h.
NSOutlineView.hPosted whenever a column is moved by user action in an NSOutlineView object.
The notification object is the NSOutlineView object in which a column moved. The userInfo dictionary contains the following information:
Key | Value |
|---|---|
| An |
| An |
– moveColumn:toColumn: (NSTableView)NSOutlineView.hPosted whenever a column is resized in an NSOutlineView object.
The notification object is the NSOutlineView object in which a column was resized. The userInfo dictionary contains the following information:
Key | Value |
|---|---|
| The column that was resized. |
| An |
NSOutlineView.hPosted whenever an item is collapsed in an NSOutlineView object.
The notification object is the NSOutlineView object in which an item was collapsed. A collapsed item’s children lose their status as being selected. The userInfo dictionary contains the following information:
Key | Value |
|---|---|
| The item that was collapsed (an id) |
NSOutlineView.hPosted whenever an item is expanded in an NSOutlineView object.
The notification object is the NSOutlineView object in which an item was expanded. The userInfo dictionary contains the following information:
Key | Value |
|---|---|
| The item that was expanded (an |
NSOutlineView.hPosted before an item is collapsed (after the user clicks the arrow but before the item is collapsed).
The notification object is the NSOutlineView object that contains the item about to be collapsed. A collapsed item’s children will lose their status as being selected. The userInfo dictionary contains the following information:
Key | Value |
|---|---|
| The item about to be collapsed (an id) |
NSOutlineView.hPosted before an item is expanded (after the user clicks the arrow but before the item is collapsed).
The notification object is the outline view that contains an item about to be expanded. The userInfo dictionary contains the following information:
Key | Value |
|---|---|
| The item that is to be expanded (an |
NSOutlineView.hPosted after the outline view's selection changes.
The notification object is the outline view whose selection changed. This notification does not contain a userInfo dictionary.
NSOutlineView.hPosted as the outline view’s selection changes (while the mouse button is still down).
The notification object is the outline view whose selection is changing. This notification does not contain a userInfo dictionary.
NSOutlineView.hLast updated: 2009-11-17
Mac OS X Reference Library User Experience: Data Presentation NSOutlineView Class Reference