NSViewController Class Reference

Inherits from
Conforms to
NSCoding
NSCoding (NSResponder)
NSObject (NSObject)
NSEditor (Informal Protocol)
NSEditorRegistration (Informal Protocol)
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.5 and later.
Declared in
NSViewController.h
Related sample code

Overview

An NSViewController object manages a view, typically loaded from a nib file.

This management includes:

NSViewController is meant to be highly reusable. For example, the NSPageLayout and NSPrintPanel addAccessoryController: methods take an NSViewController instance as the argument, and set the representedObject to the NSPrintInfo that is to be shown to the user. This allows a developer to easily create new printing accessory views using bindings and the NSPrintInfo class' new key-value coding and key-value observing compliance. When the user dismisses a printing panel, NSPageLayout and NSPrintPanel each send NSEditor messages to each accessory view controller to ensure that the user's changes have been committed or discarded properly. The titles of the accessories are retrieved from the view controllers and shown to the user in pulldown menus that the user can choose from. If your application needs to dynamically associate relatively complex views with the objects that they present to the user, you might be able to reuse NSViewController in similar ways.

Tasks

Creating A View Controller

Represented Object

Nib Properties

View Properties

NSEditor Conformance

Instance Methods

commitEditing

Returns whether the receiver was able to commit any pending edits.

- (BOOL)commitEditing
Return Value

Returns YES if the changes were successfully applied to the model, NO otherwise.

Discussion

A commit is denied if the receiver fails to apply the changes to the model object, perhaps due to a validation error.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSViewController.h

commitEditingWithDelegate:didCommitSelector:contextInfo:

Attempt to commit any currently edited results of the receiver.

- (void)commitEditingWithDelegate:(id)delegate didCommitSelector:(SEL)didCommitSelector contextInfo:(void *)contextInfo
Parameters
delegate

An object that can serve as the receiver's delegate. It should implement the method specified by didCommitSelector.

didCommitSelector

A selector that is invoked on delegate.

contextInfo

Contextual information that is sent as the contextInfo argument to delegate when didCommitSelector is invoked.

Discussion

The receiver must have been registered as the editor of an object using objectDidBeginEditing:, and has not yet been unregistered by a subsequent invocation of objectDidEndEditing:. When the committing has either succeeded or failed, send the delegate the message specified by didCommitSelector.

The didCommitSelector method must have the following method signature:.

- (void)editor:(id)editor didCommit:(BOOL)didCommit contextInfo:(void  *)contextInfo

If an error occurs while attempting to commit, for example if key-value coding validation fails, an implementation of this method should typically send the receiver’s view apresentError:modalForWindow:delegate:didPresentSelector:contextInfo: message, specifying the view's containing window.

You may find this method useful in some situations when you want to ensure that pending changes are applied before a change in user interface state. For example, you may need to ensure that changes pending in a text field are applied before a window is closed. See also commitEditing which performs a similar function but which allows you to handle any errors directly, although it provides no information beyond simple success/failure.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSViewController.h

discardEditing

Causes the receiver to discard any changes, restoring the previous values.

- (void)discardEditing
Availability
  • Available in OS X v10.5 and later.
Declared In
NSViewController.h

initWithNibName:bundle:

Returns an NSViewController object initialized to the nib file in the specified bundle.

- (id)initWithNibName:(NSString *)nibNameOrNil bundle:(NSBundle *)nibBundleOrNil
Parameters
nibNameOrNil

The name of the nib file, without any leading path information.

nibBundleOrNil

The bundle in which to search for the nib file. If you specify nil, this method looks for the nib file in the main bundle.

Return Value

The initialized NSViewController object or nil if there were errors during initialization or the nib file could not be located.

Discussion

The NSViewController object looks for the nib file in the bundle's language-specific project directories first, followed by the Resources directory.

The specified nib should typically have the class of the file's owner set to NSViewController, or a custom subclass, with the view outlet connected to a view.

If you pass in a nil for nibNameOrNil then nibName will return nil and loadView will throw an exception; in this case you must invoke setView: before view is invoked, or override loadView.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSViewController.h

loadView

Instantiate the receiver’s view and set it.

- (void)loadView
Discussion

The default implementation of this method invokes nibName and nibBundle and then uses the NSNib class to load the nib with the receiver as the file's owner. If the view outlet of the file's owner in the nib is properly connected, the regular nib loading machinery will send the receiver a setView: message.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSViewController.h

nibBundle

Return the name of the nib bundle to be loaded to instantiate the receivers view.

- (NSBundle *)nibBundle
Return Value

The name of the nib bundle.

Discussion

The default implementation returns whatever value was passed to the initializer.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSViewController.h

nibName

Return the name of the nib to be loaded to instantiate the receivers view

- (NSString *)nibName
Return Value

The name of the nib.

Discussion

The default implementation returns whatever value was passed to the initializer.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSViewController.h

representedObject

Returns the object whose value is being presented in the receiver’s view.

- (id)representedObject
Return Value

The object whose value is presented in the receiver’s view.

Discussion

This class is key-value coding and key-value observing compliant for representedObject so when you use it as the file's owner of a view's nib you can bind controls to the file's owner using key paths that start with representedObject.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSViewController.h

setRepresentedObject:

Sets the object whose value is being presented in the receiver’s view.

- (void)setRepresentedObject:(id)representedObject
Parameters
representedObject

The object whose value is presented in the receiver’s view.

Discussion

The default implementation of this method doesn't copy the passed-in object, it retains it. In another words, representedObject is a to-one relationship, not an attribute.

This class is key-value coding and key-value observing compliant for representedObject so when you use it as the file's owner of a view's nib you can bind controls to the file's owner using key paths that start with representedObject.

Availability
  • Available in OS X v10.5 and later.
Related Sample Code
Declared In
NSViewController.h

setTitle:

Sets the localized title of the receiver’s view to the specified string.

- (void)setTitle:(NSString *)title
Parameters
title

The localized title of the receiver view.

Discussion

NSViewController does not use the title property directly. This property is here because so many anticipated uses of this class will involve letting the user choose among multiple named views using a pulldown menu or some other user interface.

This class is key value coding and key value compliant for this property.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
NSViewController.h

setView:

Sets the receivers view to the specified object.

- (void)setView:(NSView *)view
Parameters
view

The view the receiver should manage.

Discussion

You can invoke this method immediately after creating the object to specify a view that's created in a different manner than the receiver's default implementation would provide.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
NSViewController.h

title

Returns the localized title of the receiver’s view.

- (NSString *)title
Return Value

The localized title of the receiver’s view

Discussion

NSViewController does not use the title property directly. This property is here because so many anticipated uses of this class will involve letting the user choose among multiple named views using a pulldown menu or some other user interface.

This class is key value coding and key value compliant for this property.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSViewController.h

view

Returns the receiver’s view.

- (NSView *)view
Return Value

The receiver’s view object.

Discussion

The default implementation of this method first invokes loadView if the view hasn't been set yet.

Availability
  • Available in OS X v10.5 and later.
Declared In
NSViewController.h