---

NSArrayController Class Reference

Overview

NSArrayController is a bindings compatible class that manages a collection of objects. Typically the collection is an array, however, if the controller manages a relationship of a managed object (see NSManagedObject) the collection may be a set. NSArrayController provides selection management and sorting capabilities.

Tasks

Managing Sort Descriptors

• – setSortDescriptors:
• – sortDescriptors

Arranging Objects

• – arrangeObjects:
• – arrangedObjects
• – rearrangeObjects

Managing Content

• – add:
• – setAutomaticallyPreparesContent:
• – automaticallyPreparesContent

Selection Attributes

• – setAvoidsEmptySelection:
• – avoidsEmptySelection
• – setClearsFilterPredicateOnInsertion:
• – preservesSelection
• – setPreservesSelection:
• – alwaysUsesMultipleValuesMarker
• – setAlwaysUsesMultipleValuesMarker:

Managing Selections

• – selectionIndex
• – setSelectionIndex:
• – setSelectsInsertedObjects:
• – selectsInsertedObjects
• – setSelectionIndexes:
• – selectionIndexes
• – addSelectionIndexes:
• – removeSelectionIndexes:
• – setSelectedObjects:
• – selectedObjects
• – addSelectedObjects:
• – removeSelectedObjects:
• – selectNext:
• – canSelectNext
• – selectPrevious:
• – canSelectPrevious

Inserting

• – canInsert
• – insert:

Adding and Removing Objects

• – addObject:
• – addObjects:
• – insertObject:atArrangedObjectIndex:
• – insertObjects:atArrangedObjectIndexes:
• – removeObjectAtArrangedObjectIndex:
• – removeObjectsAtArrangedObjectIndexes:
• – remove:
• – removeObject:
• – removeObjects:

Filtering Content

• – clearsFilterPredicateOnInsertion
• – filterPredicate
• – setFilterPredicate:

Automatic Content Rearranging

• – setAutomaticallyRearrangesObjects:
• – automaticallyRearrangesObjects
• – automaticRearrangementKeyPaths
• – didChangeArrangementCriteria

Instance Methods

add:

Creates and adds a new object to the receiver’s content and arranged objects.

- (void)add:(id)sender

Parameters

sender

Typically the object that invoked this method.

Special Considerations

Beginning with Mac 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 Mac OS X v10.4 and later.

Declared In

NSArrayController.h

addObject:

Adds object to the receiver’s content collection and the arranged objects array.

- (void)addObject:(id)object

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – addObjects:
• – insertObject:atArrangedObjectIndex:
• – removeObject:

Related Sample Code

• Aperture Edit Plugin - Borders & Titles

Declared In

NSArrayController.h

addObjects:

Adds objects to the receiver’s content collection.

- (void)addObjects:(NSArray *)objects

Discussion

If selectsInsertedObjects returns YES (the default), the added objects are selected in the array controller.

It is important to note that inserting many objects with selectsInsertedObjects on can cause a significant performance penalty. In this case it is more efficient to use the setContent: method to set the array, or to set selectsInsertedObjects to NO before adding the objects with addObjects:.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – addObject:
• – insertObjects:atArrangedObjectIndexes:
• – removeObjects:

Declared In

NSArrayController.h

addSelectedObjects:

Adds objects from the receiver’s content array to the current selection, returning YES if the selection was changed.

- (BOOL)addSelectedObjects:(NSArray *)objects

Discussion

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

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – removeSelectedObjects:
• – setSelectedObjects:

Declared In

NSArrayController.h

addSelectionIndexes:

Adds the objects at the specified indexes in the receiver’s content array to the current selection, returning YES if the selection was changed.

- (BOOL)addSelectionIndexes:(NSIndexSet *)indexes

Discussion

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

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – removeSelectionIndexes:

Declared In

NSArrayController.h

alwaysUsesMultipleValuesMarker

Returns a Boolean value that indicates whether the receiver always returns the multiple values marker when multiple objects are selected.

- (BOOL)alwaysUsesMultipleValuesMarker

Return Value

YES if the receiver always returns the multiple values marker when multiple objects are selected—even if the selected items have the same value, otherwise NO.

Discussion

The default is NO.

