Next Page > Hide TOC

NSOutlineView Class Reference

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.

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:

Tasks

Setting the Data Source

• – setDataSource:
• – dataSource

Working with Expandability

• – isExpandable:
• – isItemExpanded:

Expanding and Collapsing the Outline

• – outlineView:shouldExpandItem:  delegate method
• – outlineViewItemWillExpand:  delegate method
• – expandItem:
• – expandItem:expandChildren:
• – outlineViewItemDidExpand:  delegate method
• – outlineView:shouldCollapseItem:  delegate method
• – outlineViewItemWillCollapse:  delegate method
• – collapseItem:
• – collapseItem:collapseChildren:
• – outlineViewItemDidCollapse:  delegate method

Redisplaying Information

• – reloadItem:
• – reloadItem:reloadChildren:

Converting Between Items and Rows

• – itemAtRow:
• – rowForItem:

Working with the Outline Column

• – setOutlineTableColumn:
• – outlineTableColumn
• – autoresizesOutlineColumn
• – setAutoresizesOutlineColumn:

Working with Indentation

• – levelForItem:
• – levelForRow:
• – setIndentationPerLevel:
• – indentationPerLevel
• – setIndentationMarkerFollowsCell:
• – indentationMarkerFollowsCell

Working with Persistence

• – autosaveExpandedItems
• – setAutosaveExpandedItems:

Supporting Drag and Drop

• – setDropItem:dropChildIndex:
• – shouldCollapseAutoExpandedItemsForDeposited:

Getting the Parent for an Item

• – parentForItem:

Getting the Frame for a Cell

• – frameOfOutlineCellAtRow:

Supporting Type Select

• – outlineView:typeSelectStringForTableColumn:item:  delegate method
• – outlineView:nextTypeSelectMatchFromItem:toItem:forString:  delegate method
• – outlineView:shouldTypeSelectForEvent:withCurrentSearchString:  delegate method

Working with Tooltips

• – outlineView:toolTipForCell:rect:tableColumn:item:mouseLocation:  delegate method
• – outlineView:shouldShowCellExpansionForTableColumn:item:  delegate method

Handling Selection

• – outlineView:shouldSelectTableColumn:  delegate method
• – outlineView:shouldSelectItem:  delegate method
• – outlineView:selectionIndexesForProposedSelection:  delegate method
• – selectionShouldChangeInOutlineView:  delegate method
• – outlineViewSelectionIsChanging:  delegate method
• – outlineViewSelectionDidChange:  delegate method

Displaying Cells

• – outlineView:willDisplayCell:forTableColumn:item:  delegate method
• – outlineView:willDisplayOutlineCell:forTableColumn:item:  delegate method
• – outlineView:dataCellForTableColumn:item:  delegate method

Moving and Resizing Columns

• – outlineViewColumnDidMove:  delegate method
• – outlineViewColumnDidResize:  delegate method

Editing Items

• – outlineView:shouldEditTableColumn:item:  delegate method

Working with Table Columns

• – outlineView:mouseDownInHeaderOfTableColumn:  delegate method
• – outlineView:didClickTableColumn:  delegate method
• – outlineView:didDragTableColumn:  delegate method

Returning Row Height Information

• – outlineView:heightOfRowByItem:  delegate method

Customizing Tracking Support

• – outlineView:shouldTrackCell:forTableColumn:item:  delegate method

Grouping Rows

• – outlineView:isGroupItem:  delegate method

Instance Methods

autoresizesOutlineColumn

Returns a Boolean value that indicates whether the receiver automatically resizes its outline column when the user expands or collapses items.

- (BOOL)autoresizesOutlineColumn

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 Mac OS X v10.0 and later.

See Also

• – setAutoresizesOutlineColumn:

Declared In

autosaveExpandedItems

Returns a Boolean value that indicates whether the expanded items in the receiver are automatically saved.

- (BOOL)autosaveExpandedItems

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 Mac OS X version 10.5, the value for autosaveExpandedItems is saved out in the nib file. The default value is NO.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – autosaveName (NSTableView)
• – autosaveTableColumns (NSTableView)
• – setAutosaveExpandedItems:

Declared In

collapseItem:

Collapses a given item.

- (void)collapseItem:(id)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 Mac OS X v10.0 and later.

See Also

• – expandItem:

Declared In

collapseItem:collapseChildren:

Collapses a given item and, optionally, its children.

