Up

NSBundle class reference

Authors

Adam Fedor (fedor@boulder.colorado.edu)
Mirko Viviani (mirko.viviani@rccr.cremona.it)
Nicola Pero (nicola@brainstorm.co.uk)

Version: 1.126

Date: 2003/10/08 14:27:10

Copyright: (C) 1995, 1997, 1999, 2001, 2002 Free Software Foundation, Inc.


Contents -

  1. Software documentation for the NSBundle class
  2. Software documentation for the NSBundle(GNUstep) category

Software documentation for the NSBundle class

NSBundle : NSObject

Declared in:
Foundation/NSBundle.h
Standards:

NSBundle provides methods for locating and handling application (and tool) resources at runtime. Resources includes any time of file that the application might need, such as images, nib (gorm or gmodel) files, localization files, and any other type of file that an application might need to use to function. Resources also include executable code, which can be dynamically linked into the application at runtime. These files and executable code are commonly put together into a directory called a bundle.

NSBundle knows how these bundles are organized and can search for files inside a bundle. NSBundle also handles locating the executable code, linking this in and initializing any classes that are located in the code. NSBundle also handles Frameworks, which are basically a bundle that contains a library archive. The organization of a framework is a little difference, but in most respects there is no difference between a bundle and a framework.

There is one special bundle, called the mainBundle, which is basically the application itself. The mainBundle is always loaded (of course), but you can still perform other operations on the mainBundle, such as searching for files, just as with any other bundle.

Method summary

allBundles

+ (NSArray*) allBundles;

Return an array enumerating all the bundles in the application. This does not include frameworks.
Returns an array of all the bundles which do not belong to frameworks.
This always contains the main bundle.


allFrameworks

+ (NSArray*) allFrameworks;

Return an array enumerating all the frameworks in the application. This does not include normal bundles.
Returns an array containing all the known bundles representing frameworks.


bundleForClass:

+ (NSBundle*) bundleForClass: (Class)aClass;

Return the bundle to which aClass belongs. If aClass was loaded from a bundle, return the bundle; if it belongs to a framework (either a framework linked into the application, or loaded dynamically), return the framework; in all other cases, return the main bundle.

Please note that GNUstep supports plain shared libraries, while the openstep standard, and other openstep-like systems, do not; the behaviour when aClass belongs to a plain shared library is at the moment still under investigation -- you should consider it undefined since it might be changed. :-)

Returns the bundle whose code contains the specified class.
NB: We will not find a class if the bundle has not been loaded yet!


bundleWithPath:

+ (NSBundle*) bundleWithPath: (NSString*)path;

Return a bundle for the path at path. If path doesn't exist or is not readable, return nil. If you want the main bundle of an application or a tool, it's better if you use +mainBundle .


mainBundle

+ (NSBundle*) mainBundle;

Return the bundle containing the resources for the executable. If the executable is an application, this is the main application bundle (the xxx.app directory); if the executable is a tool, this is a bundle 'naturally' associated with the tool: if the tool executable is xxx/Tools/ix86/linux-gnu/gnu-gnu-gnu/Control then the tool's main bundle directory is xxx/Tools/Resources/Control.

NB: traditionally tools didn't have a main bundle -- this is a recent GNUstep extension, but it's quite nice and it's here to stay.

The main bundle is where the application should put all of its resources, such as support files (images, html, rtf, txt,...), localization tables,.gorm (.nib) files, etc. gnustep-make (/ProjectCenter) allows you to easily specify the resource files to put in the main bundle when you create an application or a tool.

For an application, returns the main bundle of the application.
For a tool, returns the main bundle associated with the tool.

For an application, the structure is as follows -

The executable is Gomoku.app/ix86/linux-gnu/gnu-gnu-gnu/Gomoku and the main bundle directory is Gomoku.app/.

For a tool, the structure is as follows -

The executable is xxx/Tools/ix86/linux-gnu/gnu-gnu-gnu/Control and the main bundle directory is xxx/Tools/Resources/Control.