This property is observable using key-value observing.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setAlwaysUsesMultipleValuesMarker:

Declared In

NSArrayController.h

arrangedObjects

Returns an array containing the receiver’s content objects arranged using arrangeObjects:.

- (id)arrangedObjects

Return Value

An array containing the receiver’s content objects arranged using arrangeObjects:.

Discussion

This property is observable using key-value observing.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – arrangeObjects:

Declared In

NSArrayController.h

arrangeObjects:

Returns a given array, appropriately sorted and filtered.

- (NSArray *)arrangeObjects:(NSArray *)objects

Return Value

An array containing objects filtered using the receiver's filter predicate (see filterPredicate) and sorted according to the receiver’s sortDescriptors.

Discussion

Subclasses should override this method to use a different sort mechanism, provide custom object arrangement, or (typically only prior to Mac OS X version 10.4, which provides a filter predicate) filter the objects.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – arrangedObjects
• – rearrangeObjects
• – sortDescriptors

Declared In

NSArrayController.h

automaticallyPreparesContent

Returns a Boolean value that indicates whether the receiver automatically prepares its content when it is loaded from a nib.

- (BOOL)automaticallyPreparesContent

Return Value

YES if the receiver automatically prepares its content when loaded from a nib, otherwise NO.

Discussion

See setAutomaticallyPreparesContent: for a full explanation of "automatically prepares content."

The default is YES.

See Also

• – setAutomaticallyPreparesContent:
• – prepareContent

automaticallyRearrangesObjects

Returns a Boolean that indicates if the receiver automatically rearranges its content to correspond to the current sort descriptors and filter predicates.

- (BOOL)automaticallyRearrangesObjects

Return Value

YES if the receiver automatically rearranges objects upon changes to the content, NO if the content does not automatically rearrange.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

NSArrayController.h

automaticRearrangementKeyPaths

Returns an array of key paths that trigger automatic content sorting or filtering.

- (NSArray *)automaticRearrangementKeyPaths

Return Value

An array of key paths that trigger automatic content sorting or filtering.

Discussion

Subclasses can override this method to customize the default behavior of the sort descriptors and filtering predicates, for example, if additional arrangement criteria are used in custom implementations of rearrangeObjects.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

NSArrayController.h

avoidsEmptySelection

Returns a Boolean value that indicates whether if the receiver requires that the content array attempt to maintain a selection.

- (BOOL)avoidsEmptySelection

Return Value

YES if the receiver requires that the content array attempt to maintain a selection at all times, otherwise NO.

Discussion

The default is YES.

This property is observable using key-value observing.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setAvoidsEmptySelection:

Declared In

NSArrayController.h

canInsert

Returns a Boolean value that indicates whether an object can be inserted into the receiver’s content collection.

- (BOOL)canInsert

Return Value

YES if an object can be inserted into the receiver’s content collection, otherwise NO.

Discussion

The result of this method can be used by a binding to enable user interface items.

This property is observable using key-value observing.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – insert:

Declared In

NSArrayController.h

canSelectNext

Returns YES if the next object, relative to the current selection, in the receiver’s content array can be selected.

- (BOOL)canSelectNext

Discussion

The result of this method can be used by a binding to enable user interface items.

This property is observable using key-value observing.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – selectNext:
• – canSelectPrevious

Declared In

NSArrayController.h

canSelectPrevious

Returns YES if the previous object, relative to the current selection, in the receiver’s content array can be selected.

- (BOOL)canSelectPrevious

Discussion

The result of this method can be used by a binding to enable user interface items.

This property is observable using key-value observing.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – canSelectNext
• – selectPrevious:

Declared In

NSArrayController.h

clearsFilterPredicateOnInsertion

Returns a Boolean value that indicates whether the receiver automatically clears an existing filter predicate when new items are inserted or added to the content.

- (BOOL)clearsFilterPredicateOnInsertion

Return Value

YES if the receiver automatically clears an existing filter predicate when new items are inserted or added to the content, otherwise NO.

Discussion

The default is YES.

This property is observable using key-value observing.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setClearsFilterPredicateOnInsertion:

Declared In

NSArrayController.h

didChangeArrangementCriteria

Invoked to inform the controller that the arrangement criteria has changed..

