Mac Developer Library

Developer

AppKit Framework Reference NSNib Class Reference

Options
Deployment Target:

On This Page
Language:

NSNib

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

Inheritance


Conforms To


Import Statement


import AppKit @import AppKit;

Availability


Available in OS X v10.3 and later.
  • Returns an NSNib object initialized to the nib file at the specified URL.

    Deprecation Statement

    Use initWithNibData:bundle: and specify a bundle for locating images and other resources.

    Declaration

    Objective-C

    - (id)initWithContentsOfURL:(NSURL *)nibFileURL

    Parameters

    nibFileURL

    The location of the nib file.

    Return Value

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

    Discussion

    When you instantiate the nib objects later, the NSNib object looks for an appropriate bundle from which to search for any additional resources referenced by the nib. Because you do not specify a bundle directory when calling this method, the receiver uses the bundle associated with the class of the nib file’s owner. If the nib file does not have an owner, the receiver uses the application’s main bundle instead.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

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

    Declaration

    Swift

    init?(nibNamed nibName: String, bundle bundle: NSBundle?)

    Objective-C

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

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.3 and later.

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

    Declaration

    Swift

    init(nibData nibData: NSData, bundle bundle: NSBundle?)

    Objective-C

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

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.8 and later.

  • Unarchives and instantiates the in-memory contents of the receiver's nib file, creating a distinct object tree and set of top level objects.

    Deprecation Statement

    Use instantiateWithOwner:topLevelObjects: instead.

    Declaration

    Objective-C

    - (BOOL)instantiateNibWithOwner:(id)owner topLevelObjects:(NSArray **)topLevelObjects

    Parameters

    owner

    The object to use as the owner of the nib file. If the nib file has an owner, you must specify a valid object for this parameter.

    topLevelObjects

    On input, a variable capable of holding an NSArray object. On output, this variable contains an autoreleased NSArray object containing the top-level objects from the nib file. You may specify nil for this parameter if you are not interested in the top-level objects.

    Return Value

    YEStrue if the nib file's contents were instantiated successfully; otherwise, NOfalse.

    Discussion

    You may use this method to instantiate a nib file multiple times. This is a convenience method that composes the name-table dictionary and invokes the instantiateNibWithExternalNameTable: method, passing it the name table.

    Import Statement

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.8.

  • Unarchives and instantiates the in-memory contents of the receiver's nib file, creating a distinct object tree and top level objects.

    Deprecation Statement

    Use instantiateWithOwner:topLevelObjects: instead.

    Declaration

    Objective-C

    - (BOOL)instantiateNibWithExternalNameTable:(NSDictionary *)externalNameTable

    Parameters

    externalNameTable

    A dictionary containing entries for the nib file's owner and top-level objects. See the discussion for more information.

    Return Value

    YEStrue if the nib file's contents were instantiated successfully; otherwise, NOfalse.

    Discussion

    This is the primitive method for performing instantiations of a nib file. You may use this method to instantiate a nib file multiple times. Each instantiation of the nib must have a distinct owner object that is responsible for the resulting object tree.

    If the nib file requires an owner, the externalNameTable parameter must contain the object representing the nib file’s owner (associated with the NSNibOwner key). The parameter may optionally include an NSMutableArray object to be populated with the top-level objects nib file (associated with the NSNibTopLevelObjects key).

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • Instantiates objects in the nib file with the specified owner.

    Declaration

    Swift

    func instantiateWithOwner(_ owner: AnyObject?, topLevelObjects topLevelObjects: AutoreleasingUnsafeMutablePointer<NSArray?>) -> Bool

    Objective-C

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

    YEStrue if the nib is instantiated; otherwise NOfalse.

    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.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.8 and later.

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

    Declaration

    Objective-C

    NSString *NSNibOwner; NSString *NSNibTopLevelObjects;

    Constants

    • NSNibOwner

      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.

    • NSNibTopLevelObjects

      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.

    Import Statement