NSNib Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.3 and later.
Companion guide
Declared in
NSNib.h
Related sample code

Overview

Instances of the NSNib class serve as object wrappers, or containers, for Interface Builder nib files. An NSNib object keeps the contents of a nib file resident in memory, ready for unarchiving and instantiation.

When you create an NSNib object using the contents of a nib file, the object loads the contents of the referenced nib bundle—the object graph as well as any images and sounds—into memory; but it does not yet unarchive it. To unarchive all of the nib data and thus truly instantiate the nib you must call one of the instantiate... methods of NSNib.

During the instantiation process, each object in the archive is unarchived and then initialized using the method befitting its type. View classes are initialized using their initWithFrame: method. Custom objects are initialized using their init method. In the case of Cocoa views (and custom views that have options on an associated Interface Builder palette) the initialization process also reads in any values set by the user in Interface Builder.

Once all objects have been instantiated and initialized from the archive, the nib loading code attempts to reestablish the connections between each object’s outlets and the corresponding target objects. If your custom objects have outlets, the NSNib object attempts to reestablish any connections you created in Interface Builder. It starts by trying to establish the connections using your object’s own methods first. For each outlet that needs a connection, the NSNib object looks for a method of the form setOutletName: in your object. If that method exists, the nib object calls it, passing the target object as a parameter. If you did not define a setter method with that exact name, the NSNib object searches the object for an instance variable (of type IBOutlet id) with the corresponding outlet name and tries to set its value directly. If an instance variable with the correct name cannot be found, initialization of that connection does not occur.

After all objects have been initialized and their connections reestablished, each object receives an awakeFromNib message. You can override this method in your custom objects to perform any additional initialization.

Subclassing Notes

You can subclass NSNib if you want to extend or specialize nib-loading behavior. For example, you could create a custom NSNib subclass that performs some post-processing on the top-level objects returned from the instantiateNib... methods. If you want to modify how nib instantiations are performed, it is recommended that you override the primitive method instantiateWithOwner:topLevelObjects:. Note that the instance variables of NSNib are private and thus are not available to subclasses. Any override of initWithNibData:bundle: or initWithNibNamed:bundle: should first invoke the superclass implementation.

Adopted Protocols

NSCoding

Tasks

Initializing a Nib

Instantiating a Nib

Instance Methods

initWithNibData:bundle:

Initializes an instance with nib data and specified bundle for locating resources.

- (id)initWithNibData:(NSData *)nibData bundle:(NSBundle *)bundle
Parameters
nibData

The nib data.

bundle

The bundle for locating resources. If nil, the main application bundle is used.

Return Value

The initialized NSNib object or nil if there were errors during initialization.

Availability
  • Available in OS X v10.8 and later.
Declared In
NSNib.h

initWithNibNamed:bundle:

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

- (id)initWithNibNamed:(NSString *)nibName bundle:(NSBundle *)bundle
Parameters
nibName

The name of the nib file, without any leading path information. Inclusion of the .nib extension on the nib file name is optional.

bundle

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 NSNib object or nil if there were errors during initialization or the nib file could not be located.

Discussion

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

After the nib file has been loaded, the NSNib object uses the bundle’s resource map to locate additional resources referenced by the nib. If you specified nil for the bundle parameter, the NSNib object looks for those resources in the bundle associated with the class of the nib file’s owner instead. If the nib file does not have an owner, the NSNib object looks for additional resources in the application’s main bundle.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSNib.h

instantiateWithOwner:topLevelObjects:

Instantiates objects in the nib file with the specified owner.

- (BOOL)instantiateWithOwner:(id)owner topLevelObjects:(NSArray **)topLevelObjects
Parameters
owner

The object to set as the Nib’s owner (File’s Owner).

topLevelObjects

On return, an array containing the top-level objects of the nib.

Return Value

YES if the nib is instantiated; otherwise NO.

Discussion

Unlike legacy methods, the objects adhere to standard Cocoa memory management rules; it is necessary to keep a strong reference to the objects or the array to prevent the nib contents from being deallocated.

Outlets to top level objects should be strong references to demonstrate ownership and prevent deallocation.

Availability
  • Available in OS X v10.8 and later.
Declared In
NSNib.h

Constants

Nib Loading Keys

The NSNib class uses the following constants which are used as keys in the dictionary passed to instantiateNibWithExternalNameTable:.

NSString *NSNibOwner;
NSString *NSNibTopLevelObjects;
Constants
NSNibOwner

The external object that is responsible for the instantiated nib.

This key is required.

Available in OS X v10.0 and later.

Deprecated in OS X v10.8.

Declared in NSNib.h.

NSNibTopLevelObjects

An NSMutableArray object that, if present, is populated with the top-level objects of the newly instantiated nib.

Because you must allocate this array, you are responsible for its disposal. This key is optional.

Available in OS X v10.0 and later.

Deprecated in OS X v10.8.

Declared in NSNib.h.

Declared In
NSNib.h