NSObjectController

NSObjectController is a Cocoa bindings-compatible controller class. Properties of the content object of instances of this class can be bound to user interface elements to access and modify their values.

By default, the content of an NSObjectController instance is an NSMutableDictionary object. This allows a single NSObjectController instance to be used to manage many different properties referenced by key-value paths. The default content object class can be changed by calling setObjectClass:, which subclasses must override. Your application should use a custom data class that is key-value compliant whenever possible.

Object Controllers, Entity Mode, and Lazy Fetching

NSObjectController and its subclasses, when in entity mode, can now fetch lazily. With lazy fetching enabled using the method setUsesLazyFetching:, the controller will try to fetch only a small amount of data from available persistent stores. This can provide a significant improvement in memory use when a large amount of content is stored on disk but just a subset of that data is required in memory.

When set to use lazy fetching, a controller will fetch objects in batches. You can change the default batch size for your application by setting a value for the the user default "com.apple.CocoaBindings.LazyFetchBatchSize". If you have table views bound to an array controller set to use lazy fetching, the size of the controller's batch size will grow as the table views' visible row count grows.

Add, Insert, and Remove operations on controllers that use lazy fetching behave similarly to the same operations on a regular controller. The difference is that it is faster to sort an array controller using lazy fetching if:

All of the keys in the sortDescriptors array are modeled, non transient properties.

All of the selectors in the sortDescriptors array are compare: or caseInsensitiveCompare:.

Import Statement

Availability

See Also

Sets whether the receiver automatically creates and inserts new content objects automatically when loading from a nib file.

Declaration

Swift

var automaticallyPreparesContent: Bool

Objective-C

@property BOOL automaticallyPreparesContent

Parameters

flag

A flag that specifies whether the receiver automatically prepares its content.

Discussion

If flag is YEStrue and the receiver is not using a managed object context, prepareContent is used to create the content object. If flag is YEStrue and a managed object context is set, the initial content is fetched from the managed object context using the current fetch predicate. The default is NOfalse.

Import Statement

Availability

See Also

Typically overridden by subclasses that require additional control over the creation of new objects.

Declaration

Swift

funcprepareContent()

Objective-C

- (void)prepareContent

Discussion

Subclasses that implement this method are responsible for creating the new content object and setting it as the receiver’s content object. This method is only called if automaticallyPreparesContent has been set to YEStrue.

Declaration

Return Value

A new object of the appropriate class. The returned object is implicitly retained, the sender is responsible for releasing it (with either release or autorelease).

If an entity name is set (see setEntityName:), the object created is an instance of the class specified for that entity (and the object is inserted into the receiver's managed object context). Otherwise the object created is an instance of the class returned by objectClass.

Discussion

The default implementation assumes the class returned by objectClass has a standard init method without arguments. If the object class being controlled is NSManagedObject (or a subclass thereof) its designated initializer (initWithEntity:insertIntoManagedObjectContext:) is called instead, using the entity and managed object context specified for the receiver.

Import Statement

Availability

See Also

Declaration

Swift

funcremoveObject(_object: AnyObject)

Objective-C

- (void)removeObject:(id)object

Parameters

object

The object to remove from the receiver.

Discussion

If object is the receiver’s content object, the receiver’s content is set to nil. If the receiver's content is bound to another object or controller through a relationship key, the relationship of the ‘master’ object is cleared.

Availability

See Also

Declaration

Swift

var usesLazyFetching: Bool

Objective-C

@property BOOL usesLazyFetching

Parameters

enabled

Boolean value that indicates whether the receiver uses lazy fetching.

Discussion

When enabled the controller uses a number of techniques that typically make managing large data sets more efficient. As with all optimizations, you should use suitable performance analysis tools (such as Instruments) to determine the best solution.

Note

Setting setUsesLazyFetching: to YEStrue will cause an exception if the receiving controller is not bound to a managed object context.

Parameters

The fetch request to use for the fetch. Pass nil to use the default fetch request.

merge

If YEStrue, the receiver merges the existing content with the fetch result, otherwise the receiver replaces the entire content with the fetch result.

error

If an error occurs, upon return contains an NSError object that describes the problem.

Return Value

YEStrue if the fetch completed successfully, otherwise NOfalse.

Discussion

This method performs a number of actions that you cannot reproduce. To customize this method, you should therefore create your own fetch request and then invoke super’s implementation with the new fetch request.

Availability

See Also

Declaration

Swift

var selectedObjects: [AnyObject] { get }

Objective-C

@property(readonly, copy) NSArray *selectedObjects

Return Value

An array of all objects to be affected by editing. If the receiver supports a selection mechanism, the array contains key value coding compliant proxies of the selected objects; otherwise proxies for all content objects are returned. If the receiver is a concrete instance of NSObjectController, returns an array containing the receiver’s content object.

Discussion

You should avoid registering for key-value observing changes for key paths that pass through this method, (for example, selectedObjects.firstName). Using the proxy returned by the selection method is better for performance.

Import Statement

Availability

See Also

Declaration

Swift

var selection: AnyObject { get }

Objective-C

@property(readonly, strong) id selection

Return Value

A proxy object representing the receiver’s selection. This object is fully key-value coding compliant, but note that it is a proxy and so does not provide the full range of functionality that might be available in the source object.

Discussion

If a value requested from the selection proxy using key-value coding returns multiple objects, the controller has no selection, or the proxy is not key-value coding compliant for the requested key, the appropriate marker (NSMultipleValuesMarker, NSNoSelectionMarker or NSNotApplicableMarker) is returned. Otherwise, the value of the key is returned.