NSTreeController Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.4 and later.
Companion guide
Declared in
NSTreeController.h
Related sample code

Overview

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 requires that you describe how the tree of objects is traversed by specifying the key-path for child objects specified by setChildrenKeyPath:. All child objects for the tree must be key-value coding compliant for the same child key-path. If necessary, you should implement accessor methods in your model classes, that map the child key name to the appropriate class-specific method name.

Child objects can implement a count method (specified to the tree controller using setCountKeyPath:) 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. You can also, optionally, provide a leaf key-path using setLeafKeyPath: that specifies a key in your model object that returns YES if the object is a leaf node, and NO 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 prevents the NSTreeController from having to determine if a child object is a leaf node by examining the child object and as a result improves performance.

Adopted Protocols

NSCoding
NSCopying

Tasks

Managing Sort Descriptors

Setting the Content

Arranging Objects

Getting the Current Selection

Managing Selections

Adding, Inserting and Removing Objects

Specifying Model Attributes

Instance Methods

add:

Adds an object to the receiver after the current selection.

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

Special Considerations

Beginning with OS X v10.4 the result of this method is deferred until the next iteration of the runloop so that the error presentation mechanism can provide feedback as a sheet.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSTreeController.h

addChild:

Adds a child object to the currently selected item.

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

Beginning with OS X v10.4 the result of this method is deferred until the next iteration of the runloop so that the error presentation mechanism can provide feedback as a sheet.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSTreeController.h

addSelectionIndexPaths:

Adds the objects at the specified indexPaths in the receiver’s content to the current selection.

- (BOOL)addSelectionIndexPaths:(NSArray *)indexPaths
Discussion

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

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

alwaysUsesMultipleValuesMarker

Returns whether the receiver always returns the multiple values marker when multiple objects are selected, even if the selected items have the same value.

- (BOOL)alwaysUsesMultipleValuesMarker
Discussion

The default is NO.

This property is observable using key-value observing.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

arrangedObjects

Returns the tree controller’s sorted content objects.

- (id)arrangedObjects
Return Value

A proxy root tree note containing the receiver’s sorted content objects. The proxy object responds to childNodes and descendantNodeAtIndexPath: messages.

Discussion

This property is observable using key-value observing.

Special Considerations

Prior to OS X v10.5 this method returned an opaque root node object representing all the currently displayed objects. That return value was only suitable for use with Cocoa bindings, and no assumption should be made about what methods that opaque object supports.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

avoidsEmptySelection

Returns whether the receiver requires that the content array attempt to maintain a selection at all times.

- (BOOL)avoidsEmptySelection
Discussion

The default is YES.

This property is observable using key-value observing.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

canAddChild

Returns YES if a child object can be added to the receiver’s content.

- (BOOL)canAddChild
Discussion

This property is observable using key-value observing.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

canInsert

Returns YES if an object can be inserted into the receiver’s content.

- (BOOL)canInsert
Discussion

This property is observable using key-value observing.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

canInsertChild

Returns YES if a child object can be inserted into the receiver’s content.

- (BOOL)canInsertChild
Discussion

This property is observable using key-value observing.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

childrenKeyPath

Returns the key path used to find the children in the receiver’s objects.

- (NSString *)childrenKeyPath
Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

childrenKeyPathForNode:

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

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

A tree node in the receiver.

Return Value

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

Availability
  • Available in OS X v10.5 and later.
Declared In
NSTreeController.h

content

Returns the receiver’s content object.

- (id)content
Return Value

The receiver’s content object.

Discussion

This property is observable using key-value observing.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

countKeyPath

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

- (NSString *)countKeyPath
Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

countKeyPathForNode:

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

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

A tree node in the receiver.

Return Value

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

Availability
  • Available in OS X v10.5 and later.
Declared In
NSTreeController.h

insert:

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

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

Beginning with OS X v10.4 the result of this method is deferred until the next iteration of the runloop so that the error presentation mechanism can provide feedback as a sheet.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSTreeController.h

insertChild:

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

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

Beginning with OS X v10.4 the result of this method is deferred until the next iteration of the runloop so that the error presentation mechanism can provide feedback as a sheet.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSTreeController.h

insertObject:atArrangedObjectIndexPath:

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

- (void)insertObject:(id)object atArrangedObjectIndexPath:(NSIndexPath *)indexPath
Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

insertObjects:atArrangedObjectIndexPaths:

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

- (void)insertObjects:(NSArray *)objects atArrangedObjectIndexPaths:(NSArray *)indexPaths
Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

leafKeyPath

Returns the key path used by the receiver to determine if a node is a leaf key.

- (NSString *)leafKeyPath
Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

leafKeyPathForNode:

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

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

A tree node in the receiver.

Return Value

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

Availability
  • Available in OS X v10.5 and later.
Declared In
NSTreeController.h

moveNode:toIndexPath:

Moves the specified tree node to the new index path.

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

A tree node.

indexPath

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

Availability
  • Available in OS X v10.5 and later.
Related Sample Code
Declared In
NSTreeController.h

moveNodes:toIndexPath:

Moves the specified tree nodes to the new index path.

