Next Page > Hide TOC

NSBundle

Overview

An NSBundle represents a location in the file system that groups code and resources that can be used in a program. NSBundles locate program resources, dynamically load executable code, and assist in localization. You build a bundle in Xcode using one of these project types: Application, Framework, Loadable Bundle, Palette.

Tasks

Constructors

• NSBundle

Getting an NSBundle

• bundleForClass
• bundleWithIdentifier
• bundleWithPath
• mainBundle
• allBundles
• allFrameworks

Getting a Bundled Class

• principalClass

Finding a Resource

• pathForResource
• pathsForResources
• resourcePath

Getting the Bundle Directory

• bundlePath

Getting Bundle Information

• builtInPlugInsPath
• bundleIdentifier
• executablePath
• infoDictionary
• objectForInfoDictionaryKey
• pathForAuxiliaryExecutable
• privateFrameworksPath
• sharedFrameworksPath
• sharedSupportPath

Managing Localized Resources

• localizedString
• localizedStringForKey

Loading a Bundle’s Code

• load
• isLoaded

Managing Localizations

• preferredLocalizations
• localizations
• developmentLocalization
• preferredLocalizations
• localizedInfoDictionary

Static Methods

allBundles

Returns an array of all the application’s nonframework bundles.

public static NSArray allBundles()

Discussion

This array includes the main bundle and all bundles that have been dynamically created but doesn’t contain any bundles that represent frameworks.

allFrameworks

Returns an array of all of the application’s bundles that represent frameworks.

public static NSArray allFrameworks()

Discussion

This array includes frameworks that are linked into an application when the application is built and bundles for frameworks that have been dynamically created. Only frameworks with one or more Objective-C classes in them are included.

bundleForClass

Returns the NSBundle that dynamically loaded aClass (a loadable bundle), the NSBundle for the framework in which aClass is defined, or the main bundle object if aClass was not dynamically loaded or is not defined in a framework.

public static NSBundle bundleForClass(Class aClass)

See Also

• mainBundle
• bundleWithPath

bundleWithIdentifier

Returns the previously created NSBundle instance that has the bundle identifier identifier.

public static NSBundle bundleWithIdentifier(String identifier)

Discussion

The instance must currently exist. Returns null if the requested bundle is not found.

bundleWithPath

Returns an NSBundle that corresponds to the specified directory fullPath or null if fullPath does not identify an accessible bundle directory.

public static NSBundle bundleWithPath(String fullPath)

Discussion

This method creates and initializes the returned object if there is no existing NSBundle associated with fullPath, in which case it returns the existing object. fullPath must be a full pathname for a directory; if it contains any symbolic links, they must be resolvable. If the directory doesn’t exist or the user doesn’t have access to it, this method returns null.

See Also

• mainBundle
• bundleForClass

localizedString

Returns the localized version of the string designated by key in the Localizable.strings file in the application’s main bundle.

public static String localizedString(String key)

Discussion

Returns key if it is not found in the file.

Returns the localized version of the string designated by key in the Localizable.strings file in the application’s main bundle.

public static String localizedString(String key, String comment)

Discussion

Returns key if it is not found in the file.

Returns the localized version of the string designated by key in table tableName in the application’s main bundle.

public static String localizedString(String key, String tableName, String comment)

Discussion

The argument tableName specifies the .strings file to search. Returns key if it is not found in the file.

Returns the localized version of the string designated by key in table tableName in bundle.

public static String localizedString(String key, String tableName, NSBundle bundle, String comment)

Discussion

The argument tableName specifies the .strings file to search. Returns key if it is not found in the file.

The comment arguments are not used by these methods. They are used only by the genstrings command-line tool, which creates .strings files by extracting the arguments of localizedString invocations in your source code. Use comment to document the purpose of each key in the .strings file.

See Also

• localizedStringForKey

mainBundle

Returns an NSBundle that corresponds to the directory where the application executable is located or null if this executable is not located in an accessible bundle directory.

public static NSBundle mainBundle()

Discussion

This method allocates and initializes the returned NSBundle if it doesn’t already exist.

In general, the main bundle corresponds to an application file package or application wrapper: a directory that bears the name of the application and is marked by a “.app” extension.

See Also

• bundleForClass
• bundleWithPath

preferredLocalizations

Returns the one or more localizations from the list localizationsArray that NSBundle prefers to use to locate resources based on the user’s preferences.

public static NSArray preferredLocalizations(NSArray localizationsArray)

Returns the localizations that NSBundle would prefer, given the specified bundle and user preference localizations.

public static NSArray preferredLocalizations(NSArray localizationsArray, NSArray preferencesArray)

