---

NSBundle Additions Reference

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:

• Loading nib files

• Locating image and sound resources

• Accessing context help from a Help.plist file

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

Tasks

Loading Nib Files

• + loadNibFile:externalNameTable:withZone:
• + loadNibNamed:owner:
• – loadNibFile:externalNameTable:withZone:

Locating Image Resources

• – pathForImageResource:

Accessing Context Help

• – contextHelpForKey:

Locating Sound Resources

• – pathForSoundResource:

Class Methods

loadNibFile:externalNameTable:withZone:

Unarchives the contents of the nib file and links them to objects in your program.

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

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

Discussion

This method is declared in NSNibLoading.h.

Availability

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

Declared In

NSNibLoading.h

loadNibNamed:owner:

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

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

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

Discussion

This method is declared in NSNibLoading.h.

Availability

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

See Also

• + bundleForClass: (NSBundle)

Related Sample Code

• MyPhoto
• NumberInput_IMKit_Sample
• QTAudioExtractionPanel
• Reducer
• WhackedTV

Declared In

NSNibLoading.h

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

See Also

• – contextHelpForObject: (NSHelpManager)

Declared In

NSHelpManager.h

loadNibFile:externalNameTable:withZone:

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

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

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

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 nonlocalized version of the file.

This method is declared in NSNibLoading.h.

Availability

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

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

This method is declared in NSImage.h.

Availability

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

See Also

• – pathForResource:ofType: (NSBundle)

Related Sample Code

• LayerBackedOpenGLView

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

See Also

• – pathForResource:ofType: (NSBundle)

Declared In

NSSound.h

---