- (void)collapseItem:(id)item collapseChildren:(BOOL)collapseChildren

Parameters

item

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.

collapseChildren

If YES, recursively collapses item and its children. If NO, collapses item only (identical to collapseItem:).

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 Mac OS X v10.0 and later.

See Also

• – collapseItem:
• – expandItem:expandChildren:

Declared In

dataSource

Returns the object that provides the data displayed by the receiver.

- (id)dataSource

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.

See Also

• – setDataSource:

expandItem:

Expands a given item.

- (void)expandItem:(id)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 Mac OS X v10.0 and later.

See Also

• – collapseItem:

Declared In

expandItem:expandChildren:

Expands a specified item and, optionally, its children.

- (void)expandItem:(id)item expandChildren:(BOOL)expandChildren

Parameters

item

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.

expandChildren

If YES, recursively expands item and its children. If NO, expands item only (identical to expandItem:).

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 Mac OS X v10.0 and later.

See Also

• – collapseItem:collapseChildren:
• – expandItem:

Declared In

frameOfOutlineCellAtRow:

Returns the frame of the outline cell for a given row.

- (NSRect)frameOfOutlineCellAtRow:(NSInteger)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 Mac OS X v10.5 and later.

Declared In

indentationMarkerFollowsCell

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.

- (BOOL)indentationMarkerFollowsCell

Return Value

YES if the indentation marker is indented along with the cell contents, otherwise NO.

Discussion

The default is YES.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setIndentationMarkerFollowsCell:

Declared In

indentationPerLevel

Returns the current indentation per level.

- (CGFloat)indentationPerLevel

Return Value

The current indentation per level, in points.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setIndentationPerLevel:

Declared In

isExpandable:

Returns a Boolean value that indicates whether a given item is expandable.

- (BOOL)isExpandable:(id)item

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 Mac OS X v10.0 and later.

See Also

• – expandItem:
• – isItemExpanded:

Declared In

isItemExpanded:

Returns a Boolean value that indicates whether a given item is expanded.

- (BOOL)isItemExpanded:(id)item

Parameters

item

An item in the receiver.

Return Value

YES if item is expanded, otherwise NO.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – expandItem:
• – isExpandable:

Declared In

itemAtRow:

Returns the item associated with a given row.

- (id)itemAtRow:(NSInteger)row

Parameters

row

The index of a row in the receiver.

Return Value

The item associated with row.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – rowForItem:

Declared In

levelForItem:

Returns the indentation level for a given item.

- (NSInteger)levelForItem:(id)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 Mac OS X v10.0 and later.

See Also

• – indentationPerLevel
• – levelForRow:

Declared In

levelForRow:

Returns the indentation level for a given row.

- (NSInteger)levelForRow:(NSInteger)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 Mac OS X v10.0 and later.

See Also

• – indentationPerLevel
• – levelForItem:

Declared In

outlineTableColumn

Returns the table column in which hierarchical data is displayed.

- (NSTableColumn *)outlineTableColumn

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 Mac OS X version 10.5, outline table column data is saved in encodeWithCoder: and restored in initWithCoder:.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – setOutlineTableColumn:

Declared In

parentForItem:

Returns the parent for a given item.

- (id)parentForItem:(id)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 Mac OS X v10.5 and later.

Declared In

reloadItem:

Reloads and redisplays the data for item.

- (void)reloadItem:(id)item

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – reloadItem:reloadChildren:

Declared In

reloadItem:reloadChildren:

Reloads a given item and, optionally, its children.

- (void)reloadItem:(id)item reloadChildren:(BOOL)reloadChildren

Parameters

item

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.

reloadChildren

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.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – reloadItem:

Declared In

rowForItem:

Returns the row associated with a given item.

- (NSInteger)rowForItem:(id)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 Mac OS X v10.0 and later.

See Also

• – itemAtRow:

Declared In

setAutoresizesOutlineColumn:

Sets whether the receiver automatically resizes its outline column when the user expands or collapses an item.

- (void)setAutoresizesOutlineColumn:(BOOL)resize

Parameters

resize

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 Mac OS X v10.0 and later.

See Also

• – autoresizesOutlineColumn

Declared In

setAutosaveExpandedItems:

Sets whether the expanded items in the receiver are automatically saved.

- (void)setAutosaveExpandedItems:(BOOL)flag

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 Mac OS X version 10.5, the value for autosaveExpandedItems is saved out in the nib file. The default value is NO.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – autosaveExpandedItems
• – setAutosaveTableColumns: (NSTableView)

