Mac Developer Library

Developer

AppKit Framework Reference NSOutlineView Class Reference

Options
Deployment Target:

On This Page
Language:

NSOutlineView

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

Import Statement


import AppKit @import AppKit;

Availability


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

    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

    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

    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

    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

    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

    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 invoking the outlineViewSelectionDidChange: delegate method.

    Import Statement

    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

    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

    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

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    – itemAtRow:

  • Sets the table column in which hierarchical data is displayed.

    Declaration

    Swift

    unowned(unsafe) var outlineTableColumn: NSTableColumn?

    Objective-C

    @property(assign) NSTableColumn *outlineTableColumn

    Parameters

    outlineTableColumn

    The table column in which hierarchical data is displayed.

    Special Considerations

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

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the table column in which hierarchical data is displayed.

    Declaration

    Swift

    unowned(unsafe) var outlineTableColumn: NSTableColumn?

    Objective-C

    @property(assign) NSTableColumn *outlineTableColumn

    Return Value

    The table column in which hierarchical data is displayed. A nil outline table column is silently ignored.

    Discussion

    Each level of hierarchical data is indented by the amount specified by indentationPerLevel (the default is 16.0), and decorated with the indentation marker (disclosure triangle) on rows that are expandable.

    Special Considerations

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

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var autoresizesOutlineColumn: Bool

    Objective-C

    @property BOOL autoresizesOutlineColumn

    Return Value

    YEStrue if the outline column is automatically resized, otherwise NOfalse.

    Discussion

    The outline column contains the cells with the expansion symbols and is generally the first column. The default is YEStrue.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var autoresizesOutlineColumn: Bool

    Objective-C

    @property BOOL autoresizesOutlineColumn

    Parameters

    resize

    YEStrue if the outline column is automatically resized, otherwise NOfalse.

    Discussion

    The outline column contains the cells with the expansion symbols and is generally the first column. The default is YEStrue.

    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

    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

    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

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the per-level indentation.

    Declaration

    Swift

    var indentationPerLevel: CGFloat

    Objective-C

    @property CGFloat indentationPerLevel

    Parameters

    newIndentLevel

    The indentation per level, in points.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the current indentation per level.

    Declaration

    Swift

    var indentationPerLevel: CGFloat

    Objective-C

    @property CGFloat indentationPerLevel

    Return Value

    The current indentation per level, in points.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var indentationMarkerFollowsCell: Bool

    Objective-C

    @property BOOL indentationMarkerFollowsCell

    Discussion

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

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    var indentationMarkerFollowsCell: Bool

    Objective-C

    @property BOOL indentationMarkerFollowsCell

    Return Value

    YEStrue if the indentation marker is indented along with the cell contents, otherwise NOfalse.

    Discussion

    The default is YEStrue.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns a Boolean value that indicates whether the expanded items in the receiver are automatically saved across launches of the app containing the outline view.

    Declaration

    Swift

    var autosaveExpandedItems: Bool

    Objective-C

    @property BOOL autosaveExpandedItems

    Return Value

    YEStrue if when an item is expanded, the outline view displays the previous expanded state of its contained items, otherwise NOfalse.

    Discussion

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

    Special Considerations

    Starting in OS X version 10.5, the value for autosaveExpandedItems is saved out in the nib file. The default value is NOfalse.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets whether the expanded items in the receiver are automatically saved across launches of the app containing the outline view.

    Declaration

    Swift

    var autosaveExpandedItems: Bool

    Objective-C

    @property BOOL autosaveExpandedItems

    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. YEStrue indicates that when an item is expanded, the outline view displays the previous expanded state of its contained items.

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

    If autosaveName returns nil or if you haven’t implemented the data source methods outlineView:itemForPersistentObject: and outlineView:persistentObjectForItem:, this setting is ignored, and expanded item information isn’t saved.

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

    Special Considerations

    Starting in OS X version 10.5, the value for autosaveExpandedItems is saved out in the nib file. The default value is NOfalse.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • 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

    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 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). The return value of outlineView:acceptDrop:item:childIndex: determines the incoming value of the deposited parameter.

    Import Statement

    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

    import AppKit

    Availability

    Available in OS X v10.5 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 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.

    Import Statement

    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

    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

    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.

    Import Statement

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

    Declaration

    Swift

    let NSOutlineViewDisclosureButtonKey: NSString! let NSOutlineViewShowHideButtonKey: NSString!

    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.

    Import Statement

  • 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

    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

    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

    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

    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

    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

    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

    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

    import AppKit

    Availability

    Available in OS X v10.0 and later.