Mac Developer Library

Developer

AppKit Framework Reference NSObjectController Class Reference

Options
Deployment Target:

On This Page
Language:

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 objectClass, 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 property usesLazyFetching, 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:.

  • There are no changes in the controller's managed object context

  • Initializes and returns an NSObjectController object with the given content.

    Declaration

    Swift

    init(content content: AnyObject?)

    Objective-C

    - (instancetype)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 OS X v10.3 and later.

  • The receiver’s content object.

    Declaration

    Swift

    var content: AnyObject?

    Objective-C

    @property(strong) id content

    Availability

    Available in OS X v10.3 and later.

  • A boolean that shows 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

    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.

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    func prepareContent()

    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.

    Availability

    Available in OS X v10.3 and later.

  • The object class to use when creating new objects.

    Declaration

    Swift

    var objectClass: AnyClass!

    Objective-C

    @property(assign) Class objectClass

    Discussion

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

    Availability

    Available in OS X v10.3 and later.

  • Creates and returns a new object of the appropriate class.

    Declaration

    Swift

    func newObject() -> AnyObject

    Objective-C

    - (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 entityName), 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 YEStrue.

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

  • Sets the receiver’s content object.

    Declaration

    Swift

    func addObject(_ object: AnyObject)

    Objective-C

    - (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. In a tree-like structure, the object is added after the current selection at the same depth. If there is no selection, the object is appended to the child nodes of the tree’s arranged objects.

    Availability

    Available in OS X v10.3 and later.

  • Removes a given object from the receiver’s content.

    Declaration

    Swift

    func removeObject(_ 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

    Available in OS X v10.3 and later.

    See Also

    – addObject:

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

    Declaration

    Swift

    func add(_ sender: AnyObject?)

    Objective-C

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

  • A Boolean value that indicates whether an object can be added to the receiver using add:. (read-only)

    Declaration

    Swift

    var canAdd: Bool { get }

    Objective-C

    @property(readonly) BOOL canAdd

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

  • Removes the receiver’s content object.

    Declaration

    Swift

    func remove(_ sender: AnyObject?)

    Objective-C

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

  • A Boolean value that indicates whether an object can be removed from the receiver. (read-only)

    Declaration

    Swift

    var canRemove: Bool { get }

    Objective-C

    @property(readonly) BOOL canRemove

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

  • A boolean that indicates whether the receiver allows adding and removing objects.

    Declaration

    Swift

    var editable: Bool

    Objective-C

    @property(getter=isEditable) BOOL editable

    Discussion

    The default is YEStrue.

    Availability

    Available in OS X v10.10 and later.

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

    Declaration

    Swift

    var entityName: String?

    Objective-C

    @property(copy) NSString *entityName

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func fetch(_ sender: AnyObject?)

    Objective-C

    - (void)fetch:(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 can provide feedback as a sheet.

    Availability

    Available in OS X v10.4 and later.

    See Also

    fetchPredicate

  • A boolean that indicates whether the receiver uses lazy fetching.

    Declaration

    Swift

    var usesLazyFetching: Bool

    Objective-C

    @property BOOL usesLazyFetching

    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 OS X v10.5 and later.

  • Returns the default fetch request used by the receiver.

    Declaration

    Swift

    func defaultFetchRequest() -> NSFetchRequest

    Objective-C

    - (NSFetchRequest *)defaultFetchRequest

    Return Value

    The default NSFetchResult used by the receiver.

    Availability

    Available in OS X v10.5 and later.

    See Also

    usesLazyFetching

  • The receiver’s fetch predicate.

    Declaration

    Swift

    var fetchPredicate: NSPredicate?

    Objective-C

    @property(strong) NSPredicate *fetchPredicate

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

    See Also

    – fetch:

  • The receiver’s managed object context.

    Declaration

    Swift

    var managedObjectContext: NSManagedObjectContext?

    Objective-C

    @property(strong) NSManagedObjectContext *managedObjectContext

    Availability

    Available in OS X v10.4 and later.

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

    Declaration

    Swift

    func fetchWithRequest(_ fetchRequest: NSFetchRequest?, merge merge: Bool) throws

    Objective-C

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

    Parameters

    fetchRequest

    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

    Available in OS X v10.4 and later.

    See Also

    – fetch:

  • An array of all objects to be affected by editing. (read-only)

    Declaration

    Swift

    var selectedObjects: [AnyObject] { get }

    Objective-C

    @property(readonly, copy) NSArray *selectedObjects

    Availability

    Available in OS X v10.3 and later.

    See Also

    selection

  • A proxy object representing the receiver’s selection. (read-only)

    Declaration

    Swift

    var selection: AnyObject { get }

    Objective-C

    @property(readonly, strong) id selection

    Discussion

    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.

    Availability

    Available in OS X v10.3 and later.

    See Also

    selectedObjects