Declared In

setDataSource:

Sets the receiver’s data source to a given object.

- (void)setDataSource:(id)anObject

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:.

See Also

• – dataSource

setDropItem:dropChildIndex:

Used to “retarget” a proposed drop.

- (void)setDropItem:(id)item dropChildIndex:(NSInteger)index

Discussion

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.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

setIndentationMarkerFollowsCell:

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.

- (void)setIndentationMarkerFollowsCell:(BOOL)drawInCell

Discussion

The default is YES, the indentation marker is indented along with the cell contents.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – indentationMarkerFollowsCell

Declared In

setIndentationPerLevel:

Sets the per-level indentation.

- (void)setIndentationPerLevel:(CGFloat)newIndentLevel

Parameters

newIndentLevel

The indentation per level, in points.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – indentationPerLevel

Declared In

setOutlineTableColumn:

Sets the table column in which hierarchical data is displayed.

- (void)setOutlineTableColumn:(NSTableColumn *)outlineTableColumn

Parameters

outlineTableColumn

The table column in which hierarchical data is displayed.

Special Considerations

Starting in Mac OS X version 10.5, outline table column data is saved in encodeWithCoder: and restored in initWithCoder:.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – outlineTableColumn

Declared In

shouldCollapseAutoExpandedItemsForDeposited:

Returns a Boolean value that indicates whether autoexpanded items should return to their original collapsed state.

- (BOOL)shouldCollapseAutoExpandedItemsForDeposited:(BOOL)deposited

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 Mac OS X v10.0 and later.

Declared In

Delegate Methods

outlineView:dataCellForTableColumn:item:

Returns the cell to use in a given column for a given item.

- (NSCell *)outlineView:(NSOutlineView *)outlineView dataCellForTableColumn:(NSTableColumn *)tableColumn item:(id)item

Parameters

outlineView

The outline view that sent the message.

tableColumn

The table column for which the cell is required. This value may be nil.

item

The item for which the cell is required.

Return Value

The cell to use in column tableColumn for item item, or nil (see Discussion). The cell must properly implement copyWithZone: (since it may be copied by by the outline view).

Discussion

You can return a different data cell for any particular combination of table column and item, or a cell that will be used for the entire row (a full width cell). If tableColumn is non-nil, you should return a cell. Typically you should default to returning the result from [tableColumn dataCellForRow:row].

When each row (identified by the item) is being drawn, this method is first called with a nil value for tableColumn. At this time, you can return a cell that will be used to draw the entire row, acting like a group. If you do return a cell for the 'nil' table column, your implementations of the other corresponding datasource and delegate methods must be prepared to be invoked with a nil value for tableColumn. If do not return a cell for the 'nil' table column, the method will be called once for each column in the outline view, as usual.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

outlineView:didClickTableColumn:

Sent at the time the mouse button subsequently goes up in outlineView and tableColumn has been “clicked” without having been dragged anywhere.

- (void)outlineView:(NSOutlineView *)outlineView didClickTableColumn:(NSTableColumn *)tableColumn

Availability

• Available in Mac OS X v10.3 and later.

Declared In

outlineView:didDragTableColumn:

Sent at the time the mouse button goes up in outlineView and tableColumn has been dragged during the time the mouse button was down.

- (void)outlineView:(NSOutlineView *)outlineView didDragTableColumn:(NSTableColumn *)tableColumn

Availability

• Available in Mac OS X v10.3 and later.

Declared In

outlineView:heightOfRowByItem:

Returns the height in points of the row containing item.

- (CGFloat)outlineView:(NSOutlineView *)outlineView heightOfRowByItem:(id)item

Discussion

Values returned by this method should not include intercell spacing and must be greater than 0. Implement this method to support an outline view with varying row heights.

Special Considerations

For large tables in particular, you should make sure that this method is efficient. NSTableView may cache the values this method returns, so if you would like to change a row's height make sure to invalidate the row height by calling noteHeightOfRowsWithIndexesChanged:. NSTableView automatically invalidates its entire row height cache in reloadData and noteNumberOfRowsChanged.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

outlineView:isGroupItem:

Returns a Boolean that indicates whether a given row should be drawn in the “group row” style.

- (BOOL)outlineView:(NSOutlineView *)outlineView isGroupItem:(id)item

Parameters

outlineView

The outline view that sent the message.

item

An item in the outline view.

