Developer Documentation
PATH  Mac OS X Documentation > Application Kit Reference: Java

Table of Contents

NSOutlineView


Inherits from:
NSTableView : NSView : NSResponder : NSObject
Package:
com.apple.yellow.application

Class at a Glance


An NSOutlineView object 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.

Principal Attributes


Creation



Interface Builder

Commonly Used Methods



dataSource Returns the object that provides the data to be displayed (method of NSTableView).
numberOfRows Returns the number of rows in the NSOutlineView (method of NSTableView).
collapseItem Causes an item to be collapsed.
expandItem Causes an item to be expanded.
reloadItemAndChildren Informs the NSOutlineView that data for an item has changed and needs to be retrieved and redisplayed.


Class Description



Note: The NSOutlineView class and its supporting informal protocol NSOutlineDataSource are under development and Interface Builder does not yet include support for working with it. If you want to use an NSOutlineView, you can instantiate it programmatically, or, in Interface Builder, you can drag a table view onto your interface and change its class name to NSOutlineView.

Before reading about NSOutlineView, you should read the documentation for its parent class, NSTableView. An NSOutlineView displays data for a set of related items, with rows representing individual items and columns representing the attributes of those items. As with an NSTableView, each item in an outline view represents a set of values for a particular real-world entity, such as an employee or a bank account. In addition, NSOutlineView provides the ability to expand or collapse rows containing hierarchical data.

An item in an NSOutlineView is expandable if it can contain other items. An expandable item is distinguished visually by an expansion symbol. In Cocoa, an expandable item contains an outline triangle, which points to the right when the item is collapsed and points down when the item is expanded. Clicking on the outline triangle causes it to change position. It also causes the item to be expanded or collapsed, depending on the new state of the outline triangle. An item can be expanded even if it contains no items.

Items inside an expanded item are indented. By default, as a user expands or collapses nested items, the width of the column is resized so that it is just wide enough to display the widest item, based on the width of the items and their indentation in the hierarchy. Justification follows the current system justification. To turn off automatic resizing, use setAutoResizesOutlineColumn. Note that an item may consist of text, an image, or anything else that can be drawn by a subclass of NSCell.

An NSOutlineView is typically displayed in an NSScrollView, as shown below.

[image: Art/OutlineView.gif]

In this illustration, the NSOutlineView consists of just the rows and columns that display values. The header is drawn by two auxiliary views: a header view that draws the column headers and a corner view that draws the blank square above the vertical scroller. These auxiliary views are described in the documentation for NSTableView.


Behavior Inherited from NSTableView


An outline view inherits much of its behavior from its parent class, NSTableView. As a result, many operations supported by a table view, such as selecting rows or columns, repositioning columns by dragging column headers, and so on, are also supported by an outline view. Your application has control of these features, and can configure the view's parameters to allow or disallow certain operations. For example, you might choose not to allow editing or rearranging for specific columns.

The NSTableView class also provides methods for working with data, responding to mouse clicks, setting grid attributes, editing cells, and performing other operations. For full information on these methods, see the documentation for NSTableView.


Data Source Messages


For more information on NSOutlineView's data source methods, see "Methods Implemented By the Delegate" .


Delegate Messages


NSOutlineView adds several delegate messages to those defined by its superclass, NSTableView. In addition, it redefines certain NSTableView delegate methods to be item-based instead of row-based. Together, these methods give the delegate control over the appearance of individual cells in the table, over changes in selection, and over editing of cells.

Delegate methods that request permission to alert the selection or edit a value are invoked during user actions that affect the NSOutlineView, but are not invoked by programmatic changes to the view. When making changes programmatically, you decide whether you want the delegate to intervene and, if so, you send the appropriate message (checking first that the delegate responds to that message). Because the delegate methods involve the actual data displayed by the NSOutlineView, the delegate is typically the same object as the data source, though this is not a requirement.

NSOutlineView redefines these delegate messages based on similar messages in NSTableView:

NSOutlineView defines these additional delegate messages:

In addition to these methods, the delegate is automatically registered to receive messages corresponding to NSOutlineView notifications. These inform the delegate when the selection changes or is about to change, when a column is moved or resized, and when an item is expanded or collapsed:


Delegate Message Notification
outlineViewColumnDidMove OutlineViewColumnDidMoveNotification
outlineViewColumnDidResize OutlineViewColumnDidResizeNotification
outlineViewSelectionDidChange OutlineViewSelectionDidChangeNotification
outlineViewSelectionIsChanging OutlineViewSelectionIsChangingNotification
outlineViewItemDidExpand: OutlineViewItemDidExpandNotification
outlineViewItemDidCollapse OutlineViewItemDidCollapseNotification




Method Types


Constructors
NSOutlineView
Expanding and collapsing the outline
isExpandable
expandItem
expandItemAndChildren
collapseItem
collapseItemAndChildren
isItemExpanded
Redisplaying information
reloadItem
reloadItemAndChildren
Converting between items and rows
itemAtRow
rowForItem
Setting the outline column
setOutlineTableColumn
outlineTableColumn
Setting the indentation
levelForItem
levelForRow
setIndentationPerLevel
indentationPerLevel
setIndentationMarkerFollowsCell
indentationMarkerFollowsCell
Persistence
autosaveExpandedItems
setAutosaveExpandedItems


Constructors



NSOutlineView

public NSOutlineView()

Description forthcoming.

public NSOutlineView(NSRect aRect)

Description forthcoming.


Instance Methods



autoResizesOutlineColumn

public boolean autoResizesOutlineColumn()

Returns whether the receiver automatically resizes its outline column when the user expands or collapses items. The outline column contains the cells with the expansion symbols and is generally the first column. The default is true (the outline column is automatically resized).

autosaveExpandedItems

public boolean autosaveExpandedItems()

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

The outline view information is saved separately for each user and for each application that user uses. Note that if autosaveName returns null, this setting is ignored and outline information isn't saved.

See Also: autosaveName (NSTableView), autosaveTableColumns (NSTableView), setAutosaveExpandedItems



collapseItem

public void collapseItem(Object item)

Collapses item if item is expanded and expandable, otherwise does nothing. If collapsing takes place, posts item collapse notification.

See Also: expandItem



collapseItemAndChildren

public void collapseItemAndChildren( Object item, boolean collapseChildren)

If collapseChildren is set to false, collapses item only (identical to collapseItem). If collapseChildren is set to true, recursively collapses item and its children. For each item collapsed, posts item collapsed notification.

See Also: collapseItem



expandItem

public void expandItem(Object item)

Expands item if item is expandable and is not already expanded; otherwise, does nothing. If expanding takes place, posts item expanded notification.

See Also: collapseItem



expandItemAndChildren

public void expandItemAndChildren( Object item, boolean expandChildren)

If expandChildren is set to false, expands item only (identical to expandItem). If expandChildren is set to true, recursively expands item and its children. For each item expanded, posts item expanded notification.

See Also: collapseItemAndChildren



indentationMarkerFollowsCell

public boolean indentationMarkerFollowsCell()

Returns true if the expansion symbol in an expanded item is displayed in the cell with the item and false if the symbol is displayed system-justified in the column. The default is true.

See Also: setIndentationMarkerFollowsCell



indentationPerLevel

public float indentationPerLevel()

Returns the current indentation per level, in points.

See Also: setIndentationPerLevel



isExpandable

public boolean isExpandable(Object item)

Returns true if item is expandable-that is, item can contain other items.

See Also: expandItem, isItemExpanded



isItemExpanded

public boolean isItemExpanded(Object item)

Returns true if item is expanded.

See Also: expandItem, isExpandable



itemAtRow

public Object itemAtRow(int row)

Returns the item associated with row.

See Also: rowForItem



levelForItem

public int levelForItem(Object item)

Returns the indentation level for item.

See Also: indentationPerLevel, levelForRow



levelForRow

public int levelForRow(int row)

Returns the indentation level for row.

See Also: indentationPerLevel, levelForItem



outlineTableColumn

public NSTableColumn outlineTableColumn()

Returns the table column in which hierarchical data is displayed.

See Also: setOutlineTableColumn



reloadItem

public void reloadItem(Object item)

Reloads and redisplays the data for item.

See Also: reloadItemAndChildren



reloadItemAndChildren

public void reloadItemAndChildren( Object item, boolean reloadChildren)

If reloadChildren is set to false, reloads and redisplays the data for item only (identical to reloadItem). If reloadChildren is set to true, recursively reloads and redisplays the data for item and its children. It is not necessary, or efficient, to reload children if the item is not expanded.