- (void)didChangeArrangementCriteria

Discussion

This is invoked automatically when sort descriptors and filter predicates are changed.

Subclasses should invoke this method when the array returned by automaticallyRearrangesObjects is changed.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

NSArrayController.h

filterPredicate

Returns the predicate used by the receiver to filter the array controller contents.

- (NSPredicate *)filterPredicate

Return Value

The predicate used by the receiver to filter the array controller contents. Returns nil if no filter predicate is set.

Discussion

This property is observable using key-value observing.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – setClearsFilterPredicateOnInsertion:

Declared In

NSArrayController.h

insert:

Creates a new object and inserts it into the receiver’s content array.

- (void)insert:(id)sender

Parameters

sender

Typically the object that invoked this method.

Special Considerations

Beginning with Mac 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.

Discussion

If an entity name is specified (see entityName), this method creates an instance of the of the class specified by the entity, otherwise this method creates an instance of the class specified by objectClass.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – canInsert

Declared In

NSArrayController.h

insertObject:atArrangedObjectIndex:

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

- (void)insertObject:(id)object atArrangedObjectIndex:(NSUInteger)index

Discussion

Subclasses can override this method to provide customized arranged objects support.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – insertObjects:atArrangedObjectIndexes:
• – addObject:
• – removeObjectAtArrangedObjectIndex:

Declared In

NSArrayController.h

insertObjects:atArrangedObjectIndexes:

Inserts objects into the receiver’s arranged objects array at the locations specified in indexes, and adds it to the receiver’s content collection.

- (void)insertObjects:(NSArray *)objects atArrangedObjectIndexes:(NSIndexSet *)indexes

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – insertObject:atArrangedObjectIndex:
• – addObjects:
• – removeObjectsAtArrangedObjectIndexes:

Declared In

NSArrayController.h

preservesSelection

Returns a Boolean value that indicates whether the receiver will attempt to preserve the current selection then when the content changes.

- (BOOL)preservesSelection

Return Value

YES if the receiver attempts to preserve the current selection then when the content changes, otherwise NO.

Discussion

The default is YES.

This property is observable using key-value observing.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setClearsFilterPredicateOnInsertion:

Declared In

NSArrayController.h

rearrangeObjects

Triggers filtering of the receiver’s content.

- (void)rearrangeObjects

Discussion

This method invokes arrangeObjects:.

When you detect that filtering criteria change (such as when listening to the text sent by an NSSearchField instance), invoke this method on self.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – arrangeObjects:

Related Sample Code

• iSpend

Declared In

NSArrayController.h

remove:

Removes the receiver’s selected objects from the content collection.

- (void)remove:(id)sender

Parameters

sender

Typically the object that invoked this method.

Special Considerations

Beginning with Mac 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.

Discussion

See removeObject: for a discussion of the semantics of removing objects when using Core Data.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – removeObjects:
• – removeObjectAtArrangedObjectIndex:
• – addObject:

Related Sample Code

• Aperture Edit Plugin - Borders & Titles

Declared In

NSArrayController.h

removeObject:

Removes object from the receiver’s content collection.

- (void)removeObject:(id)object

Discussion

If you are using Core Data, the exact semantics of this method differ depending on the settings for the array controller. If the receiver’s content is fetched automatically, removed objects are marked for deletion by the managed object context (and hence removal from the object graph). If, however, the receiver’s contentSet is bound to a relationship, removeObject: by default only removes the object from the relationship (not from the object graph). You can, though, set the “Deletes Object on Remove” option for the contentSet binding, in which case objects are marked for deletion as well as being removed from the relationship.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – removeObjects:
• – removeObjectAtArrangedObjectIndex:
• – addObject:

Declared In

NSArrayController.h

removeObjectAtArrangedObjectIndex:

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

- (void)removeObjectAtArrangedObjectIndex:(NSUInteger)index

Discussion

See removeObject: for a discussion of the semantics of removing objects when using Core Data.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – removeObjectsAtArrangedObjectIndexes:
• – insertObject:atArrangedObjectIndex:
• – removeObject:

Declared In

NSArrayController.h

removeObjects:

Removes objects from the receiver’s content collection.

