---

NSObjectController Class Reference

Overview

NSObjectController is a Cocoa bindings-compatible controller class. Properties of the content object of an instance 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 subclassers must override.

Tasks

Initializing an Object Controller

• – initWithContent:

Managing Content

• – setContent:
• – content
• – setAutomaticallyPreparesContent:
• – automaticallyPreparesContent
• – prepareContent

Setting the Content Class

• – setObjectClass:
• – objectClass

Managing Objects

• – newObject
• – addObject:
• – removeObject:
• – add:
• – canAdd
• – remove:
• – canRemove

Managing Editing

• – setEditable:
• – isEditable

Core Data Support

• – entityName
• – setEntityName:
• – fetch:
• – setUsesLazyFetching:
• – usesLazyFetching
• – defaultFetchRequest
• – fetchPredicate
• – setFetchPredicate:
• – managedObjectContext
• – setManagedObjectContext:
• – fetchWithRequest:merge:error:

Obtaining Selections

• – selectedObjects
• – selection

Validating User Interface Items

• – validateUserInterfaceItem:

Instance Methods

add:

Creates a new object and sets it as the receiver’s content object.

- (void)add:(id)sender

Parameters

sender

Typically the object that invoked this method.

Discussion

Creates a new object of the appropriate entity (specified by entityName) or class (specified by objectClass)—see newObject—and sets it as the receiver’s content object using addObject:.

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

• – canAdd
• – remove:

Declared In

NSObjectController.h

addObject:

Sets the receiver’s content object.

- (void)addObject:(id)object

Parameters

object

The content object for the receiver.

Discussion

If the receiver's content is bound to another object or controller through a relationship key, the relationship of the “master” object is changed.

Availability

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

See Also

• – removeObject:

Declared In

NSObjectController.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 NO.

Availability

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

See Also

• – setAutomaticallyPreparesContent:
• – prepareContent

Declared In

NSObjectController.h

canAdd

Returns a Boolean value that indicates whether an object can be added to the receiver using add:.

- (BOOL)canAdd

Return Value

YES if an object can be added to the receiver using add:, otherwise NO.

Discussion

Bindings can use this method to control the enabling of user interface objects.

This property is observable using key-value observing.

Availability

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

See Also

• – canRemove
• – add:

Declared In

NSObjectController.h

canRemove

Returns a Boolean value that indicates whether an object can be removed from the receiver.

- (BOOL)canRemove

Return Value

YES if an object can be removed from the receiver using remove:, otherwise NO.

Discussion

Bindings can use this method to control the enabling of user interface objects.

This property is observable using key-value observing.

Availability

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

See Also

• – canAdd
• – remove:

Declared In

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

See Also

• – setContent:

Related Sample Code

• Aperture Edit Plugin - Borders & Titles

Declared In

NSObjectController.h

defaultFetchRequest

Returns the default fetch request used by the receiver.

- (NSFetchRequest *)defaultFetchRequest

Return Value

The default NSFetchResult used by the receiver.

Availability

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

See Also

• – setUsesLazyFetching:
• – usesLazyFetching

Declared In

NSObjectController.h

entityName

Returns the entity name used by the receiver to create new objects.

- (NSString *)entityName

Return Value

The entity name used by the receiver to create new objects.

Availability

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

See Also

• – setEntityName:

Declared In

NSObjectController.h

fetch:

Causes the receiver to fetch the data objects specified by the entity name and fetch predicate.