See Also: reloadItem



rowForItem

public int rowForItem(Object anObject)

Returns the row associated with item.

See Also: itemAtRow



setAutoResizesOutlineColumn

public void setAutoresizesOutlineColumn(boolean resize)

Sets whether the receiver automatically resizes its outline column when the user expands or collapses an item. The outline column contains the cells with the expansion symbols and is generally the first column. The default is true (the outline column is automatically resized).

setAutosaveExpandedItems

public void setAutosaveExpandedItems(boolean flag)

Sets whether the expanded items in the receiver are automatically saved. 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.

The outline information is saved separately for each user and for each application that user uses.

If autosaveName returns null 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.

See Also: autosaveExpandedItems, setAutosaveTableColumns (NSTableView)



setIndentationMarkerFollowsCell

public void setIndentationMarkerFollowsCell(boolean drawInCell)

Sets whether the expansion symbol in an item should be displayed in the cell with the item or left-justified in the column. The default is true (the symbol is displayed in the cell).

See Also: indentationMarkerFollowsCell



setIndentationPerLevel

public void setIndentationPerLevel(float newIndentLevel)

Sets indentation per level, in points, to newIndentLevel.

See Also: indentationPerLevel



setOutlineTableColumn

public void setOutlineTableColumn(NSTableColumn outlineTableColumn)

Sets the table column in which hierarchical data is displayed to outlineTableColumn.

See Also: outlineTableColumn




Methods Implemented By the Delegate

Methods Implemented By the Data Source. Specifying null as the item will refer to the "root" item.


outlineViewChildOfItem

public abstract outlineViewChildOfItem( NSOutlineView outlineView, int index, Object item)

Returns the child item at the specified index. Children of a given parent item are accessed sequentially. If item is null, this method should return the appropriate child item of the root object.

See Also: outlineViewNumberOfChildrenOfItem



outlineViewIsItemExpandable

public abstract outlineViewIsItemExpandable( NSOutlineView outlineView, Object item)

This method should return true if item can be expanded to display its children.

outlineViewNumberOfChildrenOfItem

public outlineViewNumberOfChildrenOfItem( NSOutlineView outlineView, Object object)

Returns the number of child items encompassed by item. If item is null, this method should return the number of children for the top-level item.

outlineViewObjectValueForItem

public abstract Object outlineViewObjectValueForItem( NSOutlineView outlineView, NSTableColumn tableColumn, Object item)

Returns the data object associated with the specified item. The item is located in the specified tableColumn of the view.

outlineView:setObjectValue:forTableColumn:byItem:

public abstract void outlineViewSetObjectValueForItem( NSOutlineView outlineView, Object object, NSTableColumn tableColumn, Object item)

Sets the data object for the specified item. The object parameter contains the data to be set. The item is located in the specified tableColumn of the view.

Outline views support a data-source delegate in addition to the regular delegate object. The data-source delegate provides data and information about that data to the outline view. The regular delegate object handles all other delegate responsibilities for the outline view.



outlineViewColumnDidMove

public abstract void outlineViewColumnDidMove(NSNotification notification)

Invoked whenever the user moves a column in the outline view. This method is invoked as a result of posting an OutlineViewColumnDidMoveNotification.

See Also: OutlineViewColumnDidMoveNotification (notification)



outlineViewColumnDidResize

public abstract void outlineViewColumnDidResize(NSNotification notification)

Invoked whenever the user resizes a column in the outline view. This method is invoked as a result of posting an OutlineViewColumnDidResizeNotification.

See Also: OutlineViewColumnDidResizeNotification (notification)



outlineViewItemDidCollapse

public abstract void outlineViewItemDidCollapse(NSNotification notification)

Invoked whenever the user collapses an item in the outline view. This method is invoked as a result of posting an OutlineViewItemDidCollapseNotification.

See Also: OutlineViewItemDidCollapseNotification (notification)



outlineViewItemDidExpand:

public abstract void outlineViewItemDidExpand(NSNotification notification)

Invoked whenever the user expands an item in the outline view. This method is invoked as a result of posting an OutlineViewItemDidExpandNotification.

See Also: OutlineViewItemDidExpandNotification (notification)



outlineViewSelectionDidChange

public abstract void outlineViewSelectionDidChange(NSNotification notification)