(when the tool has not yet been installed, it's similar - xxx/shared_obj/ix86/linux-gnu/gnu-gnu-gnu/Control and the main bundle directory is xxx/Resources/Control).

(For a flattened structure, the structure is the same without the ix86/linux-gnu/gnu-gnu-gnu directories).


pathForResource:ofType:inDirectory:

+ (NSString*) pathForResource: (NSString*)name ofType: (NSString*)ext inDirectory: (NSString*)bundlePath;

Returns an absolute path for a resource name with the extension ext in the specified bundlePath. See also -pathForResource:ofType:inDirectory: for more information on searching a bundle.


pathForResource:ofType:inDirectory:withVersion:

+ (NSString*) pathForResource: (NSString*)name ofType: (NSString*)ext inDirectory: (NSString*)bundlePath withVersion: (int)version;

This method has been depreciated. Version numbers were never implemented so this method behaves exactly like +pathForResource:ofType:inDirectory: .


pathsForResourcesOfType:inDirectory:

+ (NSArray*) pathsForResourcesOfType: (NSString*)extension inDirectory: (NSString*)bundlePath;

Description forthcoming.


preferredLocalizationsFromArray:

+ (NSArray*) preferredLocalizationsFromArray: (NSArray*)localizationsArray;

Description forthcoming.


preferredLocalizationsFromArray:forPreferences:

+ (NSArray*) preferredLocalizationsFromArray: (NSArray*)localizationsArray forPreferences: (NSArray*)preferencesArray;

Description forthcoming.


bundleIdentifier

- (NSString*) bundleIdentifier;

Returns the bundle identifier, as defined by the CFBundleIdentifier key in the infoDictionary


bundlePath

- (NSString*) bundlePath;

Return the path to the bundle - an absolute path.


bundleVersion

- (unsigned) bundleVersion;

Returns the bundle version.


classNamed:

- (Class) classNamed: (NSString*)className;

Returns the class in the bundle with the given name. If no class of this name exists in the bundle, then Nil is returned.


executablePath

- (NSString*) executablePath;

Returns the path to the executable code in the bundle


infoDictionary

- (NSDictionary*) infoDictionary;

Returns the info property list associated with the bundle.


initWithPath:

- (id) initWithPath: (NSString*)path;
This is a designated initialiser for the class.

Init the bundle for reading resources from path. path must be an absolute path to a directory on disk. If path is nil or doesn't exist, initWithPath: returns nil. If a bundle for that path already existed, it is returned in place of the receiver (and the receiver is deallocated).


isLoaded

- (BOOL) isLoaded;

Returns YES if the receiver's code is loaded, otherwise, returns NO.


load

- (BOOL) load;

Loads any executable code contained in the bundle into the application. Load will be called implicitly if any information about the bundle classes is requested, such as -principalClass or -classNamed: .


localizations

- (NSArray*) localizations;

Returns all the localizations in the bundle.


localizedInfoDictionary

- (NSDictionary*) localizedInfoDictionary;

Returns a localized info property list based on the preferred localization or the most appropriate localization if the preferred one cannot be found.


localizedStringForKey:value:table:

- (NSString*) localizedStringForKey: (NSString*)key value: (NSString*)value table: (NSString*)tableName;

Returns the value for the key found in the strings file tableName, or Localizable.strings if tableName is nil.


pathForResource:ofType:

- (NSString*) pathForResource: (NSString*)name ofType: (NSString*)ext;

Returns an absolute path for a resource name with the extension ext in the receivers bundle path. See -pathForResource:ofType:inDirectory: .


pathForResource:ofType:inDirectory:

- (NSString*) pathForResource: (NSString*)name ofType: (NSString*)ext inDirectory: (NSString*)bundlePath;

Returns an absolute path for a resource name with the extension ext in the specified bundlePath. Directories in the bundle are searched in the following order:

     root path/Resources/bundlePath
     root path/Resources/bundlePath/"language.lproj"
     root path/bundlePath
     root path/bundlePath/"language.lproj"
   

where lanuage.lproj can be any localized language directory inside the bundle.

If ext is nil or empty, then the first file with name and any extension is returned.


pathForResource:ofType:inDirectory:forLocalization:

- (NSString*) pathForResource: (NSString*)name ofType: (NSString*)ext inDirectory: (NSString*)bundlePath forLocalization: (NSString*)localizationName;

Description forthcoming.


pathsForResourcesOfType:inDirectory:

- (NSArray*) pathsForResourcesOfType: (NSString*)extension inDirectory: (NSString*)bundlePath;

Returns an array of paths for all resources with the specified extension and residing in the bundlePath directory. If extension is nil or empty, all bundle resources are returned.


pathsForResourcesOfType:inDirectory:forLocalization:

- (NSArray*) pathsForResourcesOfType: (NSString*)extension inDirectory: (NSString*)bundlePath forLocalization: (NSString*)localizationName;

Description forthcoming.


preferredLocalizations

- (NSArray*) preferredLocalizations;

Returns the list of localizations that the bundle uses to search for information. This is based on the user's preferences.


principalClass

- (Class) principalClass;

Returns the principal class of the bundle. This is the class specified by the NSPrincipalClass key in the Info-gnustep property list contained in the bundle. If this key is not found, the class returned is arbitrary, although it is typically the first class compiled into the archive.


resourcePath

- (NSString*) resourcePath;

Returns the absolute path to the resources directory of the bundle.


setBundleVersion:

- (void) setBundleVersion: (unsigned)version;

Set the bundle version


Software documentation for the NSBundle(GNUstep) category

NSBundle(GNUstep)

Declared in:
Foundation/NSBundle.h
Standards:

Description forthcoming.

Method summary

_absolutePathOfExecutable:

+ (NSString*) _absolutePathOfExecutable: (NSString*)path;

Warning the underscore at the start of the name of this method indicates that it is private, for internal use only, and you should not use the method in your code.


_gnustep_target_cpu

+ (NSString*) _gnustep_target_cpu;

Warning the underscore at the start of the name of this method indicates that it is private, for internal use only, and you should not use the method in your code.


_gnustep_target_dir

+ (NSString*) _gnustep_target_dir;

Warning the underscore at the start of the name of this method indicates that it is private, for internal use only, and you should not use the method in your code.


_gnustep_target_os

+ (NSString*) _gnustep_target_os;

Warning the underscore at the start of the name of this method indicates that it is private, for internal use only, and you should not use the method in your code.


_library_combo

+ (NSString*) _library_combo;

Warning the underscore at the start of the name of this method indicates that it is private, for internal use only, and you should not use the method in your code.


bundleForLibrary:

+ (NSBundle*) bundleForLibrary: (NSString*)libraryName;

This method is an experimental GNUstep extension, and might change. At the moment, search on the standard GNUstep directories (starting from GNUSTEP_USER_ROOT, and going on to GNUSTEP_SYSTEM_ROOT) for a directory Libraries/Resources/'libraryName'/.
Return a bundle which accesses the first existing directory from the list GNUSTEP_USER_ROOT/Libraries/Resources/libraryName/ GNUSTEP_NETWORK_ROOT/Libraries/Resources/libraryName/ GNUSTEP_LOCAL_ROOT/Libraries/Resources/libraryName/ GNUSTEP_SYSTEM_ROOT/Libraries/Resources/libraryName/


gnustepBundle

+ (NSBundle*) gnustepBundle;

Depreciated. Use +bundleForLibrary: instead.


pathForGNUstepResource:ofType:inDirectory:

+ (NSString*) pathForGNUstepResource: (NSString*)name ofType: (NSString*)ext inDirectory: (NSString*)bundlePath;

Depreciated. Use +pathForLibraryResource:ofType:inDirectory: or +bundleForLibrary: instead.


pathForLibraryResource:ofType:inDirectory:

+ (NSString*) pathForLibraryResource: (NSString*)name ofType: (NSString*)ext inDirectory: (NSString*)bundlePath;

Find a resource in the "Library" directory



Up