Mac Developer Library

Developer

AppKit Framework Reference NSTreeController Class Reference

Options
Deployment Target:

On This Page
Language:

NSTreeController

The NSTreeController is a bindings compatible controller that manages a tree of objects. It provides selection and sort management. Its primary purpose is to act as the controller when binding NSOutlineView and NSBrowser instances to a hierarchical collection of objects. The root content object of the tree can be a single object, or an array of objects.

An NSTreeController object requires that you describe how the tree of objects is traversed by specifying the key-path for child objects specified by childrenKeyPath. All child objects for the tree must be key-value coding compliant for the same child key path. If necessary, you should add properties to your model classes that map the child key name to the appropriate class-specific property name.

Child objects can implement a count method (specified to the tree controller using countKeyPath) that, if provided, returns the number of child objects available. Your model objects are expected to update the value of the count key path in a key-value observing compliant method. Optionally, you can also provide a leaf key path using leafKeyPath that specifies a key in your model object that returns YEStrue if the object is a leaf node, and NOfalse if it is not. Changes to the leaf node value of the child object should be made in a key-value observing compliant manner. Providing the leaf node key path can improve performance, because it prevents the NSTreeController from having to examine the child object to determine if it is a leaf node.

Inheritance


Conforms To


Import Statement


Swift

import AppKit

Objective-C

@import AppKit;

Availability