Return Value

YES to indicate a particular row should have the "group row" style drawn for that row, otherwise NO.

Discussion

If the cell in that row is an instance of NSTextFieldCell and contains only a string value, the “group row” style attributes are automatically applied for that cell.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

outlineView:mouseDownInHeaderOfTableColumn:

Sent to the delegate whenever the mouse button is clicked in outlineView while the cursor is in a column header tableColumn.

- (void)outlineView:(NSOutlineView *)outlineView mouseDownInHeaderOfTableColumn:(NSTableColumn *)tableColumn

Availability

• Available in Mac OS X v10.3 and later.

Declared In

outlineView:nextTypeSelectMatchFromItem:toItem:forString:

Returns the first item that matches the searchString from within the range of startItem to endItem

- (id)outlineView:(NSOutlineView *)outlineView nextTypeSelectMatchFromItem:(id)startItem toItem:(id)endItem forString:(NSString *)searchString

Parameters

outlineView

The outline view that sent the message.

startItem

The first item to search.

endItem

The item before which to stop searching. It is possible for endItem to be less than startItem if the search will wrap.

searchString

The string for which to search.

Return Value

The first item—from within the range of startItem to endItem—that matches the searchString, or nil if there is no match.

Discussion

Implement this method if you want to control how type selection works. You should include startItem as a possible match, but do not include endItem.

It is not necessary to implement this method in order to support type select.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

outlineView:selectionIndexesForProposedSelection:

Invoked to allow the delegate to modify the proposed selection.

- (NSIndexSet *)outlineView:(NSOutlineView *)outlineView selectionIndexesForProposedSelection:(NSIndexSet *)proposedSelectionIndexes

Parameters

outlineView

The outline view that sent the message.

proposedSelectionIndexes

An index set containing the indexes of the proposed selection.

Return Value

An NSIndexSet instance containing the indexes of the new selection. Return proposedSelectionIndexes if the proposed selection is acceptable, or the value of the table view’s existing selection to avoid changing the selection.

Discussion

This method may be called multiple times with one new index added to the existing selection to find out if a particular index can be selected when the user is extending the selection with the keyboard or mouse.

Implementation of this method is optional. If implemented, this method will be called instead of outlineView:shouldSelectItem:.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

outlineView:shouldCollapseItem:

Returns a Boolean value that indicates whether the outline view should collapse a given item.

- (BOOL)outlineView:(NSOutlineView *)outlineView shouldCollapseItem:(id)item

Parameters

outlineView

The outline view that sent the message.

item

The item that should collapse.

Return Value

YES to permit outlineView to collapse item, NO to deny permission.

Discussion

The delegate can implement this method to disallow collapsing of specific items. For example, if the first row of your outline view should not be collapsed, your delegate method could contain this line of code:

return [outlineView rowForItem:item]!=0;

Availability

• Available in Mac OS X v10.0 and later.

Declared In

outlineView:shouldEditTableColumn:item:

Returns a Boolean value that indicates whether the outline view should allow editing of a given item in a given table column.

- (BOOL)outlineView:(NSOutlineView *)outlineView shouldEditTableColumn:(NSTableColumn *)tableColumn item:(id)item

Return Value

YES to permit outlineView to edit the cell specified by tableColumn and item, NO to deny permission.

If this method returns YES, the cell may still not be editable—for example, if you have set up a custom NSTextFieldCell as a data cell, it must return YES for isEditable to allow editing.

Discussion

The delegate can implement this method to disallow editing of specific cells.

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – outlineView:setObjectValue:forTableColumn:byItem:

Declared In

outlineView:shouldExpandItem:

Returns a Boolean value that indicates whether the outline view should expand a given item.

- (BOOL)outlineView:(NSOutlineView *)outlineView shouldExpandItem:(id)item

Parameters

outlineView

The outline view that sent the message.

item

The item that should expand.

Return Value

YES to permit outlineView to expand item, NO to deny permission.

Discussion

The delegate can implement this method to disallow expanding of specific items.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

outlineView:shouldSelectItem:

Returns a Boolean value that indicates whether the outline view should select a given item.

- (BOOL)outlineView:(NSOutlineView *)outlineView shouldSelectItem:(id)item

Return Value

YES to permit outlineView to select item, NO to deny permission.

Discussion

The delegate can implement this method to disallow selection of particular items.

For better performance and finer grain control over the selection, use outlineView:selectionIndexesForProposedSelection:.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

