NSBundle AppKit Additions Reference

Inherits from
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.0 and later.
Companion guide
Declared in
NSHelpManager.h
NSImage.h
NSNibLoading.h
NSSound.h

Overview

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

The NSBundle additions add support for the following tasks:

These methods become part of the NSBundle class only for those applications that use the Application Kit.

Tasks

Loading Nib Files

Locating Image Resources

Accessing Context Help

Locating Sound Resources

Instance Methods

contextHelpForKey:

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

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

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSHelpManager.h

imageForResource:

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

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

Availability
  • Available in OS X v10.7 and later.
See Also
Declared In
NSImage.h

loadNibNamed:owner:topLevelObjects:

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

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

YES if the nib file was loaded successfully; otherwise, NO.

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.

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

pathForImageResource:

Returns the location of the specified image resource file.

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSImage.h

pathForSoundResource:

Returns the location of the specified sound resource file.

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

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSSound.h

URLForImageResource:

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

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

Availability
  • Available in OS X v10.6 and later.
Declared In
NSImage.h