---

NSArrayController

Overview

The NSArrayController is a bindings compatible class that manages an array of objects. It provides selection management and sorting capabilities.

Tasks

Constructors

• NSArrayController

Managing Sort Descriptors

• setSortDescriptors
• sortDescriptors

Arranging Objects

• arrangeObjects
• arrangedObjects

Setting Selection Attributes

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

Getting the Current Selection

• setSelectionIndex
• selectionIndex

Managing Selections

• setSelectsInsertedObjects
• selectsInsertedObjects
• setSelectionIndexes
• selectionIndexes
• addSelectionIndexes
• removeSelectionIndexes
• setSelectedObjects
• selectedObjects
• addSelectedObjects
• removeSelectedObjects
• selectNext
• canSelectNext
• selectPrevious
• canSelectPrevious

Inserting

• canInsert
• insert

Adding and Removing Objects

• addObject
• addObjects
• insertObject
• insertObjects
• remove
• removeObject
• removeObjects

Filtering Objects

• clearsFilterPredicateOnInsertion
• filterPredicate
• setFilterPredicate

Instance Methods

addObject

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

public void addObject(Object object)

Availability

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

See Also

• addObjects
• insertObject
• removeObject

addObjects

Adds objects to the receiver’s content array.

public void addObjects(NSArray objects)

Discussion

If selectsInsertedObjects returns true, which is 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 false before adding the objects with addObjects.

Availability

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

See Also

• addObject
• insertObjects
• removeObjects

addSelectedObjects

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

public boolean 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

addSelectionIndexes

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

public boolean 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

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.

public boolean alwaysUsesMultipleValuesMarker()

Discussion

The default is false.

This property is observable using key-value observing.

Availability

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

See Also

• setAlwaysUsesMultipleValuesMarker

arrangedObjects

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

public Object arrangedObjects()

Discussion

.

This property is observable using key-value observing.

Availability

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

See Also

• arrangeObjects

arrangeObjects

Returns an array containing the content of the objects array arranged according to the receiver’s sortDescriptors.

public NSArray arrangeObjects(NSArray objects)

Discussion

Subclasses should override this method to use a different sort mechanism, provide custom object arrangement, or filter the objects.

Availability

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

See Also

• arrangedObjects

avoidsEmptySelection

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

public boolean avoidsEmptySelection()

Discussion

The default is true.

This property is observable using key-value observing.

Availability

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

See Also

• setAvoidsEmptySelection

canInsert

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

public boolean canInsert()

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

canSelectNext

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

public boolean 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

canSelectPrevious

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

public boolean 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

clearsFilterPredicateOnInsertion

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

public boolean clearsFilterPredicateOnInsertion()

Discussion

The default is true.

This property is observable using key-value observing.

Availability

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

See Also

• setClearsFilterPredicateOnInsertion

filterPredicate

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

public NSPredicate filterPredicate()

Discussion

Returns null if no filter predicate is set.

This property is observable using key-value observing.

Availability

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

See Also

• setClearsFilterPredicateOnInsertion

insert

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

public void insert(Object sender)

Discussion

The sender is typically the object that invoked this method.

Availability

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

See Also

• canInsert

insertObject

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

public void insertObject(Object object, int 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
• addObject
• removeObject

insertObjects

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

public void insertObjects(NSArray objects, NSIndexSet indexes)

Availability

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

See Also

• insertObject
• addObjects
• removeObjects

preservesSelection

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

public boolean preservesSelection()

Discussion

The default is true.

This property is observable using key-value observing.

Availability

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

See Also

• setClearsFilterPredicateOnInsertion

remove

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

public void remove(Object object)

Discussion

The sender is typically the object that invoked this method.

Availability

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

See Also

• removeObjects
• addObject

removeObject

Removes object from the receiver’s content collection.

public void removeObject(Object 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.

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

public void removeObject(int index)

Availability

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

See Also

• removeObjects
• addObject

removeObjects

Removes objects from the receiver’s content array.

public void removeObjects(NSArray objects)

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

public void removeObjects(NSIndexSet indexes)

Availability

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

See Also

• removeObject
• addObjects

removeSelectedObjects

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

public boolean 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

removeSelectionIndexes

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

public boolean 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

selectedObjects

Returns an array containing the receiver’s selected objects.

public NSArray selectedObjects()

Discussion

This property is observable using key-value observing.

Availability

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

See Also

• setSelectedObjects

selectionIndex

Returns the index of the first object in the receiver’s selection, NSArray.NotFound if there is no selection.

public int selectionIndex()

Discussion

This property is observable using key-value observing.

Availability

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

See Also

• setSelectionIndex
• selectionIndexes

selectionIndexes

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

public NSIndexSet selectionIndexes()

Discussion

This property is observable using key-value observing.

Availability

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

See Also

• setSelectionIndexes
• selectionIndex

selectNext

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

public void selectNext(Object sender)

Discussion

The sender is typically the object that invoked this method.

Availability

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

See Also

• selectPrevious
• canSelectNext

selectPrevious

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

public void selectPrevious(Object sender)

Discussion

The sender is typically the object that invoked this method.

Availability

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

See Also

• selectNext
• canSelectPrevious

selectsInsertedObjects

Returns whether the receiver selects inserted objects automatically.

public boolean selectsInsertedObjects()

Discussion

The default is true.

This property is observable using key-value observing.

Availability

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

See Also

• setSelectsInsertedObjects

setAlwaysUsesMultipleValuesMarker

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

public void setAlwaysUsesMultipleValuesMarker(boolean flag)

Discussion

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

Availability

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

See Also

• alwaysUsesMultipleValuesMarker

setAvoidsEmptySelection

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

public void setAvoidsEmptySelection(boolean)

Discussion

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

Availability

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

See Also

• avoidsEmptySelection

setClearsFilterPredicateOnInsertion

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

public void setClearsFilterPredicateOnInsertion(boolean flag)

Discussion

The default is true.

Availability

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

See Also

• clearsFilterPredicateOnInsertion

setFilterPredicate

Sets the predicate used to filter the contents of the receiver to filterPredicate, replacing any existing filter predicate.

public void setFilterPredicate(NSPredicate filterPredicate)

Discussion

If filterPredicate is null any existing filter predicate is removed.

Availability

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

See Also

• filterPredicate

setPreservesSelection

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

public void setPreservesSelection(boolean flag)

Discussion

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

Availability

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

See Also

• preservesSelection

setSelectedObjects

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

public boolean 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

setSelectionIndex

Sets the receiver’s current selection to index, returning true if the selection was changed.

public boolean setSelectionIndex(int index)

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

setSelectionIndexes

Sets the receiver’s current selection to the objects at indexes, returning true if the selection was changed.

public boolean setSelectionIndexes(NSIndexSet indexes)

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 NSIndexSet with indexes [0..count -1]. To deselect all indexes, pass an empty NSIndexSet.

Availability

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

See Also

• selectionIndexes
• setSelectionIndex

setSelectsInsertedObjects

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

public void setSelectsInsertedObjects(boolean flag)

Discussion

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

Availability

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

See Also

• selectsInsertedObjects

setSortDescriptors

Sets the sort descriptors used by the receiver to arrange objects to sortDescriptors.

public void setSortDescriptors(NSArray sortDescriptors)

Availability

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

See Also

• sortDescriptors

sortDescriptors

Returns an array of sort descriptors used by the receiver to arrange objects.

public NSArray sortDescriptors()

Discussion

This property is observable using key-value observing.

Availability

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

See Also

• setSortDescriptors

---