Mac Developer Library

Developer

AppKit Framework Reference NSOutlineView Class Reference

Options
Deployment Target:

On This Page
Language:

NSOutlineView

Conforms To


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.0 and later.

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 Delegates and Data Sources). See 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 and the item must maintain isEqual: sameness.

  • The view gets data from a data source (see NSOutlineViewDataSource Protocol).

  • The view retrieves only the data that needs to be displayed.

Subclassing

Subclassing NSOutlineView is not recommended. Customization can be accomplished in your data source class implementation (conforming to NSOutlineViewDataSource Protocol) or your delegate class implementation (conforming to NSOutlineViewDelegate Protocol).

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

    Declaration

    Swift

    func isExpandable(_ item: AnyObject?) -> Bool

    Objective-C

    - (BOOL)isExpandable:(id)item

    Parameters

    item

    An item in the receiver.

    Return Value

    YEStrue if item is expandable—that is, item can contain other items, otherwise NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func isItemExpanded(_ item: AnyObject?) -> Bool

    Objective-C

    - (BOOL)isItemExpanded:(id)item

    Parameters

    item

    An item in the receiver.

    Return Value

    YEStrue if item is expanded, otherwise NOfalse.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Expands a given item.

    Declaration

    Swift

    func expandItem(_ item: AnyObject?)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Expands a specified item and, optionally, its children.

    Declaration

    Swift

    func expandItem(_ item: AnyObject?, expandChildren expandChildren: Bool)

    Objective-C

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

    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 YEStrue, recursively expands item and its children. If NOfalse, expands item only (identical to expandItem:).

    Discussion

    For example, this method is invoked with the expandChildren parameter set to YEStrue 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Collapses a given item.

    Declaration

    Swift

    func collapseItem(_ item: AnyObject?)

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – expandItem:

  • Collapses a given item and, optionally, its children.

    Declaration

    Swift

    func collapseItem(_ item: AnyObject?, collapseChildren collapseChildren: Bool)

    Objective-C

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

    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 YEStrue, recursively collapses item and its children. If NOfalse, collapses item only (identical to collapseItem:).

    Discussion

    For example, this method is invoked with the collapseChildren parameter set to YEStrue 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Reloads and redisplays the data for the given item.

    Declaration

    Swift

    func reloadItem(_ item: AnyObject?)

    Objective-C

    - (void)reloadItem:(id)item

    Parameters

    item

    The item to reload and display.

    Discussion

    This method may cause the outline view to change its selection without calling the outlineViewSelectionDidChange: delegate method.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Reloads a given item and, optionally, its children.

    Declaration

    Swift

    func reloadItem(_ item: AnyObject?, reloadChildren reloadChildren: Bool)

    Objective-C

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

    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 YEStrue, recursively reloads item and its children. If NOfalse, reloads item only (identical to reloadItem:).

    It is not necessary, or efficient, to reload children if the item is not expanded.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – reloadItem:

  • Returns the item associated with a given row.

    Declaration

    Swift

    func itemAtRow(_ row: Int) -> AnyObject?

    Objective-C

    - (id)itemAtRow:(NSInteger)row

    Parameters

    row

    The index of a row in the receiver.

    Return Value

    The item associated with row.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – rowForItem:

  • Returns the row associated with a given item.

    Declaration

    Swift

    func rowForItem(_ item: AnyObject?) -> Int

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – itemAtRow:

  • The table column in which hierarchical data is displayed.

    Declaration

    Swift

    unowned(unsafe) var outlineTableColumn: NSTableColumn?

    Objective-C

    @property(assign) NSTableColumn *outlineTableColumn

    Discussion

    Each level of hierarchical data is indented by the amount specified by the indentationPerLevel property (the default is 16.0), and decorated with the indentation marker (disclosure triangle) on rows that are expandable. Outline table column data is archived with the rest of the outline view’s state information.

    Attempts to set the value of this property to nil are silently ignored.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • A Boolean value that indicates whether the outline view resizes its outline column when the user expands or collapses items.

    Declaration

    Swift

    var autoresizesOutlineColumn: Bool

    Objective-C

    @property BOOL autoresizesOutlineColumn

    Discussion

    The outline column contains the cells with the expansion symbols and is generally the first column. The default value of this property is YEStrue, which causes the outline column to be resized.

    The outline column is resized based on how many indentation levels are exposed or hidden. For example, if expanding a row exposes a single indentation level, the outline column width is increased by one indentationPerLevel.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the indentation level for a given item.

    Declaration

    Swift

    func levelForItem(_ item: AnyObject?) -> Int

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the indentation level for a given row.

    Declaration

    Swift

    func levelForRow(_ row: Int) -> Int

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • The per-level indentation, measured in points.

    Declaration

    Swift

    var indentationPerLevel: CGFloat

    Objective-C

    @property CGFloat indentationPerLevel

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • A Boolean value indicating whether the indentation marker symbol displayed in the outline column should be indented along with the cell contents.

    Declaration

    Swift

    var indentationMarkerFollowsCell: Bool

    Objective-C

    @property BOOL indentationMarkerFollowsCell

    Discussion

    When the value of this property is YEStrue, the indentation marker is indented along with the cell contents. When the value is NOfalse, the marker is always displayed left-justified in the column. The default value of this property is YEStrue.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • A Boolean value indicating whether the expanded items are automatically saved across launches of the app.

    Declaration

    Swift

    var autosaveExpandedItems: Bool

    Objective-C

    @property BOOL autosaveExpandedItems

    Discussion

    When the value of this property is YEStrue, the outline view saves the state of its expanded items and restores that state the next time the user launches the app. (If the outline view’s autosaveName property is nil, or if you have not implemented the outlineView:itemForPersistentObject: and outlineView:persistentObjectForItem: delegate methods, this setting is ignored and outline information is not saved.) The configuration data is saved separately for each user and for each app. The default value of this property is NOfalse.

    You can have separate settings for the autosaveExpandedItems and autosaveTableColumns properties, so you could, for example, save expanded item information, but not table column positions.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    autosaveName (NSTableView)
    autosaveTableColumns (NSTableView)

  • Used to “retarget” a proposed drop.

    Declaration

    Swift

    func setDropItem(_ item: AnyObject?, dropChildIndex index: Int)

    Objective-C

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

    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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value that indicates whether auto-expanded items should return to their original collapsed state.

    Declaration

    Swift

    func shouldCollapseAutoExpandedItemsForDeposited(_ deposited: Bool) -> Bool

    Objective-C

    - (BOOL)shouldCollapseAutoExpandedItemsForDeposited:(BOOL)deposited

    Parameters

    deposited

    If YEStrue, the drop terminated successfully; if NOfalse the drop failed.

    Return Value

    YEStrue if auto-expanded items should return to their original collapsed state; otherwise NOfalse.

    Discussion

    Override this method to provide custom behavior. If the target of a drop is not auto-expanded (by hovering long enough) the drop target still gets expanded after a successful drop unless this method returns YEStrue. The default implementation returns NOfalse after a successful drop.

    This method is called in a variety of situations. For example, it is called shortly after the outlineView:acceptDrop:item:childIndex: method is called and also if the drag exits the outline view (exiting the view is treated the same as a failed drop). The return value of the outlineView:acceptDrop:item:childIndex: method determines the incoming value of the deposited parameter.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the parent for a given item.

    Declaration

    Swift

    func parentForItem(_ item: AnyObject?) -> AnyObject?

    Objective-C

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the specified child of an item.

    Declaration

    Swift

    func child(_ index: Int, ofItem item: AnyObject?) -> AnyObject?

    Objective-C

    - (id)child:(NSInteger)index ofItem:(id)item

    Parameters

    index

    The index of the child item in the parent.

    item

    The parent item whose child item you want to retrieve.

    Return Value

    The child item or nil if the item could not be found.

    Discussion

    You can call this method on an outline view with either a static or dynamic data source. For an outline view whose contents are dynamic, this method may call out to the outlineView:child:ofItem: method of the associated data source object.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

  • Returns the number of children for the specified parent item.

    Declaration

    Swift

    func numberOfChildrenOfItem(_ item: AnyObject?) -> Int

    Objective-C

    - (NSInteger)numberOfChildrenOfItem:(id)item

    Parameters

    item

    The parent item.

    Return Value

    The number of children associated with the parent.

    Discussion

    You can call this method on an outline view with either a static or dynamic data source. For an outline view whose contents are dynamic, this method may call out to the outlineView:numberOfChildrenOfItem: method of the associated data source object.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.10 and later.

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

    Declaration

    Swift

    func frameOfOutlineCellAtRow(_ row: Int) -> NSRect

    Objective-C

    - (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 in the indentationMarkerFollowsCell property. 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.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Returns the receiver’s delegate.

    Declaration

    Swift

    func delegate() -> NSOutlineViewDelegate?

    Objective-C

    - (id<NSOutlineViewDelegate>)delegate

    Return Value

    The receiver’s delegate.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Sets the receiver’s delegate.

    Declaration

    Swift

    func setDelegate(_ anObject: NSOutlineViewDelegate?)

    Objective-C

    - (void)setDelegate:(id<NSOutlineViewDelegate>)anObject

    Parameters

    anObject

    The delegate for the receiver. The delegate must conform to the NSOutlineViewDelegate Protocol protocol.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.6 and later.

    See Also

    – delegate

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

    Declaration

    Swift

    var NSOutlineViewDropOnItemIndex: Int { get }

    Objective-C

    enum { NSOutlineViewDropOnItemIndex = -1 };

    Constants

    • NSOutlineViewDropOnItemIndex

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

  • These keys are used by the outline view to create disclosure buttons that collapse and expand items.

    Declaration

    Swift

    let NSOutlineViewDisclosureButtonKey: String let NSOutlineViewShowHideButtonKey: String

    Objective-C

    NSString *const NSOutlineViewDisclosureButtonKey; NSString *const NSOutlineViewShowHideButtonKey;

    Constants

    • NSOutlineViewDisclosureButtonKey

      NSOutlineViewDisclosureButtonKey

      The normal triangle disclosure button.

      Available in OS X v10.9 and later.

    • NSOutlineViewShowHideButtonKey

      NSOutlineViewShowHideButtonKey

      The Show/Hide button.

      Available in OS X v10.9 and later.

    Discussion

    The outline view creates these buttons by calling its inherited makeViewWithIdentifier:owner: method, passing in the key as the identifier and the delegate as the owner.

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

    Key

    Value

    @"NSOldColumn"

    An NSNumber object containing the integer value of the column’s original index

    @"NSNewColumn"

    An NSNumber object containing the integer value of the column’s present index

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Key

    Value

    @"NSTableColumn"

    The column that was resized.

    @"NSOldWidth"

    An NSNumber object containing the column’s original width

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Key

    Value

    @"NSObject"

    The item that was collapsed (an id)

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Key

    Value

    @"NSObject"

    The item that was expanded (an id)

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Key

    Value

    @"NSObject"

    The item about to be collapsed (an id)

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Key

    Value

    @"NSObject"

    The item that is to be expanded (an id)

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.0 and later.