Next Page > Hide TOC

NSViewController Class Reference

Overview

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

This management includes:

• Memory management of top-level objects similar to that of the NSWindowController class, taking the same care to prevent reference cycles when controls are bound to the nib file's owner that NSWindowController began taking in Mac OS v 10.4.

• Declaring a generic representedObject property, to make it easy to establish bindings in the nib to an object that isn't yet known at nib-loading time or readily available to the code that's doing the nib loading.

• Implementing the key-value binding NSEditor informal protocol, so that applications using NSViewController can easily make bound controls in the views commit or discard the changes the user is making.

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

• – initWithNibName:bundle:
• – loadView

Represented Object

• – setRepresentedObject:
• – representedObject

Nib Properties

• – nibBundle
• – nibName

View Properties

• – view
• – setView:
• – title
• – setTitle:

NSEditor Conformance

• – commitEditingWithDelegate:didCommitSelector:contextInfo:
• – commitEditing
• – discardEditing

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

See Also

• – commitEditingWithDelegate:didCommitSelector:contextInfo:
• – discardEditing

Declared In

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

See Also

• – commitEditing
• – discardEditing

Declared In

discardEditing

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

- (void)discardEditing

Availability

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

See Also

• – commitEditing

Declared In

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

Related Sample Code

• ViewController

Declared In

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

Declared In

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

See Also

• – initWithNibName:bundle:
• – nibName

Declared In

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

See Also

• – initWithNibName:bundle:
• – nibBundle

Declared In

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

See Also

• – setRepresentedObject:

Declared In

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

See Also

• – representedObject

Declared In

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

See Also

• – title

Declared In

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

See Also

• – view

Declared In

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

See Also

• – setTitle:

Declared In

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

See Also

• – setView:
• – loadView

Declared In

Next Page > Hide TOC