NSOutlineView Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/AppKit.framework |
| Availability | Available in OS X v10.0 and later. |
| Declared in | NSOutlineView.h |
| Companion guides | |
Overview
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.
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
NSOutlineViewDataSourceprotocol).The view retrieves only the data that needs to be displayed.
Subclassing
Subclassing NSOutlineView is not recommended. Customization can be accomplished in your datasource class implementation (conforming to the NSOutlineViewDataSource protocol) or your delegate class implementation (conforming to the NSOutlineViewDelegate protocol).
Tasks
Setting the Data Source
Working with Expandability
Expanding and Collapsing the Outline
Redisplaying Information
Converting Between Items and Rows
Working with the Outline Column
-
– setOutlineTableColumn: -
– outlineTableColumn -
– autoresizesOutlineColumn -
– setAutoresizesOutlineColumn:
Working with Indentation
-
– levelForItem: -
– levelForRow: -
– setIndentationPerLevel: -
– indentationPerLevel -
– setIndentationMarkerFollowsCell: -
– indentationMarkerFollowsCell
Working with Persistence
Supporting Drag and Drop
Getting the Parent for an Item
Getting the Frame for a Cell
Getting and Setting the Delegate
Instance Methods
autoresizesOutlineColumn
Returns a Boolean value that indicates whether the receiver automatically resizes its outline column when the user expands or collapses items.
Return Value
YES if the outline column is automatically resized, otherwise NO.
Discussion
The outline column contains the cells with the expansion symbols and is generally the first column. The default is YES.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSOutlineView.hautosaveExpandedItems
Returns a Boolean value that indicates whether the expanded items in the receiver are automatically saved.
Return Value
YES if when an item is expanded, the outline view displays the previous expanded state of its contained items, otherwise NO.
Discussion
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.
Special Considerations
Starting in OS X version 10.5, the value for autosaveExpandedItems is saved out in the nib file. The default value is NO.
Availability
- Available in OS X v10.0 and later.
See Also
-
autosaveName(NSTableView) -
autosaveTableColumns(NSTableView) -
– setAutosaveExpandedItems:
Declared In
NSOutlineView.hcollapseItem:
Collapses a given item.
Parameters
- item
An item in the receiver.
Discussion
If item is not expanded or not expandable, does nothing
If collapsing takes place, posts item collapse notification.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSOutlineView.hcollapseItem:collapseChildren:
Collapses a given item and, optionally, its children.
Parameters
- item
An item in the receiver.
Starting in OS X version 10.5, passing
'nil'will collapse each item under the root in the outline view.- collapseChildren
If
YES, recursively collapses item and its children. IfNO, collapses item only (identical tocollapseItem:).
Discussion
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.
Availability
- Available in OS X v10.0 and later.
Declared In
NSOutlineView.hdataSource
Returns the object that provides the data displayed by the receiver.
Return Value
The object that provides the data displayed by the receiver.
Discussion
See “Writing an Outline View Data Source” and the NSOutlineViewDataSource Protocol Reference informal protocol specification for more information.
Availability
- Available in OS X v10.6 and later.
See Also
Declared In
NSOutlineView.hdelegate
Returns the receiver’s delegate.
Return Value
The receiver’s delegate.
Availability
- Available in OS X v10.6 and later.
See Also
Declared In
NSOutlineView.hexpandItem:
Expands a given item.
Parameters
- item
An item in the receiver.
Discussion
If item is not expandable or is already expanded, does nothing.
If expanding takes place, posts an item expanded notification.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSOutlineView.hexpandItem:expandChildren:
Expands a specified item and, optionally, its children.
Parameters
- item
An item in the receiver.
Starting in OS X version 10.5, passing
'nil'will expand each item under the root in the outline view.- expandChildren
If
YES, recursively expands item and its children. IfNO, expands item only (identical toexpandItem:).
Discussion
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.
Availability
- Available in OS X v10.0 and later.
Declared In
NSOutlineView.hframeOfOutlineCellAtRow:
Returns the frame of the outline cell for a given row.
Parameters
- row
The index of the row for which to return the frame.
Return Value
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.
Discussion
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.
Availability
- Available in OS X v10.5 and later.
Declared In
NSOutlineView.hindentationMarkerFollowsCell
Returns 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.
Return Value
YES if the indentation marker is indented along with the cell contents, otherwise NO.
Discussion
The default is YES.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSOutlineView.hindentationPerLevel
Returns the current indentation per level.
Return Value
The current indentation per level, in points.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSOutlineView.hisExpandable:
Returns a Boolean value that indicates whether a given item is expandable.
Parameters
- item
An item in the receiver.
Return Value
YES if item is expandable—that is, item can contain other items, otherwise NO.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSOutlineView.hisItemExpanded:
Returns a Boolean value that indicates whether a given item is expanded.
Parameters
- item
An item in the receiver.
Return Value
YES if item is expanded, otherwise NO.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSOutlineView.hitemAtRow:
Returns the item associated with a given row.
Parameters
- row
The index of a row in the receiver.
Return Value
The item associated with row.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSOutlineView.hlevelForItem:
Returns the indentation level for a given item.
Parameters
- item
An item in the receiver.
Return Value
The indentation level for item. If item is nil (which is the root item), returns –1.
Discussion
The levels are zero-based—that is, the first level of displayed items is level 0.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSOutlineView.hlevelForRow:
Returns the indentation level for a given row.
Parameters
- row
The index of a row in the receiver.
Return Value
The indentation level for row. For an invalid row, returns –1.
Discussion
The levels are zero-based—that is, the first level of displayed items is level 0.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSOutlineView.houtlineTableColumn
Returns the table column in which hierarchical data is displayed.
Return Value
The table column in which hierarchical data is displayed.
Discussion
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.
Special Considerations
Starting in OS X version 10.5, outline table column data is saved in encodeWithCoder: and restored in initWithCoder:.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSOutlineView.hparentForItem:
Returns the parent for a given item.
Parameters
- item
The item for which to return the parent.
Return Value
The parent for item, or nil if the parent is the root.
Availability
- Available in OS X v10.5 and later.
Declared In
NSOutlineView.hreloadItem:
Reloads and redisplays the data for item.
Parameters
- item
The item to reload and display
Discussion
This method may cause the outline view to change it’s selection unexpectedly.
Special Considerations
In OS X v 10.6 and earlier, this method will not invoke the outlineViewSelectionDidChange: delegate method.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSOutlineView.hreloadItem:reloadChildren:
Reloads a given item and, optionally, its children.
Parameters
- item
An item in the receiver.
Starting in OS X version 10.5, passing
'nil'will reload everything under the root in the outline view.- reloadChildren
If
YES, recursively reloads item and its children. IfNO, reloads item only (identical toreloadItem:).It is not necessary, or efficient, to reload children if the item is not expanded.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSOutlineView.hrowForItem:
Returns the row associated with a given item.
Parameters
- item
An item in the receiver.
Return Value
The row associated with item, or –1 if item is nil or cannot be found.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSOutlineView.hsetAutoresizesOutlineColumn:
Sets whether the receiver automatically resizes its outline column when the user expands or collapses an item.
Parameters
- resize
YESif the outline column is automatically resized, otherwiseNO.
Discussion
The outline column contains the cells with the expansion symbols and is generally the first column. The default is YES.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSOutlineView.hsetAutosaveExpandedItems:
Sets whether the expanded items in the receiver are automatically saved.
Discussion
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.
Special Considerations
Starting in OS X version 10.5, the value for autosaveExpandedItems is saved out in the nib file. The default value is NO.
Availability
- Available in OS X v10.0 and later.
See Also
-
– autosaveExpandedItems -
setAutosaveTableColumns:(NSTableView)
Declared In
NSOutlineView.hsetDataSource:
Sets the receiver’s data source to a given object.
Parameters
- anObject
The data source for the receiver. The object must implement the appropriate methods of the NSOutlineViewDataSource Protocol Reference informal protocol.
Discussion
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:.
Availability
- Available in OS X v10.6 and later.
See Also
Declared In
NSOutlineView.hsetDelegate:
Sets the receiver’s delegate.
Parameters
- anObject
The delegate for the receiver. The delegate must conform to the
NSOutlineViewDelegate Protocolprotocol.
Availability
- Available in OS X v10.6 and later.
See Also
Declared In
NSOutlineView.hsetDropItem:dropChildIndex:
Used to “retarget” a proposed drop.
Parameters
- item
The target item.
- index
The drop index.
Discussion
For example, to specify a drop on someOutlineItem, you specify item as someOutlineItem and index as NSOutlineViewDropOnItemIndex. To specify a drop between child 2 and 3 of someOutlineItem, you specify item as someOutlineItem and index as 3 (children are a zero-based index). To specify a drop on an un-expandable someOutlineItem, you specify item as someOutlineItem and index as NSOutlineViewDropOnItemIndex.
Availability
- Available in OS X v10.0 and later.
Declared In
NSOutlineView.hsetIndentationMarkerFollowsCell:
Sets 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.
Discussion
The default is YES, the indentation marker is indented along with the cell contents.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSOutlineView.hsetIndentationPerLevel:
Sets the per-level indentation.
Parameters
- newIndentLevel
The indentation per level, in points.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSOutlineView.hsetOutlineTableColumn:
Sets the table column in which hierarchical data is displayed.
Parameters
- outlineTableColumn
The table column in which hierarchical data is displayed.
Special Considerations
Starting in OS X version 10.5, outline table column data is saved in encodeWithCoder: and restored in initWithCoder:.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSOutlineView.hshouldCollapseAutoExpandedItemsForDeposited:
Returns a Boolean value that indicates whether autoexpanded items should return to their original collapsed state.
Return Value
YES if autoexpanded items should return to their original collapsed state, otherwise NO.
Discussion
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).
Availability
- Available in OS X v10.0 and later.
Declared In
NSOutlineView.hConstants
Drop on Item Index
This constant defines an index that allows you to drop an item directly on a target.
enum {
NSOutlineViewDropOnItemIndex = -1
};
Constants
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 OS X v10.0 and later.
Declared in
NSOutlineView.h.
Declared In
NSOutlineView.hNotifications
NSOutlineViewColumnDidMoveNotification
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 |
Availability
- Available in OS X v10.0 and later.
See Also
-
moveColumn:toColumn:(NSTableView)
Declared In
NSOutlineView.hNSOutlineViewColumnDidResizeNotification
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 |
Availability
- Available in OS X v10.0 and later.
Declared In
NSOutlineView.hNSOutlineViewItemDidCollapseNotification
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) |
Availability
- Available in OS X v10.0 and later.
Declared In
NSOutlineView.hNSOutlineViewItemDidExpandNotification
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 |
Availability
- Available in OS X v10.0 and later.
Declared In
NSOutlineView.hNSOutlineViewItemWillCollapseNotification
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) |
Availability
- Available in OS X v10.0 and later.
Declared In
NSOutlineView.hNSOutlineViewItemWillExpandNotification
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 |
Availability
- Available in OS X v10.0 and later.
Declared In
NSOutlineView.hNSOutlineViewSelectionDidChangeNotification
The notification object is the outline view whose selection changed. This notification does not contain a userInfo dictionary.
Availability
- Available in OS X v10.0 and later.
Declared In
NSOutlineView.hNSOutlineViewSelectionIsChangingNotification
The notification object is the outline view whose selection is changing. This notification does not contain a userInfo dictionary.
Availability
- Available in OS X v10.0 and later.
Declared In
NSOutlineView.h© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-01-13)