Discussion

Use the argument localizationsArray to specify the supported localizations of the bundle and use preferencesArray to specify the user’s localization preferences. If you specify null for preferencesArray, this method uses the current user’s localization preferences. If none of the user-preferred localizations are available in the bundle, this method chooses one of the bundle localizations and returns it.

Availability

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

Instance Methods

builtInPlugInsPath

Returns the full pathname of the receiving bundle’s subdirectory containing plug-ins.

public String builtInPlugInsPath()

bundleIdentifier

Returns the receiver’s bundle identifier, which is defined by the CFBundleIdentifier key in the bundle’s information property list.

public String bundleIdentifier()

See Also

• infoDictionary

bundlePath

Returns the full pathname of the receiver’s bundle directory.

public String bundlePath()

developmentLocalization

Returns the localization used to create the bundle.

public String developmentLocalization()

Discussion

The returned localization corresponds to the value in the CFBundleDevelopmentRegion key of the bundle’s property list (Info.plist).

Availability

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

executablePath

Returns the full pathname of the receiving bundle’s executable file.

public String executablePath()

infoDictionary

Returns a dictionary that contains information about the receiver.

public NSDictionary infoDictionary()

Discussion

This information is extracted from the property list (Info.plist) associated with the bundle. The returned dictionary is empty if no Info.plist can be found. Common keys for accessing the values of the dictionary are CFBundleIdentifier, NSMainNibFile, and NSPrincipalClass.

See Also

• principalClass

isLoaded

Obtains information about the load status of a bundle.

public boolean isLoaded()

Discussion

Returns true if the bundle’s code is currently loaded; otherwise, returns false.

Availability

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

See Also

• load

load

Dynamically loads the bundle’s executable code into a running program, if the code has not already been loaded.

public boolean load()

Discussion

A bundle attempts to load its code—if it has any—only once. Returns true if the method successfully loads the bundle’s code or if the code has already been loaded. Returns false if the method fails to load the code. You don’t need to load a bundle’s executable code to search the bundle’s resources.

See Also

• isLoaded
• principalClass

localizations

Returns a list of all the localizations contained within the receiver’s bundle.

public NSArray localizations()

localizedInfoDictionary

Returns a dictionary with the keys from the bundle’s localized property list (InfoPList.strings).

public NSDictionary localizedInfoDictionary()

Discussion

This method uses the preferred localization for the current user when determining which resources to return. If the preferred localization is not available, this method chooses the most appropriate localization found in the bundle.

Availability

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

localizedStringForKey

Returns a localized version of the string designated by key in table tableName.

public String localizedStringForKey(String key, String value, String tableName)

Discussion

The argument tableName specifies the receiver’s string table to search. If tableName is null or is an empty string, the method attempts to use the table in Localizable.strings. The value argument specifies the value to return if key is null or if a localized string for key can’t be found in the table. If value is null or an empty string, and a localized string is not found in the table, the method returns key. If key and value are both null, the method returns the empty string. For more details about string localization and the specification of a .strings file, see “Working With Localized Strings.”

Using the user default NSShowNonLocalizedStrings, you can alter the behavior of localizedStringForKey to log a message when the method can’t find a localized string. If you set this default to true (in the global domain or in the application’s domain), then when the method can’t find a localized string in the table, it logs a message to the console and capitalizes key before returning it.

See Also

• pathForResource
• pathsForResources

objectForInfoDictionaryKey

Returns the value associated with key in the bundle’s property list (Info.plist).

public Object objectForInfoDictionaryKey(String key)

Discussion

Use of this method is preferred over other access methods because it returns the localized value of a key when one is available.

Availability

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

pathForAuxiliaryExecutable

Returns the full pathname of the executable executableName in the receiver’s bundle.

public String pathForAuxiliaryExecutable(String executableName)

pathForResource

Returns the full pathname for the resource identified by name with the specified file extension.

public String pathForResource(String name, String extension)

Discussion

If extension is an empty string or null, the returned pathname is the first one encountered where the file name exactly matches name.

The method first looks for a matching resource file in the nonlocalized resource directory (typically Resources) of the specified bundle. If a matching resource file is not found, it then looks in the top level of any available language-specific “.lproj” directories. (The search order for the language-specific directories corresponds to the user’s preferences.) It does not recurse through other subdirectories at any of these locations. For more details see “Bundles and Localization”.

Returns the full pathname for the resource identified by name, with the specified filename extension, and residing in the specific resource subdirectory specified by subpath; returns null if no matching resource file exists in the bundle.

public String pathForResource(String name, String extension, String subpath)

Discussion