- (void)fetch:(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.

See Also

• – setFetchPredicate:
• – fetchPredicate

Declared In

NSObjectController.h

fetchPredicate

Returns the receiver’s fetch predicate.

- (NSPredicate *)fetchPredicate

Return Value

The receiver’s fetch predicate.

Availability

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

See Also

• – fetch:
• – setFetchPredicate:

Declared In

NSObjectController.h

fetchWithRequest:merge:error:

Subclasses should override this method to customize a fetch request, for example to specify fetch limits.

- (BOOL)fetchWithRequest:(NSFetchRequest *)fetchRequest merge:(BOOL)merge error:(NSError **)error

Parameters

fetchRequest

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

merge

If YES, 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

YES if the fetch completed successfully, otherwise NO.

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

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

See Also

• – fetch:

Declared In

NSObjectController.h

initWithContent:

Initializes and returns an NSObjectController object with the given content.

- (id)initWithContent:(id)content

Parameters

content

The content for the receiver.

Return Value

The initialized object controller, with its content object set to content.

Availability

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

Declared In

NSObjectController.h

isEditable

Returns a Boolean value that indicates whether the receiver allows adding and removing objects.

- (BOOL)isEditable

Return Value

YES if the receiver allows adding and removing objects, otherwise NO.

Discussion

This property is observable using key-value observing.

Availability

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

See Also

• – setEditable:

Declared In

NSObjectController.h

managedObjectContext

Returns the receiver’s managed object context.

- (NSManagedObjectContext *)managedObjectContext

Return Value

The receiver’s managed object context.

Availability

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

See Also

• – setManagedObjectContext:

Declared In

NSObjectController.h

newObject

Creates and returns a new object of the appropriate class.

- (id)newObject

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

This method is called when adding and inserting objects if automaticallyPreparesContent is YES.

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.

Availability

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

See Also

• – setObjectClass:
• – objectClass
• – setEntityName:
• – entityName

Declared In

NSObjectController.h

objectClass

Returns the class used when creating new non-Core Data objects.

- (Class)objectClass

Return Value

The object class used when creating new non-Core Data objects (that is, if no entity has been set)—see newObject.

Discussion

If an entity has been set, then the class returned by this method does not automatically reflect the class for the entity.

The default class is NSMutableDictionary.

This property is observable using key-value observing.

Availability

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

See Also

• – setObjectClass:
• – entityName
• – managedObjectContext

Declared In

NSObjectController.h

prepareContent

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

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

Availability

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

See Also

• – automaticallyPreparesContent
• – setAutomaticallyPreparesContent:

Related Sample Code

• QTMetadataEditor

Declared In

NSObjectController.h

remove:

Removes the receiver’s content object.

- (void)remove:(id)sender

Parameters

sender

Typically the object that invoked this method.

Discussion

Removes the receiver’s content object using removeObject:.

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

• – canRemove
• – add:

Declared In

NSObjectController.h

removeObject:

Removes a given object from the receiver’s content.

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

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

See Also

• – addObject:

Declared In

NSObjectController.h

selectedObjects

Returns an array of all objects to be affected by editing.

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

This property is observable using key-value observing.

Availability

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

See Also

• – selection

Declared In

NSObjectController.h

selection

Returns a proxy object representing the receiver’s selection.

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

This property is observable using key-value observing.

Availability

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

See Also

• – selectedObjects

Declared In

NSObjectController.h

setAutomaticallyPreparesContent:

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

- (void)setAutomaticallyPreparesContent:(BOOL)flag

Parameters

flag

A flag that specifies whether 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 default is NO.

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

Availability

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

See Also

• – automaticallyPreparesContent
• – prepareContent

Declared In

NSObjectController.h

setContent:

Sets the receiver’s content object.

- (void)setContent:(id)content

Parameters

content

The content object for the receiver.

Availability

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

See Also

• – content

Declared In

NSObjectController.h

setEditable:

Sets whether the receiver allows adding and removing objects.

- (void)setEditable:(BOOL)flag

Parameters

flag

YES if the the receiver should allow adding and removing objects, otherwise NO.

Discussion

The default is YES.

Availability

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

See Also

• – isEditable

Declared In

NSObjectController.h

setEntityName:

Sets the entity name used by the receiver to create new objects.

- (void)setEntityName:(NSString *)entityName

Parameters

entityName

The entity name used by the receiver to create new objects.

Availability

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

See Also

• – entityName

Declared In

NSObjectController.h

setFetchPredicate:

Sets the receiver’s fetch predicate.

- (void)setFetchPredicate:(NSPredicate *)predicate

Parameters

predicate

The fetch predicate for the receiver.

Discussion

The receiver uses predicate when fetching its content, for example in fetch:. If you need to customize the fetching behavior further, you can override fetchWithRequest:merge:error:.

Availability

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

See Also

• – fetch:
• – fetchPredicate
• – fetchWithRequest:merge:error:

Declared In

NSObjectController.h

setManagedObjectContext:

Sets the receiver’s managed object context.

- (void)setManagedObjectContext:(NSManagedObjectContext *)managedObjectContext

Parameters

managedObjectContext

The managed object context for the receiver.

Availability

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

See Also

• – managedObjectContext

Declared In

NSObjectController.h

setObjectClass:

Sets the object class to use when creating new objects.

- (void)setObjectClass:(Class)objectClass

Parameters

objectClass

The object class to use when creating new objects.

Discussion

NSObjectController's default implementation assumes that instances of objectClass are initialized using a standard init method that takes no arguments.

If an entity name has been set (see setEntityName:), this method has no effect.

Availability

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

See Also

• – objectClass
• – setEntityName:
• – managedObjectContext

Declared In

NSObjectController.h

setUsesLazyFetching:

Sets whether the receiver uses lazy fetching.

- (void)setUsesLazyFetching:(BOOL)enabled

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.

Availability

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

See Also

• – defaultFetchRequest
• – usesLazyFetching

Declared In

NSObjectController.h

usesLazyFetching

Returns a Boolean indicating whether the receiver uses lazy fetching.

- (BOOL)usesLazyFetching

Return Value

YES if the receiver uses lazy fetching, otherwise NO.

Availability

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

See Also

• – defaultFetchRequest
• – setUsesLazyFetching:

Declared In

NSObjectController.h

validateUserInterfaceItem:

Returns whether the receiver can handle the action method for a user interface item.

- (BOOL)validateUserInterfaceItem:(id < NSValidatedUserInterfaceItem >)item

Parameters

item

The user interface item to validate. You can send item the action and tag messages.

Return Value

YES if the receiver can handle the action method; NO if it cannot.

Availability

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

Declared In

NSObjectController.h

---