- (void)removeObjects:(NSArray *)objects

Discussion

See removeObject: for a discussion of the semantics of removing objects when using Core Data.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – removeObject:
• – removeObjectsAtArrangedObjectIndexes:
• – addObjects:

Declared In

NSArrayController.h

removeObjectsAtArrangedObjectIndexes:

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

- (void)removeObjectsAtArrangedObjectIndexes:(NSIndexSet *)indexes

Discussion

See removeObject: for a discussion of the semantics of removing objects when using Core Data.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – removeObjectAtArrangedObjectIndex:
• – insertObjects:atArrangedObjectIndexes:
• – removeObjects:

Declared In

NSArrayController.h

removeSelectedObjects:

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

- (BOOL)removeSelectedObjects:(NSArray *)objects

Discussion

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

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – addSelectedObjects:

Declared In

NSArrayController.h

removeSelectionIndexes:

Removes the object as the specified indexes from the receiver’s current selection, returning YES if the selection was changed.

- (BOOL)removeSelectionIndexes:(NSIndexSet *)indexes

Discussion

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

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – addSelectionIndexes:

Declared In

NSArrayController.h

selectedObjects

Returns an array containing the receiver’s selected objects.

- (NSArray *)selectedObjects

Discussion

This property is observable using key-value observing.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setSelectedObjects:

Related Sample Code

• CoreRecipes

Declared In

NSArrayController.h

selectionIndex

Returns the index of the first object in the receiver’s selection.

- (NSUInteger)selectionIndex

Return Value

The index of the first object in the receiver’s selection, or NSNotFound if there is no selection.

Discussion

This property is observable using key-value observing.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setSelectionIndex:
• – selectionIndexes

Related Sample Code

• SBSystemPrefs

Declared In

NSArrayController.h

selectionIndexes

Returns an index set containing the indexes of the receiver’s currently selected objects in the content array.

- (NSIndexSet *)selectionIndexes

Return Value

An index set containing the indexes of the receiver’s currently selected objects in the content array.

Discussion

This property is observable using key-value observing.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setSelectionIndexes:
• – selectionIndex

Declared In

NSArrayController.h

selectNext:

Selects the next object, relative to the current selection, in the receiver’s arranged content.

- (void)selectNext:(id)sender

Discussion

The sender is typically the object that invoked this method.

Special Considerations

Beginning with Mac 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 Mac OS X v10.3 and later.

See Also

• – selectPrevious:
• – canSelectNext

Declared In

NSArrayController.h

selectPrevious:

Selects the previous object, relative to the current selection, in the receiver’s arranged content.

- (void)selectPrevious:(id)sender

Discussion

The sender is typically the object that invoked this method.

Special Considerations

Beginning with Mac 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 Mac OS X v10.3 and later.

See Also

• – selectNext:
• – canSelectPrevious

Declared In

NSArrayController.h

selectsInsertedObjects

Returns whether the receiver automatically selects inserted objects.

- (BOOL)selectsInsertedObjects

Return Value

YES if the receiver automatically selects inserted objects, otherwise NO.

Discussion

The default is YES.

This property is observable using key-value observing.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setSelectsInsertedObjects:

Declared In

NSArrayController.h

setAlwaysUsesMultipleValuesMarker:

Sets whether the receiver always returns the multiple values marker when multiple objects are selected.

- (void)setAlwaysUsesMultipleValuesMarker:(BOOL)flag

Parameters

flag

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

Discussion

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

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – alwaysUsesMultipleValuesMarker

Declared In

NSArrayController.h

setAutomaticallyPreparesContent:

Sets whether the receiver automatically creates and inserts new content objects automatically.

- (void)setAutomaticallyPreparesContent:(BOOL)flag

Parameters

flag

If YES, the receiver automatically prepares its content.

Discussion

If flag is YES and the receiver is not using a managed object context, prepareContent is used to create the content object.

If flag is YES and a managed object context is set, the initial content is fetched from the managed object context using the current fetch predicate. The controller also registers as an observer of its managed object context. It then tracks insertions and deletions of its entity using the context's notifications, and updates its content array as appropriate.

Setting flag to YES is the same as checking the “Automatically Prepares Content” option in the Interface Builder controller inspector.