outlineView:shouldSelectTableColumn:

Returns a Boolean value that indicates whether the outline view should select a given table column.

- (BOOL)outlineView:(NSOutlineView *)outlineView shouldSelectTableColumn:(NSTableColumn *)tableColumn

Return Value

YES to permit outlineView to select tableColumn, NO to deny permission.

Discussion

The delegate can implement this method to disallow selection of specific columns.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

outlineView:shouldShowCellExpansionForTableColumn:item:

Returns a Boolean value that indicates whether an expansion tooltip should appear in a given column for a given item.

- (BOOL)outlineView:(NSOutlineView *)outlineView shouldShowCellExpansionForTableColumn:(NSTableColumn *)tableColumn item:(id)item

Parameters

outlineView

The outline view that sent the message.

tableColumn

A table column in the outline view.

item

An item in the outline view.

Return Value

YES to allow an expansion tooltip to appear in the column tableColumn for item item, otherwise NO.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

outlineView:shouldTrackCell:forTableColumn:item:

Returns a Boolean value that indicates whether a given cell should be tracked.

- (BOOL)outlineView:(NSOutlineView *)outlineView shouldTrackCell:(NSCell *)cell forTableColumn:(NSTableColumn *)tableColumn item:(id)item

Parameters

outlineView

The outline view that sent the message.

cell

The cell used to display item item in column tableColumn

tableColumn

A table column in the outline view.

item

An item in the outline view.

Return Value

YES if the cell should be tracked for the item item in column tableColumn, otherwise NO.

Discussion

Normally, only selectable or selected cells can be tracked. If you implement this method, cells which are not selectable or selected can be tracked (and vice-versa). For example, this allows you to have a button cell in a table which does not change the selection, but can still be clicked on and tracked.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

outlineView:shouldTypeSelectForEvent:withCurrentSearchString:

Returns a Boolean value that indicates whether type select should proceed for a given event and search string.

- (BOOL)outlineView:(NSOutlineView *)outlineView shouldTypeSelectForEvent:(NSEvent *)event withCurrentSearchString:(NSString *)searchString

Parameters

outlineView

The outline view that sent the message.

event

The event that caused the message to be sent.

searchString

The string for which searching is to proceed. The search string is nil if no type select has begun.

Return Value

YES if type select should proceed, otherwise NO.

Discussion

Generally, this method will be called from keyDown: and the event will be a key event.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

outlineView:toolTipForCell:rect:tableColumn:item:mouseLocation:

When the cursor pauses over a given cell, the value returned from this method is displayed in a tooltip.

- (NSString *)outlineView:(NSOutlineView *)ov toolTipForCell:(NSCell *)cell rect:(NSRectPointer)rect tableColumn:(NSTableColumn *)tc item:(id)item mouseLocation:(NSPoint)mouseLocation

Parameters

ov

The outline view that sent the message.

cell

The cell for which to generate a tooltip.

rect

The proposed active area of the tooltip. To control the default active area, you can modify the rect parameter. By default, rect is computed as [cell drawingRectForBounds:cellFrame].

tc

The table column that contains cell.

item

The item for which to display a tooltip.

mouseLocation

The current mouse location in view coordinates.

Return Value

If you don’t want a tooltip at that location, return nil or the empty string.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

outlineView:typeSelectStringForTableColumn:item:

Returns the string that is used for type selection for a given column and item.

- (NSString *)outlineView:(NSOutlineView *)outlineView typeSelectStringForTableColumn:(NSTableColumn *)tableColumn item:(id)item

Parameters

outlineView

The outline view that sent the message.

tableColumn

A table column in the outline view.

item

An item in the outline view.

Return Value

The string that is used for type selection. You may want to change what is searched for based on what is displayed, or simply return nil for that row and/or column to not be searched

Discussion

Implement this method if you want to control the string that is used for type selection. You may want to change what is searched for based on what is displayed, or simply return nil to specify that the given row and/or column should not be searched. By default, all cells with text in them are searched.

The default value when this delegate method is not implemented is:

[[outlineView preparedCellAtColumn:tableColumn row:[outlineView rowForItem:item]] stringValue]

and you can return this value from the delegate method if you wish.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

outlineView:willDisplayCell:forTableColumn:item:

Informs the delegate that outlineView is about to display the cell specified by tableColumn and item.

- (void)outlineView:(NSOutlineView *)outlineView willDisplayCell:(id)cell forTableColumn:(NSTableColumn *)tableColumn item:(id)item