Invoked immediately after the outline view's selection has changed. This method is invoked as a result of posting an OutlineViewSelectionDidChangeNotification.

See Also: OutlineViewSelectionDidChangeNotification (notification)



outlineViewSelectionIsChanging

public abstract void outlineViewSelectionIsChanging(NSNotification notification)

Invoked whenever the outline view's selection changes. This method is invoked as a result of posting an OutlineViewSelectionIsChangingNotification.

See Also: OutlineViewSelectionIsChangingNotification (notification)



outlineViewShouldCollapseItem

public abstract boolean outlineViewShouldCollapseItem( NSOutlineView outlineView, Object item)

Returns true to permit outlineView to collapse item, false to deny permission. The delegate can implement this method to disallow collapsing of specific items.

outlineViewShouldEditTableColumn

public abstract boolean outlineViewShouldEditTableColumn( NSOutlineView outlineView, NSTableColumn tableColumn, Object item)

Returns true to permit outlineView to edit the cell specified by tableColumn and item, false to deny permission. The delegate can implement this method to disallow editing of specific cells.

outlineViewShouldExpandItem

public abstract boolean outlineViewShouldExpandItem( NSOutlineView outlineView, Object item)

Returns true to permit outlineView to expand item, false to deny permission. The delegate can implement this method to disallow expanding of specific items.

outlineViewShouldSelectItem

public abstract boolean outlineViewShouldSelectItem( NSOutlineView outlineView, Object item)

Returns true to permit outlineView to select item, false to deny permission. The delegate can implement this method to disallow selection of particular items.

outlineViewShouldSelectTableColumn

public abstract boolean outlineViewShouldSelectTableColumn( NSOutlineView outlineView, NSTableColumn tableColumn)

Returns true to permit outlineView to select tableColumn, false to deny permission. The delegate can implement this method to disallow selection of specific columns.

outlineViewWillDisplayCell

public abstract void outlineViewWillDisplayCell( NSOutlineView outlineView, Object cell, NSTableColumn tableColumn, Object item)

Informs the delegate that outlineView is about to display the cell specified by tableColumn and item. The delegate can modify cell to alter its display attributes; for example, making uneditable values display in italic or gray text.

outlineViewWillDisplayOutlineCellForTableColumn

public abstract void outlineViewWillDisplayOutlineCellForTableColumn( NSOutlineView outlineView, Object cell, NSTableColumn tableColumn, Object item)

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

selectionShouldChangeInOutlineView

public abstract boolean selectionShouldChangeInOutlineView(NSOutlineView outlineView)

Returns true to permit outlineView to change its selection (typically a row being edited), false 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.


Notifications


OutlineViewColumnDidMoveNotification

Posted whenever a column is moved by user action in the NSOutlineView. This notification contains a notification object and a userInfo dictionary. The notification object is the NSOutlineView in which a column moved. The userInfo dictionary contains these keys and values:
Key Value
OldColumn The column's original index (a Number)
NewColumn The column's present index (a Number)

See Also: moveColumnToColumn (NSTableView)

OutlineViewColumnDidResizeNotification

Posted whenever a column is resized in the NSOutlineView.This notification contains a notification object and a userInfo dictionary. The notification object is the NSOutlineView in which a column was resized. The userInfo dictionary contains these keys and values:
Key Value
OldWidth The column's original width (a Number)

OutlineViewItemDidCollapseNotification

Posted whenever an item is collapsed. This notification contains a notification object and a userInfo dictionary. The notification object is the NSOutlineView in which an item was collapsed. The userInfo dictionary contains these keys and values:
Key Value
Object The item that was collapsed

OutlineViewItemDidExpandNotification

Posted whenever an item is expanded. This notification contains a notification object and a userInfo dictionary. The notification object is the NSOutlineView in which an item was expanded. The userInfo dictionary contains these keys and values:
Key Value
Object The item that was expanded

OutlineViewSelectionDidChangeNotification

Posted after the NSOutlineView's selection changes.This notification contains a notification object but no userInfo dictionary. The notification object is the NSOutlineView whose selection changed.

OutlineViewSelectionIsChangingNotification

Posted as the NSOutlineView's selection changes (while the mouse is still down). This notification contains a notification object but no userInfo dictionary. The notification object is the NSOutlineView whose selection is changing.

Table of Contents