| Conforms to | |
| Framework | /System/Library/Frameworks/AppKit.framework |
| Availability | Available in Mac OS X v10.6 and later. |
| Declared in | NSOutlineView.h |
| Companion guides |
The NSOutlineViewDelegate protocol defines the optional methods implemented by delegates of NSOutlineView objects.
Some delegate methods have not yet migrated to the NSOutlineViewDelegate protocol, including:
– outlineView:typeSelectStringForTableColumn:item:
– outlineView:nextTypeSelectMatchFromItem:toItem:forString:
– outlineView:shouldTypeSelectForEvent:withCurrentSearchString:
– outlineView:toolTipForCell:rect:tableColumn:item:mouseLocation:
– outlineView:shouldShowCellExpansionForTableColumn:item:
– outlineView:shouldSelectTableColumn:
– outlineView:shouldSelectItem:
– outlineView:selectionIndexesForProposedSelection:
– selectionShouldChangeInOutlineView:
– outlineView:willDisplayCell:forTableColumn:item:
– outlineView:willDisplayOutlineCell:forTableColumn:item:
– outlineView:dataCellForTableColumn:item:
– outlineView:shouldShowOutlineCellForItem:
– outlineView:mouseDownInHeaderOfTableColumn:
– outlineView:didClickTableColumn:
– outlineView:didDragTableColumn:
Returns the cell to use in a given column for a given item.
- (NSCell *)outlineView:(NSOutlineView *)outlineView dataCellForTableColumn:(NSTableColumn *)tableColumn item:(id)item
The outline view that sent the message.
The table column for which the cell is required. This value may be nil.
The item for which the cell is required.
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).
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.
NSOutlineView.hSent 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
NSOutlineView.hSent 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
NSOutlineView.hReturns the height in points of the row containing item.
- (CGFloat)outlineView:(NSOutlineView *)outlineView heightOfRowByItem:(id)item
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.
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.
NSOutlineView.hReturns a Boolean that indicates whether a given row should be drawn in the “group row” style.
- (BOOL)outlineView:(NSOutlineView *)outlineView isGroupItem:(id)item
The outline view that sent the message.
An item in the outline view.
YES to indicate a particular row should have the "group row" style drawn for that row, otherwise NO.
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.
NSOutlineView.hSent 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
NSOutlineView.hReturns 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
The outline view that sent the message.
The first item to search.
The item before which to stop searching. It is possible for endItem to be less than startItem if the search will wrap.
The string for which to search.
The first item—from within the range of startItem to endItem—that matches the searchString, or nil if there is no match.
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.
NSOutlineView.hInvoked to allow the delegate to modify the proposed selection.
- (NSIndexSet *)outlineView:(NSOutlineView *)outlineView selectionIndexesForProposedSelection:(NSIndexSet *)proposedSelectionIndexes
The outline view that sent the message.
An index set containing the indexes of the proposed selection.
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.
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:willDisplayOutlineCell:forTableColumn:item:.
NSOutlineView.hReturns a Boolean value that indicates whether the outline view should collapse a given item.
- (BOOL)outlineView:(NSOutlineView *)outlineView shouldCollapseItem:(id)item
The outline view that sent the message.
The item that should collapse.
YES to permit outlineView to collapse item, NO to deny permission.
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; |
NSOutlineView.hReturns 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
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.
The delegate can implement this method to disallow editing of specific cells.
– outlineView:setObjectValue:forTableColumn:byItem:NSOutlineView.hReturns a Boolean value that indicates whether the outline view should expand a given item.
- (BOOL)outlineView:(NSOutlineView *)outlineView shouldExpandItem:(id)item
The outline view that sent the message.
The item that should expand.
YES to permit outlineView to expand item, NO to deny permission.
The delegate can implement this method to disallow expanding of specific items.
NSOutlineView.hSent to the delegate to allow or prohibit the specified column to be dragged to a new location.
- (BOOL)outlineView:(NSOutlineView *)outlineView shouldReorderColumn:(NSInteger)columnIndex toColumn:(NSInteger)newColumnIndex
The outline view that sent the message.
The index of the column being dragged.
The proposed target index of the column.
YES if the column reordering should be allowed, otherwise NO.
When a column is initially dragged by the user, the delegate is first called with a newColumnIndex value of -1. Returning NO will disallow that column from being reordered at all. Returning YES allows it to be reordered, and the delegate will be called again when the column reaches a new location.
The actual NSTableColumn instance can be retrieved from the tableColumns array.
If this method is not implemented, all columns are considered reorderable.
NSOutlineView.hReturns a Boolean value that indicates whether the outline view should select a given item.
- (BOOL)outlineView:(NSOutlineView *)outlineView shouldSelectItem:(id)item
YES to permit outlineView to select item, NO to deny permission.
The delegate can implement this method to disallow selection of particular items.
For better performance and finer grain control over the selection, use outlineView:dataCellForTableColumn:item:.
NSOutlineView.hReturns a Boolean value that indicates whether the outline view should select a given table column.
- (BOOL)outlineView:(NSOutlineView *)outlineView shouldSelectTableColumn:(NSTableColumn *)tableColumn
YES to permit outlineView to select tableColumn, NO to deny permission.
The delegate can implement this method to disallow selection of specific columns.
NSOutlineView.hReturns 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
The outline view that sent the message.
A table column in the outline view.
An item in the outline view.
YES to allow an expansion tooltip to appear in the column tableColumn for item item, otherwise NO.
NSOutlineView.hReturns a whether the specified item should display the outline cell (the disclosure triangle).
- (BOOL)outlineView:(NSOutlineView *)outlineView shouldShowOutlineCellForItem:(id)item
The outline view that sent the message.
An item in the outline view.
YES if the outline cell should be displayed, otherwise NO.
Returning NO causes frameOfOutlineCellAtRow: to return NSZeroRect, hiding the cell. In addition, the row will not be collapsable by keyboard shortcuts.
This method will only be called for expandable rows.
NSOutlineView.hReturns 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
The outline view that sent the message.
The cell used to display item item in column tableColumn
A table column in the outline view.
An item in the outline view.
YES if the cell should be tracked for the item item in column tableColumn, otherwise NO.
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.
NSOutlineView.hReturns 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
The outline view that sent the message.
The event that caused the message to be sent.
The string for which searching is to proceed. The search string is nil if no type select has begun.
YES if type select should proceed, otherwise NO.
Generally, this method will be called from keyDown: and the event will be a key event.
NSOutlineView.hInvoked to allow the delegate to provide custom sizing behavior when a column’s resize divider is double clicked.
- (CGFloat)outlineView:(NSOutlineView *)outlineView sizeToFitWidthOfColumn:(NSInteger)column
The outline view that sent the message.
The index of the column.
The width of the specified column.
By default, NSOutlineView iterates every row in the table, accesses a cell via preparedCellAtColumn:row:, and requests the cellSize to find the appropriate largest width to use.
For accurate results and performance, it is recommended that this method is implemented when using large tables. By default, large tables use a monte carlo simulation instead of interating every row.
NSOutlineView.hWhen the cursor pauses over a given cell, the value returned from this method is displayed in a tooltip.
- (NSString *)outlineView:(NSOutlineView *)outlineView toolTipForCell:(NSCell *)cell rect:(NSRectPointer)rect tableColumn:(NSTableColumn *)tc item:(id)item mouseLocation:(NSPoint)mouseLocation
The outline view that sent the message.
The cell for which to generate a tooltip.
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].
The table column that contains cell.
The item for which to display a tooltip.
The current mouse location in view coordinates.
If you don’t want a tooltip at that location, return nil or the empty string.
NSOutlineView.hReturns the string that is used for type selection for a given column and item.
- (NSString *)outlineView:(NSOutlineView *)outlineView typeSelectStringForTableColumn:(NSTableColumn *)tableColumn item:(id)item
The outline view that sent the message.
A table column in the outline view.
An item in the outline view.
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
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.
NSOutlineView.hInforms 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
The delegate can modify cell to alter its display attributes; for example, making uneditable values display in italic or gray text.
NSOutlineView.hInforms 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
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.
NSOutlineView.hReturns a Boolean value that indicates whether the outline view should change its selection.
- (BOOL)selectionShouldChangeInOutlineView:(NSOutlineView *)outlineView
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.
NSOutlineView.hLast updated: 2009-05-29
Mac OS X Reference Library User Experience: Data Presentation NSOutlineViewDelegate Protocol Reference