- (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 receiver’s content.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSTreeController.h

preservesSelection

Returns whether the receiver will attempt to preserve the current selection when the content changes.

- (BOOL)preservesSelection
Discussion

The default is YES.

This property is observable using key-value observing.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

rearrangeObjects

Use this method to trigger reordering of the receiver’s content.

- (void)rearrangeObjects
Discussion

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

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

remove:

Removes the receiver’s selected objects from the content.

- (void)remove:(id)sender
Discussion

The sender is typically the object that invoked this method.

Special Considerations

Beginning with OS X v10.4 the result of this method is deferred until the next iteration of the runloop so that the error presentation mechanism can provide feedback as a sheet.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
NSTreeController.h

removeObjectAtArrangedObjectIndexPath:

Removes the object at the specified indexPath in the receiver’s arranged objects from the receiver’s content.

- (void)removeObjectAtArrangedObjectIndexPath:(NSIndexPath *)indexPath
Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

removeObjectsAtArrangedObjectIndexPaths:

Removes the objects at the specified indexPaths in the receiver’s arranged objects from the receiver’s content.

- (void)removeObjectsAtArrangedObjectIndexPaths:(NSArray *)indexPaths
Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

removeSelectionIndexPaths:

Removes the objects at the specified indexPaths from the receiver’s current selection, returning YES if the selection was changed.

- (BOOL)removeSelectionIndexPaths:(NSArray *)indexPaths
Discussion

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

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

selectedNodes

Returns an array of the receiver’s selected tree nodes.

- (NSArray *)selectedNodes
Return Value

An array containing the receiver’s selected tree nodes

Availability
  • Available in OS X v10.5 and later.
Declared In
NSTreeController.h

selectedObjects

Returns an array containing the currently selected objects.

- (NSArray *)selectedObjects
Return Value

An array containing the currently selected objects in the tree controller content.

Discussion

This property is observable using key-value observing.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

selectionIndexPath

Returns the index path of the first selected object.

- (NSIndexPath *)selectionIndexPath
Return Value

Returns an index path of the first object in the tree controller’s selection. Returns nil if there is no selection.

Discussion

This property is observable using key-value observing.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

selectionIndexPaths

Returns an array containing the index paths of the currently selected objects.

- (NSArray *)selectionIndexPaths
Return Value

An array containing NSIndexPath objects for each of the selected objects in the tree controller’s content.

Discussion

This property is observable using key-value observing.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

selectsInsertedObjects

Returns whether the receiver selects inserted objects automatically.

- (BOOL)selectsInsertedObjects
Discussion

The default is YES.

This property is observable using key-value observing.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

setAlwaysUsesMultipleValuesMarker:

Sets whether the receiver always returns the multiple values marker when multiple objects are selected, even if they have the same value.

- (void)setAlwaysUsesMultipleValuesMarker:(BOOL)flag
Discussion

Setting flag to YES can increase performance if your application doesn’t allow editing multiple values. The default is NO.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

setAvoidsEmptySelection:

Sets whether the receiver will attempt to avoid an empty selection.

- (void)setAvoidsEmptySelection:(BOOL)flag
Discussion

If flag is YES then the receiver will maintain a selection unless there are no objects in the content. The default is YES.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

setChildrenKeyPath:

Sets the key path used by the receiver to access child objects to key.

- (void)setChildrenKeyPath:(NSString *)key
Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

setContent:

Sets the receiver’s content.

- (void)setContent:(id)content
Parameters
content

The content. The content can be an array of objects, or a single root object.

Availability
  • Available in OS X v10.4 and later.
See Also
Related Sample Code
Declared In
NSTreeController.h

setCountKeyPath:

Sets the key path used by the receiver to determine the number of objects at a node to key.

- (void)setCountKeyPath:(NSString *)key
Discussion

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

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

setLeafKeyPath:

Sets the key path used by the receiver to determine if an object is a leaf node to key.

- (void)setLeafKeyPath:(NSString *)key
Discussion

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

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

setPreservesSelection:

Sets whether the receiver will attempt to preserve selection when the content changes.

- (void)setPreservesSelection:(BOOL)flag
Discussion

If flag is YES then the selection will be preserved, if possible. The default is YES.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

setSelectionIndexPath:

Sets the receiver’s current selection.

- (BOOL)setSelectionIndexPath:(NSIndexPath *)indexPath
Parameters
indexPath

The proposed new selection.

Return Value

Return YES if the selection has changed, otherwise NO.

Discussion

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

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

setSelectionIndexPaths:

Sets the receiver’s current selection to the specified index paths.

- (BOOL)setSelectionIndexPaths:(NSArray *)indexPaths
Parameters
indexPaths

An array of NSIndexpath objects specifying the selected objects.

Return Value

Return YES if the selection has changed, otherwise NO.

Discussion

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

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

setSelectsInsertedObjects:

Sets whether the receiver will automatically select objects as they are inserted.

- (void)setSelectsInsertedObjects:(BOOL)flag
Discussion

If flag is YES then items will be selected upon insertion. The default is YES.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

setSortDescriptors:

Sets the sort descriptors used to arrange the receiver's contents.

- (void)setSortDescriptors:(NSArray *)sortDescriptors
Parameters
sortDescriptors

An array of NSSortDescriptor objects. Passing nil causes the contents to be arranged in their natural order.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h

sortDescriptors

Returns an array containing the sort descriptors used to arrange the receiver's content.

- (NSArray *)sortDescriptors
Return Value

Returns an array containing the tree controller’s sort descriptors. Returns nil if the receiver has no sort descriptors configured.

Discussion

This property is observable using key-value observing.

Availability
  • Available in OS X v10.4 and later.
Declared In
NSTreeController.h