If extension is an empty string or null, the returned pathname is the first one encountered where the file name exactly matches name.

The argument subpath specifies the name of a specific subdirectory to search within the current bundle’s general resource directory hierarchy. If subpath is null, this method searches the top-level nonlocalized resource directory (typically Resources) and the top-level of any language-specific directories. For example, suppose you have a modern bundle and specify @"Documentation" for the subpath parameter. This method would first look in the Contents/Resources/Documentation directory of the bundle, followed by the Documentation subdirectories of each language-specific .lproj directory. (The search order for the language-specific directories corresponds to the user’s preferences.) This method does not recurse through any other subdirectories at any of these locations. For more details see “Bundles and Localization”.

Returns the full pathname for the resource identified by name, with the specified filename extension, residing in the resource subdirectory specified by subpath, and limited to global resources and those associated with localizationName.

public String pathForResource(String name, String extension, String subpath, String localizationName)

Discussion

This method is equivalent to the three parameter version except that only nonlocalized resources and those in the language-specific .lproj directory specified by localizationName are searched.

See Also

• localizedStringForKey
• pathsForResources

pathsForResources

Returns an array containing the pathnames for all bundle resources having the specified filename extension and residing in the resource subdirectory specified by subpath; returns an empty array if no matching resource files are found.

public NSArray pathsForResources(String extension, String subpath)

Discussion

This method provides a means for dynamically discovering multiple bundle resources of the same type. If extension is an empty string or null, all bundle resources in the specified resource directory are returned.

The argument subpath specifies the name of a specific subdirectory to search within the current bundle’s resource directory hierarchy. If subpath is null, this method searches the top-level nonlocalized resource directory (typically Resources) and the top-level of any language-specific directories. For example, suppose you have a modern bundle and specify @"Documentation" for the subpath parameter. This method would first look in the Contents/Resources/Documentation directory of the bundle, followed by the Documentation subdirectories of each language-specific .lproj directory. (The search order for the language-specific directories corresponds to the user’s preferences.) This method does not recurse through any other subdirectories at any of these locations. For more details see “Bundles and Localization”.

Returns an array containing pathnames for all bundle resources having the specified filename extension, residing in the resource subdirectory specified by subpath, and limited to global resources and those associated with localizationName.

public NSArray pathsForResources(String extension, String subpath, String localizationName)

Discussion

This method is equivalent to the two parameter version except that only nonlocalized resources and those in the language-specific .lproj directory specified by localizationName are searched.

See Also

• localizedStringForKey

preferredLocalizations

Returns one or more localizations contained in the receiver’s bundle that the receiver uses to locate resources based on the user’s preferences.

public NSArray preferredLocalizations()

See Also

• preferredLocalizations
• localizations

principalClass

Returns the receiver’s principal class after ensuring that the code containing the definition of that class is dynamically loaded.

public Class principalClass()

Discussion

If the receiver encounters errors in loading or if it can’t find the executable code file in the bundle directory, it returns NIL. The principal class typically controls all the other classes in the bundle; it should mediate between those classes and classes external to the bundle. Classes (and categories) are loaded from just one file within the bundle directory. NSBundle obtains the name of the code file to load from the dictionary returned from infoDictionary, using “NSExecutable” as the key. The NSBundle determines its principal class in one of two ways:

• It first looks in its own information dictionary, which extracts the information encoded in the bundle’s property list (Info.plist). NSBundle obtains the principal class from the dictionary using the key NSPrincipalClass. For nonloadable bundles (applications and frameworks), if the principal class is not specified in the property list, the method returns NIL.

• If the principal class is not specified in the information dictionary, NSBundle identifies the first class loaded as the principal class. When several classes are linked into a dynamically loadable file, the default principal class is the first one listed on the ld command line. In the following example, Reporter would be the principal class:

ld -o myBundle -r Reporter.o NotePad.o QueryList.o

The order of classes in Xcode’s project browser is the order in which they will be linked. To designate the principal class, control-drag the file containing its implementation to the top of the list.

See Also

• infoDictionary
• load

privateFrameworksPath

Returns the full pathname of the receiving bundle’s subdirectory containing private frameworks.

public String privateFrameworksPath()

resourcePath

Returns the full pathname of the receiving bundle’s subdirectory containing resources.

public String resourcePath()

See Also

• bundlePath

sharedFrameworksPath

Returns the full pathname of the receiving bundle’s subdirectory containing shared frameworks.

public String sharedFrameworksPath()

sharedSupportPath

Returns the full pathname of the receiving bundle’s subdirectory containing shared support files.

public String sharedSupportPath()

Next Page > Hide TOC