Available in OS X v10.4 and later.
  • An array containing the sort descriptors used to arrange the tree controller’s content.

    Declaration

    Swift

    var sortDescriptors: [AnyObject]!

    Objective-C

    @property(copy) NSArray *sortDescriptors

    Discussion

    When the value of this property is nil, the tree controller has no sort descriptors configured, which means that the contents are arranged in their natural order. This property is observable using key-value observing.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • content content Property

    The tree controller’s content object.

    Declaration

    Swift

    var content: AnyObject!

    Objective-C

    @property(strong) id content

    Discussion

    The value of this property can be an array of objects, or a single root object. The default value is nil. This property is observable using key-value observing.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • The tree controller’s sorted content objects. (read-only)

    Declaration

    Swift

    var arrangedObjects: AnyObject { get }

    Objective-C

    @property(readonly, strong) id arrangedObjects

    Discussion

    The value of this property represents a proxy root tree node containing the tree controller’s sorted content objects. The proxy object responds to childNodes and descendantNodeAtIndexPath: messages. This property is observable using key-value observing.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Use this method to trigger reordering of the tree controller’s content.

    Declaration

    Swift

    func rearrangeObjects()

    Objective-C

    - (void)rearrangeObjects

    Discussion

    Subclasses should invoke this method if any parameter that affects the arranged objects changes.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

    See Also

    arrangedObjects

  • Sets the tree controller’s current selection.

    Declaration

    Swift

    func setSelectionIndexPath(_ indexPath: NSIndexPath?) -> Bool

    Objective-C

    - (BOOL)setSelectionIndexPath:(NSIndexPath *)indexPath

    Parameters

    indexPath

    The proposed new selection.

    Return Value

    Return YEStrue if the selection has changed, otherwise NOfalse.

    Discussion

    Attempting to change the selection may cause a commitEditing message which fails, thus denying the selection change.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • The index path of the first selected object. (read-only)

    Declaration

    Swift

    @NSCopying var selectionIndexPath: NSIndexPath? { get }

    Objective-C

    @property(readonly, copy) NSIndexPath *selectionIndexPath

    Discussion

    The value of this property is nil if there is no selection. This property is observable using key-value observing.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Sets the tree controller’s current selection to the specified index paths.

    Declaration

    Swift

    func setSelectionIndexPaths(_ indexPaths: [AnyObject]!) -> Bool

    Objective-C

    - (BOOL)setSelectionIndexPaths:(NSArray *)indexPaths

    Parameters

    indexPaths

    An array of NSIndexPath objects specifying the selected objects.

    Return Value

    Return YEStrue if the selection has changed, otherwise NOfalse.

    Discussion

    Attempting to change the selection may cause a commitEditing message which fails, thus denying the selection change.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • An array containing the index paths of the currently selected objects. (read-only)

    Declaration

    Swift

    var selectionIndexPaths: [AnyObject]! { get }

    Objective-C

    @property(readonly, copy) NSArray *selectionIndexPaths

    Discussion

    This property contains an array containing NSIndexPath objects for each of the selected objects in the tree controller’s content. This property is observable using key-value observing.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • An array containing the currently selected objects in the tree controller’s content. (read-only)

    Declaration

    Swift

    var selectedObjects: [AnyObject]! { get }

    Objective-C

    @property(readonly, copy) NSArray *selectedObjects

    Discussion

    This property is observable using key-value observing.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • An array containing the tree controller’s selected tree nodes. (read-only)

    Declaration

    Swift

    var selectedNodes: [AnyObject]! { get }

    Objective-C

    @property(readonly, copy) NSArray *selectedNodes

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • A Boolean value that indicates whether the tree controller automatically selects objects as they are inserted.

    Declaration

    Swift

    var selectsInsertedObjects: Bool

    Objective-C

    @property BOOL selectsInsertedObjects

    Discussion

    The default value of this property is YEStrue. This property is observable using key-value observing.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Adds the objects at the specified indexPaths in the tree controller’s content to the current selection.

    Declaration

    Swift

    func addSelectionIndexPaths(_ indexPaths: [AnyObject]) -> Bool

    Objective-C

    - (BOOL)addSelectionIndexPaths:(NSArray *)indexPaths

    Discussion

    Attempting to change the selection may cause a commitEditing message which fails, thus denying the selection change.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Removes the objects at the specified indexPaths from the tree controller’s current selection, returning YEStrue if the selection was changed.

    Declaration

    Swift

    func removeSelectionIndexPaths(_ indexPaths: [AnyObject]) -> Bool

    Objective-C

    - (BOOL)removeSelectionIndexPaths:(NSArray *)indexPaths

    Discussion

    Attempting to change the selection may cause a commitEditing message which fails, thus denying the selection change.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • A Boolean value that indicates whether the tree controller requires the content array to attempt to maintain a selection at all times, avoiding an empty selection.

    Declaration

    Swift

    var avoidsEmptySelection: Bool

    Objective-C

    @property BOOL avoidsEmptySelection

    Discussion

    When the value of this property is YEStrue, the tree controller maintains a selection unless there are no objects in the content. The default value is YEStrue. This property is observable using key-value observing.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • A Boolean value that indicates whether the tree controller will attempt to preserve the current selection when the content changes.

    Declaration

    Swift

    var preservesSelection: Bool

    Objective-C

    @property BOOL preservesSelection

    Discussion

    When the value of this property is YEStrue, the selection is preserved, if possible. The default value is YEStrue. This property is observable using key-value observing.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • A Boolean value that indicates whether the tree controller always returns the multiple values marker when multiple objects are selected, even if the selected items have the same value.

    Declaration

    Swift

    var alwaysUsesMultipleValuesMarker: Bool

    Objective-C

    @property BOOL alwaysUsesMultipleValuesMarker

    Discussion

    Setting this property to YEStrue can increase performance if your application doesn’t allow editing multiple values. The default is NOfalse. This property is observable using key-value observing.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Adds an object to the tree controller’s content after the current selection.

    Declaration

    Swift

    func add(_ sender: AnyObject?)

    Objective-C

    - (void)add:(id)sender

    Discussion

    The sender is typically the object that invoked this method.

    If the receiver is in object mode, newObject is called and the returned object is added to the collection. If the receiver is in entity mode a new object is created that is appropriate as specified by the entity, and newObject is not used. The object is added after the current selection at the same depth. If there is no selection, the object is appended to the child nodes of the tree controller’s sorted content objects, which are represented by the value of arrangedObjects.

    Special Considerations

    The result of this method is deferred until the next iteration of the run loop so that the error presentation mechanism can provide feedback as a sheet.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

    See Also

    – remove:

  • Adds a child object to the currently selected item.

    Declaration

    Swift

    func addChild(_ sender: AnyObject?)

    Objective-C

    - (void)addChild:(id)sender

    Discussion

    The sender is typically the object that invoked this method.

    If the receiver is in object mode newObject is called and the returned object is added as a child. If the receiver is in entity mode a new object is created that is appropriate for the relationship as specified by the entity, and newObject is not used.

    Special Considerations

    The result of this method is deferred until the next iteration of the run loop so that the error presentation mechanism can provide feedback as a sheet.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

    See Also

    – remove:

  • A Boolean value that indicates if a child object can be added to the tree controller’s content. (read-only)

    Declaration

    Swift

    var canAddChild: Bool { get }

    Objective-C

    @property(readonly) BOOL canAddChild

    Discussion

    The value of this property is YEStrue if a child object can be added to the tree controller’s content. This property is observable using key-value observing.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

    See Also

    canInsertChild

  • canInsert canInsert Property

    A Boolean value that indicates if an object can be inserted into the tree controller’s content. (read-only)

    Declaration

    Swift

    var canInsert: Bool { get }

    Objective-C

    @property(readonly) BOOL canInsert

    Discussion

    The value of this property is YEStrue if an object can be inserted into the tree controller’s content. This property is observable using key-value observing.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

    See Also

    canInsertChild

  • A Boolean value that indicates if a child object can be inserted into the tree controller’s content. (read-only)

    Declaration

    Swift

    var canInsertChild: Bool { get }

    Objective-C

    @property(readonly) BOOL canInsertChild

    Discussion

    The value of this property is YEStrue if a child object can be inserted into the tree controller’s content. This property is observable using key-value observing.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Creates a new object of the class specified by objectClass and inserts it into the tree controller’s content.

    Declaration

    Swift

    func insert(_ sender: AnyObject?)

    Objective-C

    - (void)insert:(id)sender

    Discussion

    The sender is typically the object that invoked this method.

    If the receiver is in object mode newObject is called and the returned object is inserted into the collection. If the receiver is in entity mode a new object is created that is appropriate as specified by the entity, and newObject is not used.

    Special Considerations

    The result of this method is deferred until the next iteration of the run loop so that the error presentation mechanism can provide feedback as a sheet.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

    See Also

    – add:

  • Creates a new object of the class specified by objectClass and inserts it into the tree controller’s content as a child of the current selection.

    Declaration

    Swift

    func insertChild(_ sender: AnyObject?)

    Objective-C

    - (void)insertChild:(id)sender

    Discussion

    The sender is typically the object that invoked this method.

    If the receiver is in object mode newObject is called and the returned object is inserted as a child. If the receiver is in entity mode a new object is created that is appropriate for the relationship as specified by the entity, and newObject is not used.

    Special Considerations

    The result of this method is deferred until the next iteration of the run loop so that the error presentation mechanism can provide feedback as a sheet.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

    See Also

    – add:

  • Inserts object into the tree controller’s arranged objects array at the location specified by indexPath, and adds it to the tree controller’s content.

    Declaration

    Swift

    func insertObject(_ object: AnyObject!, atArrangedObjectIndexPath indexPath: NSIndexPath)

    Objective-C

    - (void)insertObject:(id)object atArrangedObjectIndexPath:(NSIndexPath *)indexPath

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Inserts objects into the tree controller’s arranged objects array at the locations specified in indexPaths, and adds them to the tree controller’s content.

    Declaration

    Swift

    func insertObjects(_ objects: [AnyObject], atArrangedObjectIndexPaths indexPaths: [AnyObject])

    Objective-C

    - (void)insertObjects:(NSArray *)objects atArrangedObjectIndexPaths:(NSArray *)indexPaths

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Removes the tree controller’s selected objects from the content.

    Declaration

    Swift

    func remove(_ sender: AnyObject?)

    Objective-C

    - (void)remove:(id)sender

    Discussion

    The sender is typically the object that invoked this method.

    Special Considerations

    The result of this method is deferred until the next iteration of the run loop so that the error presentation mechanism can provide feedback as a sheet.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

    See Also

    – add:

  • Removes the object at the specified indexPath in the tree controller’s arranged objects from the tree controller’s content.

    Declaration

    Swift

    func removeObjectAtArrangedObjectIndexPath(_ indexPath: NSIndexPath)

    Objective-C

    - (void)removeObjectAtArrangedObjectIndexPath:(NSIndexPath *)indexPath

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Removes the objects at the specified indexPaths in the tree controller’s arranged objects from the tree controller’s content.

    Declaration

    Swift

    func removeObjectsAtArrangedObjectIndexPaths(_ indexPaths: [AnyObject])

    Objective-C

    - (void)removeObjectsAtArrangedObjectIndexPaths:(NSArray *)indexPaths

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Moves the specified tree node to the new index path.

    Declaration

    Swift

    func moveNode(_ node: NSTreeNode, toIndexPath indexPath: NSIndexPath)

    Objective-C

    - (void)moveNode:(NSTreeNode *)node toIndexPath:(NSIndexPath *)indexPath

    Parameters

    node

    A tree node.

    indexPath

    An index path specifying the new position in the tree controller’s content.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • Moves the specified tree nodes to the new index path.

    Declaration

    Swift

    func moveNodes(_ nodes: [AnyObject], toIndexPath startingIndexPath: NSIndexPath)

    Objective-C

    - (void)moveNodes:(NSArray *)nodes toIndexPath:(NSIndexPath *)startingIndexPath

    Parameters

    nodes

    An array of tree nodes.

    startingIndexPath

    An index path specifying the starting position to move the tree nodes to in the tree controller’s content.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • The key path used to find the children in the tree controller’s objects.

    Declaration

    Swift

    var childrenKeyPath: String!

    Objective-C

    @property(copy) NSString *childrenKeyPath

    Discussion

    The default value of this property is nil.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns the key path used to find the children in the specified tree node.

    Declaration

    Swift

    func childrenKeyPathForNode(_ node: NSTreeNode) -> String?

    Objective-C

    - (NSString *)childrenKeyPathForNode:(NSTreeNode *)node

    Parameters

    node

    A tree node in the tree controller’s content.

    Return Value

    A string containing the key path in node that provides the child nodes.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • The key path used to find the number of children for a node.

    Declaration

    Swift

    var countKeyPath: String!

    Objective-C

    @property(copy) NSString *countKeyPath

    Discussion

    Specifying this key path (if the data is available in the model object) can increase performance, but disables insert and remove functionality.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns the key path that provides the number of children for a specified node.

    Declaration

    Swift

    func countKeyPathForNode(_ node: NSTreeNode) -> String?

    Objective-C

    - (NSString *)countKeyPathForNode:(NSTreeNode *)node

    Parameters

    node

    A tree node in the tree controller’s content.

    Return Value

    A string containing the key path in node that provides the number of children.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.

  • The key path used by the tree controller to determine if a node is a leaf key.

    Declaration

    Swift

    var leafKeyPath: String?

    Objective-C

    @property(copy) NSString *leafKeyPath

    Discussion

    Specifying a key path for this property is optional. If the tree controller is able to determine that a node is a leaf node, it can disable inserting or adding children to those nodes.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns the key path that specifies whether the node is a leaf node.

    Declaration

    Swift

    func leafKeyPathForNode(_ node: NSTreeNode) -> String?

    Objective-C

    - (NSString *)leafKeyPathForNode:(NSTreeNode *)node

    Parameters

    node

    A tree node in the tree controller’s content.

    Return Value

    A string containing the key path in node that specifies that the node is a leaf node.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.5 and later.