See Also

• – automaticallyPreparesContent
• – prepareContent

setAutomaticallyRearrangesObjects:

Sets whether or not the receiver automatically rearranges its content to correspond to the current sort descriptors and filter predicates.

- (void)setAutomaticallyRearrangesObjects:(BOOL)flag

Parameters

flag

A Boolean value that indicates whether the receiver automatically rearranges its content (YES) or not (NO).

Discussion

The default is NO.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

NSArrayController.h

setAvoidsEmptySelection:

Sets whether the receiver attempts to avoid an empty selection.

- (void)setAvoidsEmptySelection:(BOOL)flag

Parameters

flag

If YES, the receiver maintains a selection unless there are no objects in the content array.

Discussion

The default is YES.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – avoidsEmptySelection

Declared In

NSArrayController.h

setClearsFilterPredicateOnInsertion:

Sets whether the receiver automatically clears an existing filter predicate when a new object is inserted or added to the content array.

- (void)setClearsFilterPredicateOnInsertion:(BOOL)flag

Parameters

flag

If YES, the receiver automatically clears an existing filter predicate when a new object is inserted or added to the content array.

Discussion

The default is YES.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – clearsFilterPredicateOnInsertion

Declared In

NSArrayController.h

setFilterPredicate:

Sets the predicate used to filter the contents of the receiver.

- (void)setFilterPredicate:(NSPredicate *)filterPredicate

Parameters

filterPredicate

The predicate used to filter the contents of the receiver.

Discussion

If filterPredicate is nil, any existing filter predicate is removed.

Availability

• Available in Mac OS X v10.4 and later.

See Also

• – filterPredicate

Declared In

NSArrayController.h

setPreservesSelection:

Sets whether the receiver attempts to preserve selection when the content changes.

- (void)setPreservesSelection:(BOOL)flag

Parameters

flag

If YES, the receiver attempts to preserve selection when the content changes.

Discussion

The default is YES.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – preservesSelection

Declared In

NSArrayController.h

setSelectedObjects:

Sets objects as the receiver’s current selection, returning YES if the selection was changed.

- (BOOL)setSelectedObjects:(NSArray *)objects

Discussion

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

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – selectedObjects
• – addSelectedObjects:

Declared In

NSArrayController.h

setSelectionIndex:

Sets the receiver’s selection to the given index, and returns a Boolean value that indicates whether the selection was changed.

- (BOOL)setSelectionIndex:(NSUInteger)index

Parameters

index

The index for the selection.

Return Value

YES if the selection was changed, otherwise NO.

Discussion

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

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – selectionIndex
• – setSelectionIndexes:

Declared In

NSArrayController.h

setSelectionIndexes:

Sets the receiver’s selection indexes and returns a Boolean value that indicates whether the selection changed.

- (BOOL)setSelectionIndexes:(NSIndexSet *)indexes

Parameters

indexes

The set of selection indexes for the receiver.

Return Value

YES if the selection was changed, otherwise NO.

Discussion

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

To select all the receiver’s objects, indexes should be an index set with indexes [0...count -1]. To deselect all indexes, pass an empty index set.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – selectionIndexes
• – setSelectionIndex:

Declared In

NSArrayController.h

setSelectsInsertedObjects:

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

- (void)setSelectsInsertedObjects:(BOOL)flag

Parameters

flag

If YES then items will be selected upon insertion.

Discussion

The default is YES.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – selectsInsertedObjects

Declared In

NSArrayController.h

setSortDescriptors:

Sets the sort descriptors for the receiver.

- (void)setSortDescriptors:(NSArray *)sortDescriptors

Parameters

sortDescriptors

An array of NSSortDescriptor objects, used by the receiver to arrange its content.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – sortDescriptors
• – arrangeObjects:

Declared In

NSArrayController.h

sortDescriptors

Returns the receiver's array of sort descriptors.

- (NSArray *)sortDescriptors

Return Value

The array of NSSortDescriptor objects used by the receiver to arrange its content.

Discussion

This property is observable using key-value observing.

Availability

• Available in Mac OS X v10.3 and later.

See Also

• – setSortDescriptors:
• – arrangeObjects:

Declared In

NSArrayController.h

---