NSBundle

Inherits From: NSObject

Conforms To: NSObject (NSObject)

Declared In: Foundation/NSBundle.h

Class Description

A bundle is a mechanism for grouping application resources into convenient chunks. A typical (but by no means the only) application of a bundle is to group executable code together with the resources used by that executable code. A major use of bundles is to handle localization issues, as described below in Localized Resources.

An NSBundle is an object that corresponds to a directory (or folder in the terminology of some operating systems) where application resources are stored. The directory, in essence, bundles a set of resources used by an application, and the NSBundle object makes those resources available to the application. NSBundle is able to find requested resources in the directory and, in some cases, dynamically load executable code. The term bundle is used both for the object and for the directory it represents.

Bundled resources might include such things as:

. ImagesTIFF or EPS (for instance) images used by an application's user interface components

. Sounds

. Localized character strings

. Executable code

. User Interface resourcesfiles describing the layout of user interface objects and their relationships with other objects

Each resource within a bundle usually resides in a separate file.

Localized Resources

If an application is to be used in more than one part of the world, its resources may need to be customized, or localized, for language, country, or cultural region. An application may need, for example, to have separate Japanese, English, French, Hindi, and Swedish versions of the character strings that label menu commands.

Resource files specific to a particular language are grouped together in a subdirectory of the bundle directory. The subdirectory has the name of the language (in English) followed by a .lproj extension (for language project). The application mentioned above, for example, would have Japanese.lproj, English.lproj, French.lproj, Hindi.lproj, and Swedish.lproj subdirectories.

Each .lproj subdirectory in a bundle has the same set of files; all versions of a resource file must have the same name.

The Main Bundle

Every application is considered to have at least one bundleits main bundlethe directory where its executable file is located. If the application is organized into a file package marked by a .app extension, the file package is the main bundle.

Other Bundles

An application can be organized into any number of other bundles in addition to the main bundle. For example, an application for managing PostScript printers may have a bundle full of PostScript code to be downloaded to printers.These other bundles usually reside inside the application file package, but they can be located anywhere in the file system. Each bundle directory is represented in the application by a separate NSBundle object.

By convention, bundle directories other than the main bundle end in a .bundle extension.

Dynamically Loadable Classes

Any bundle directory can contain a file with executable code. For the main bundle, that file is the application executable that's loaded into memory when the application is launched. The executable in the main bundle includes the main() function and other code necessary to start up the application.

Executable files in other bundle directories hold class (and category) definitions that the Bundle object can dynamically load while the application runs. When asked, the Bundle returns class objects for the classes (and categories) stored in the file. It waits to load the file until those classes are needed.

By using a number of separate bundles, you can split an application into smaller, more manageable pieces. Each piece is loaded into memory only when the code being executed requires it, so the application can start up faster than it otherwise would. And, assuming users will rarely exercise every part of an application, the application will also consume less memory as it runs.

The file that contains dynamically loadable code must have the same name as the bundle directory, but without the .bundle extension.

Since each bundle can have only one executable file, that file should be kept free of localizable content. Anything that needs to be localized should be segregated into separate resource files and stored in .lproj subdirectories.

Working with Bundles

Generally, you instantiate a bundle object by sending one of the bundleForClass:, bundleWithPath:, or mainBundle methods to the NSBundle class object. mainBundle gives you the NSBundle object corresponding to the directory containing the application's executable.

Initializing an NSBundle

• - (id)initWithPath:(NSString *)path Initializes a newly allocated NSBundle object to make it the NSBundle for the path directory.

• + (NSBundle *)bundleForClass:(Class)aClass Returns the NSBundle object that dynamically loaded aClass, or the main bundle object if aClass wasn't dynamically loaded.
• + (NSBundle *)bundleWithPath:(NSString *)path Returns an NSBundle object that's initialized for the path directory.
• + (NSBundle *)mainBundle Returns the NSBundle object that corresponds to the directory where the application executable is located.

• - (Class)classNamed:(NSString *)className Returns the class object for the className class, or nil if className isn't one of the classes associated with the receiver.
• - (Class)principalClass Returns the class object for the first class that's dynamically loaded by the NSBundle, or nil if the NSBundle can't dynamically load any classes.

• + (NSString *)pathForResource:(NSString *)name Returns the path for the resource identified by name, ofType:(NSString *)ext having the specified filename ext, inDirectory:(NSString *)bundlePath residing in bundlePath, withVersion:(int)version and having version number version.
• - (NSString *)pathForResource:(NSString *)name Returns the path for the resource identified by name ofType:(NSString *)ext having the specified filename extension ext.

• - (NSString *)bundlePath Returns a string containing the full pathname of the receiver's bundle directory.

• + (void)stripAfterLoading:(BOOL)flag Sets whether symbols are stripped when modules are loaded. The default is YES. You would usually set flag to NO for debugging purposes.

• - (NSString *)localizedStringForKey:(NSString *)key value:(NSString *)value Returns a localized version of the string designated by table:(NSString *)tableName key. tableName specifies the string table to search; if tableName is NULL, the file Localizable.strings is used. value specifies the value to return if the key or table can't be found (or if key is NULL).

• - (unsigned)bundleVersion Returns the version last set by the setBundleVersion: method, or 0 if no version has been set.
• - (void)setBundleVersion:(unsigned)version Sets the version that the NSBundle will use when searching .lproj subdirectories for resource files.