Mac Developer Library

Developer

AppKit Framework Reference NSBundle AppKit Additions Reference

Options
Deployment Target:

On This Page
Language:

NSBundle

The Application Kit extends the behavior of the Foundation framework’s NSBundle class to support the loading of specific resource types. More...

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


import AppKit @import AppKit;

Availability


Available in OS X v10.0 and later.
  • Unarchives the contents of the nib file and links them to objects in your program.

    Declaration

    Objective-C

    + (BOOL)loadNibFile:(NSString *)fileName externalNameTable:(NSDictionary *)context withZone:(NSZone *)zone

    Parameters

    fileName

    The location of the nib file specified as an absolute path in the file system.

    context

    A name table whose keys identify objects associated with your program or the nib file. The newly unarchived objects from the nib file use this table to connect to objects in your program. For example, the nib file uses the object associated with the NSNibOwner constant as the nib file's owning object. If you associate an empty NSMutableArray object with the NSNibTopLevelObjects constant, on output, the array contains the top level objects from the nib file. For descriptions of these constants, see NSNib Class Reference.

    zone

    The memory zone in which to allocate the nib file objects.

    Return Value

    YEStrue if the nib file was loaded successfully; otherwise, NOfalse.

    Discussion

    This method is declared in NSNibLoading.h.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • Unarchives the contents of the nib file and links them to a specific owner object.

    Declaration

    Objective-C

    + (BOOL)loadNibNamed:(NSString *)aNibName owner:(id)owner

    Parameters

    aNibName

    The name of the nib file, which need not include the .nib extension. The file name should not include path information. The object in the owner parameter determines the location in which to look for the nib file.

    owner

    The object to assign as the nib File's Owner. If the class of this object has an associated bundle, that bundle is searched for the specified nib file; otherwise, this method looks in the main bundle.

    Return Value

    YEStrue if the nib file was loaded successfully; otherwise, NOfalse.

    Discussion

    This method is declared in NSNibLoading.h.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

    See Also

    bundleForClass: (NSBundle)

  • Unarchives the contents of a nib file located in the receiver's bundle.

    Declaration

    Objective-C

    - (BOOL)loadNibFile:(NSString *)fileName externalNameTable:(NSDictionary *)context withZone:(NSZone *)zone

    Parameters

    fileName

    The name of the nib file, which need not include the .nib extension.

    context

    A name table whose keys identify objects associated with your program or the nib file. The newly unarchived objects from the nib file use this table to connect to objects in your program. For example, the nib file uses the object associated with the NSNibOwner constant as the nib file's owning object. If you associate an empty NSMutableArray object with the NSNibTopLevelObjects constant, on output, the array contains the top level objects from the nib file. For descriptions of these constants, see NSNib Class Reference.

    zone

    The memory zone in which to allocate the nib file objects.

    Return Value

    YEStrue if the nib file was loaded successfully; otherwise, NOfalse.

    Discussion

    This method searches the language-specific project (.lproj) directories for the specified nib file. If the file is not there, it searches the bundle's Resources directory for a non-localized version of the file.

    This method is declared in NSNibLoading.h.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • Loads a nib from the bundle with the specified file name and owner.

    Declaration

    Swift

    func loadNibNamed(_ nibName: String, owner owner: AnyObject!, topLevelObjects topLevelObjects: AutoreleasingUnsafeMutablePointer<NSArray?>) -> Bool

    Objective-C

    - (BOOL)loadNibNamed:(NSString *)nibName owner:(id)owner topLevelObjects:(NSArray **)topLevelObjects

    Parameters

    nibName

    The name of the nib.

    owner

    The object that will be the nib’s owner.

    topLevelObjects

    This by-reference parameter is populated with the top level objects of the nib.

    Return Value

    YEStrue if the nib file was loaded successfully; otherwise, NOfalse.

    Discussion

    Unlike legacy methods, the objects adhere to the standard cocoa memory management rules; it is necessary to keep a strong reference to them by using IBOutlets or holding a reference to 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.

    For more information on Nibs, see NSNib Class Reference.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.8 and later.

  • Returns the location of the specified image resource as an NSURL.

    Declaration

    Swift

    func URLForImageResource(_ name: String) -> NSURL?

    Objective-C

    - (NSURL *)URLForImageResource:(NSString *)name

    Parameters

    name

    The name of the image resource file. Including a filename extension is optional.

    Return Value

    An NSURL for the resource file or nil if the file was not found.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Returns the location of the specified image resource file.

    Declaration

    Swift

    func pathForImageResource(_ name: String) -> String?

    Objective-C

    - (NSString *)pathForImageResource:(NSString *)name

    Parameters

    name

    The name of the image resource file, without any pathname information. Including a filename extension is optional.

    Return Value

    The absolute pathname of the resource file or nil if the file is not found.

    Discussion

    Image resources are those files in the bundle that are recognized by the NSImage class, including those that can be converted using the Image IO framework.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns an NSImage instance associated with the specified name, which can be backed by multiple files representing different resolution versions of the image.

    Declaration

    Swift

    func imageForResource(_ name: String) -> NSImage?

    Objective-C

    - (NSImage *)imageForResource:(NSString *)name

    Parameters

    name

    The filename of the image resource file. Including a filename extension is optional.

    Return Value

    The NSImage object associated with the specified name, or nil if no file is found.

    Discussion

    This method accommodates Apple’s naming conventions for high-resolution versions of the image. For example, if your bundle contains files named button.png, button@2x.png, and button.pdf then imageForResource:@"button" returns an NSImage object backed by all three files. Each time the NSImage object is drawn, it selects the representation best for the drawing context.

    Images requested using this method whose name ends in the word Template are automatically marked as template images.

    This method does not look up images based on setName: or get named system images. Use imageNamed: for that purpose.

    This method does not cache its search results.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.7 and later.

    See Also

    imageNamed: (NSImage)

  • Returns the context-sensitive help for the specified key from the bundle's help file.

    Declaration

    Swift

    func contextHelpForKey(_ key: String) -> NSAttributedString?

    Objective-C

    - (NSAttributedString *)contextHelpForKey:(NSString *)key

    Parameters

    key

    A key in your application's Help.plist file that identifies the context-sensitive help to return.

    Return Value

    The help string or nil if the application does not have a Help.plist file or the file does not contain an entry for the specified key.

    Discussion

    When you build your application, you can merge multiple RTF-based help files together using the /usr/bin/compileHelp tool, which then packages your help file information into a property list named Help.plist. After placing this property-list file in your application bundle, you can use this method to extract context help information from it. To look up a particular entry, you specify the name of the original RTF help file in the key parameter of this method. For example, if your application project contains a help file named Copy.rtf, you would retrieve the text from this file by passing the value @"Copy.rtf" to the key parameter.

    This method is declared in NSHelpManager.h.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    contextHelpForObject: (NSHelpManager)

  • Returns the location of the specified sound resource file.

    Declaration

    Swift

    func pathForSoundResource(_ name: String) -> String?

    Objective-C

    - (NSString *)pathForSoundResource:(NSString *)name

    Parameters

    name

    The name of the sound resource file, without any pathname information. Including a filename extension is optional

    Return Value

    The absolute pathname of the resource file or nil if the file was not found.

    Discussion

    Sound resources are those files in the bundle that are recognized by the NSSound class. The types of sound files can be determined by calling the soundUnfilteredFileTypes method of NSSound.

    This method is declared in NSSound.h.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

    See Also

    pathForResource:ofType: (NSBundle)