NSArrayController Class Reference

Inherits from
NSObjectController : NSController : NSObject
Conforms to
NSCoding (NSController)
NSObject (NSObject)
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.3 and later.
Declared in
NSArrayController.h
Companion guides
Cocoa Bindings Programming Topics
Predicate Programming Guide
Core Data Programming Guide
Related sample code

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

Arranging Objects

Managing Content

Selection Attributes

Managing Selections

Inserting

Adding and Removing Objects

Filtering Content

Automatic Content Rearranging

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 OS X v10.4 the result of this method is deferred until the next iteration of the runloop so that the error presentation mechanism (see Error Responders and Error Recovery) can provide feedback as a sheet.

Availability
  • Available in 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 OS X v10.3 and later.
See Also
Related Sample Code
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 OS X v10.3 and later.
See Also
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 OS X v10.3 and later.
See Also
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 OS X v10.3 and later.
See Also
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 OS X v10.4 and later.
See Also
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 OS X v10.3 and later.
See Also
Related Sample Code
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 OS X version 10.4, which provides a filter predicate) filter the objects.

Availability
  • Available in OS X v10.3 and later.
See Also
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

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 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 a custom implementation of rearrangeObjects.

Availability
  • Available in OS X v10.5 and later.
See Also
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 OS X v10.3 and later.
See Also
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 OS X v10.3 and later.
See Also
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 OS X v10.3 and later.
See Also
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 OS X v10.3 and later.
See Also
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 OS X v10.4 and later.
See Also
Declared In
NSArrayController.h

didChangeArrangementCriteria

Invoked when any criteria for arranging objects change.

- (void)didChangeArrangementCriteria
Discussion

This method is invoked by the controller itself when any criteria for arranging objects change (sort descriptors or filter predicates) to reset the key paths for automatic rearranging.

Special Considerations

If you implement a subclass of NSArrayController and override rearrangeObjects to use additional arrangement criteria, you should invoke this method if those criteria change.

Availability
  • Available in OS X v10.5 and later.
See Also
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 OS X v10.4 and later.
See Also
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.

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.

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 (see Error Responders and Error Recovery) can provide feedback as a sheet.

Availability
  • Available in OS X v10.3 and later.
See Also
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 OS X v10.3 and later.
See Also
Related Sample Code
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 OS X v10.3 and later.
See Also
Declared In
NSArrayController.h

preservesSelection

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

- (BOOL)preservesSelection
Return Value

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

Discussion

The default is YES.

This property is observable using key-value observing.

Availability
  • Available in OS X v10.3 and later.
See Also
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 OS X v10.3 and later.
See Also
Related Sample Code
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.

Discussion

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

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 (see Error Responders and Error Recovery) can provide feedback as a sheet.

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

removeObject:

Removes object from the receiver’s content collection.

- (void)removeObject:(id)object
Special Considerations

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 OS X v10.3 and later.
See Also
Related Sample Code
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 OS X v10.3 and later.
See Also
Related Sample Code
Declared In
NSArrayController.h

removeObjects:

Removes objects from the receiver’s content collection.

- (void)removeObjects:(NSArray *)objects
Special Considerations

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

Availability
  • Available in OS X v10.3 and later.
See Also
Related Sample Code
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 OS X v10.3 and later.
See Also
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 OS X v10.3 and later.
See Also
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 OS X v10.3 and later.
See Also
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 OS X v10.3 and later.
See Also
Related Sample Code
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 OS X v10.3 and later.
See Also
Related Sample Code
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 OS X v10.3 and later.
See Also
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 OS X v10.4 the result of this method is deferred until the next iteration of the runloop so that the error presentation mechanism (see Error Responders and Error Recovery) can provide feedback as a sheet.

Availability
  • Available in OS X v10.3 and later.
See Also
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 OS X v10.4 the result of this method is deferred until the next iteration of the runloop so that the error presentation mechanism (see Error Responders and Error Recovery) can provide feedback as a sheet.

Availability
  • Available in OS X v10.3 and later.
See Also
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 OS X v10.3 and later.
See Also
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 OS X v10.4 and later.
See Also
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

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 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 OS X v10.3 and later.
See Also
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 OS X v10.4 and later.
See Also
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 OS X v10.4 and later.
See Also
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 OS X v10.3 and later.
See Also
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 OS X v10.3 and later.
See Also
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 OS X v10.3 and later.
See Also
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 OS X v10.3 and later.
See Also
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 OS X v10.3 and later.
See Also
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 OS X v10.3 and later.
See Also
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 OS X v10.3 and later.
See Also
Related Sample Code
Declared In
NSArrayController.h


© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-11-17)

Did this document help you? Yes It's good, but... Not helpful...