Discussion

The delegate can modify cell to alter its display attributes; for example, making uneditable values display in italic or gray text.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

outlineView:willDisplayOutlineCell:forTableColumn:item:

Informs the delegate that an outline view is about to display a cell used to draw the expansion symbol.

- (void)outlineView:(NSOutlineView *)outlineView willDisplayOutlineCell:(id)cell forTableColumn:(NSTableColumn *)tableColumn item:(id)item

Discussion

Informs the delegate that outlineView is about to display cell—an expandable cell (a cell that has the expansion symbol)—for the column and item specified by tableColumn and item. The delegate can modify cell to alter its display attributes.

This method is not invoked when outlineView is about to display a non-expandable cell.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

outlineViewColumnDidMove:

Invoked when notification is posted—that is, whenever the user moves a column in the outline view.

- (void)outlineViewColumnDidMove:(NSNotification *)notification

Discussion

This method is invoked as a result of posting an NSOutlineViewColumnDidMoveNotification.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

outlineViewColumnDidResize:

Invoked when notification is posted—that is, whenever the user resizes a column in the outline view.

- (void)outlineViewColumnDidResize:(NSNotification *)notification

Discussion

This method is invoked as a result of posting an NSOutlineViewColumnDidResizeNotification.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

outlineViewItemDidCollapse:

Invoked when notification is posted—that is, whenever the user collapses an item in the outline view.

- (void)outlineViewItemDidCollapse:(NSNotification *)notification

Discussion

This method is invoked as a result of posting an NSOutlineViewItemDidCollapseNotification.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

outlineViewItemDidExpand:

Invoked when notification is posted—that is, whenever the user expands an item in the outline view.

- (void)outlineViewItemDidExpand:(NSNotification *)notification

Discussion

This method is invoked as a result of posting an NSOutlineViewItemDidExpandNotification.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

outlineViewItemWillCollapse:

Invoked when notification is posted—that is, whenever the user is about to collapse an item in the outline view.

- (void)outlineViewItemWillCollapse:(NSNotification *)notification

Discussion

This method is invoked as a result of posting an NSOutlineViewItemWillCollapseNotification.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

outlineViewItemWillExpand:

Invoked when notification is posted—that is, whenever the user is about to expand an item in the outline view.

- (void)outlineViewItemWillExpand:(NSNotification *)notification

Discussion

This method is invoked as a result of posting an NSOutlineViewItemWillExpandNotification.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

outlineViewSelectionDidChange:

Invoked when notification is posted—that is, immediately after the outline view’s selection has changed.

- (void)outlineViewSelectionDidChange:(NSNotification *)notification

Discussion

This method is invoked as a result of posting an NSOutlineViewSelectionDidChangeNotification.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

outlineViewSelectionIsChanging:

Invoked when notification is posted—that is, whenever the outline view’s selection changes.

- (void)outlineViewSelectionIsChanging:(NSNotification *)notification

Discussion

This method is invoked as a result of posting an NSOutlineViewSelectionIsChangingNotification.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

selectionShouldChangeInOutlineView:

Returns a Boolean value that indicates whether the outline view should change its selection.

- (BOOL)selectionShouldChangeInOutlineView:(NSOutlineView *)outlineView

Return Value

YES to permit outlineView to change its selection (typically a row being edited), NO to deny permission.

Discussion

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.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

Constants

Drop on Item Index

This constant defines an index that allows you to drop an item directly on a target.

enum {
   NSOutlineViewDropOnItemIndex = -1
};

Constants

NSOutlineViewDropOnItemIndex

May 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.

Declared In

Notifications

NSOutlineViewColumnDidMoveNotification

Posted 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:

Availability

• Available in Mac OS X v10.0 and later.

See Also

• – moveColumn:toColumn: (NSTableView)

Declared In

NSOutlineViewColumnDidResizeNotification

Posted 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:

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSOutlineViewItemDidCollapseNotification

Posted 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:

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSOutlineViewItemDidExpandNotification

Posted 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:

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSOutlineViewItemWillCollapseNotification

Posted 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:

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSOutlineViewItemWillExpandNotification

Posted 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:

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSOutlineViewSelectionDidChangeNotification

Posted 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.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

NSOutlineViewSelectionIsChangingNotification

Posted 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.

Availability

• Available in Mac OS X v10.0 and later.

Declared In

Next Page > Hide TOC