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.
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.
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.
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; if it belongs to a library, return the
bundle for that library; 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 to return a bundle for that library,
but 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!
Returns the bundle for the specified
identifier (see -bundleIdentifier) as
long as the bundle has already
been loaded. This never causes a bundle to be loaded.
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
.
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/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).
Returns an absolute path for a resource
name with the extension in the
specified bundlePath. See also
-pathForResource:ofType:inDirectory:
for more information on searching a bundle.
Returns an array of paths for all resources with
the specified extension and residing in
the bundlePath directory.
bundlePath can be any type of directory
structure, but typically it is used to search
for resources in a application or framework. For
example, one could search for tiff files in the
MyApp.app application using [NSBundle
pathsForResourcesOfType: @"tiff"
inDirectory: @"MyApp.app"]. It will search
in any Resources subdirectory inside
bundlePath as well as the main directory
for resource files. If extension is
nil or empty, all resources are
returned.
Returns subarray of given array containing those
localizations that are used to locate
resources given environment given user
preferences (which are used instead of looking
up the preferences of the current user).
Init the bundle for reading resources from
path. The MacOS-X documentation
says that the path must be a full
path to a directory on disk. However, it
(in MacOS-X) version 10.3 at least) actually accepts
relative paths too. The GNUstep behavior is
similar in that it accepts a relative
path, but GNUstep converts it to an
absolute path by referring to the
current working directory when the is initialised,
so an absolute path is then used and a
warning message is printed. On MacOS-X using
a bundle initialised with a relative path will
cause a crash if the current working directory is
changed between the point at which the bundle was
initialised and that at which it is used.
If path is nil or
can't be accessed, initWithPath: deallocates the
receiver and returns nil. If a
bundle for that path already existed, it
is returned in place of the receiver (and the receiver
is deallocated). If the
-bundleIdentifier
is not nil, and a bundle with the same
identifier already exists, the existing bundle
is returned in place of the receiver (and the receiver
is deallocated).
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:
.
Returns the value for the
key found in the strings file
tableName, or Localizable.strings if
tableName is nil.
If the user default
NSShowNonLocalizedStrings is set, the
value of the key will be
returned as an uppercase string rather than any
localized equivalent found. This can be useful
during development to check where a given string
in the UI is "coming from".
Returns an absolute path for a resource
name with the extension in
the specified bundlePath. Directories in the bundle
are searched in the following order:
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.
This method returns the same information as
-pathsForResourcesOfType:inDirectory:
except that only non-localized resources and resources that match the localization localizationName are returned. The GNUstep implementation places localised resources in the array before any non-localised resources.
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 or the specified class is not
found, the class returned is arbitrary, although it
is typically the first class compiled into the archive.
Warning the underscore at the start of the
name of this instance variable indicates that, even
though it is not technically private, it is
intended for internal use within the package, and
you should not use the variable in other code.
Warning the underscore at the start of the
name of this instance variable indicates that, even
though it is not technically private, it is
intended for internal use within the package, and
you should not use the variable in other code.
Warning the underscore at the start of the
name of this instance variable indicates that, even
though it is not technically private, it is
intended for internal use within the package, and
you should not use the variable in other code.
Warning the underscore at the start of the
name of this instance variable indicates that, even
though it is not technically private, it is
intended for internal use within the package, and
you should not use the variable in other code.
Warning the underscore at the start of the
name of this instance variable indicates that, even
though it is not technically private, it is
intended for internal use within the package, and
you should not use the variable in other code.
Warning the underscore at the start of the
name of this instance variable indicates that, even
though it is not technically private, it is
intended for internal use within the package, and
you should not use the variable in other code.
Warning the underscore at the start of the
name of this instance variable indicates that, even
though it is not technically private, it is
intended for internal use within the package, and
you should not use the variable in other code.
Warning the underscore at the start of the
name of this instance variable indicates that, even
though it is not technically private, it is
intended for internal use within the package, and
you should not use the variable in other code.
Warning the underscore at the start of the
name of this instance variable indicates that, even
though it is not technically private, it is
intended for internal use within the package, and
you should not use the variable in other code.
Availability: Base
Likely to be changed/moved/removed at 1.17.0
Returns the Android asset dir for the given
path if path is in main bundle
resources and the asset directory exists. The
returned object must be released using the
AAssetDir_close function.
Availability: Base
Likely to be changed/moved/removed at 1.17.0
Returns the Android asset for the given
path if path is in main bundle
resources and asset exists. Uses
`AASSET_MODE_UNKNOWN` to open the
asset if it exists. The returned object must be
released using the AAsset_close function.
Availability: Base
Likely to be changed/moved/removed at 1.17.0
Returns the Android asset for the given
path if path is in main bundle
resources and asset exists. Uses the given
mode to open the AAsset if it exists. The
returned object must be released using the
AAsset_close function.
Availability: Base
Likely to be changed/moved/removed at 1.17.0
This method is an experimental GNUstep extension, and
might change.
Return a bundle to access the resources for the
(static or shared) library libraryName
, with interface version interfaceVersion.
Resources for shared libraries are stored into
GNUSTEP_LIBRARY/Libraries/libraryName/Versions/interfaceVersion/Resources/; this method will search for the first such existing directory and return it.
libraryName should be the name of a
library without the lib prefix or any
extensions; interfaceVersion is
the interface version of the library (eg, it's 1.13
in libgnustep-base.so.1.13; see library.make on how to
control it).
This method exists to provide resource bundles for
libraries and has no particular relationship to
the library code itsself. The named library could be
a dynamic library linked in to the running program, a
static library (whose code may not even exist on
the host machine except where it is linked in to the
program), or even a library which is not linked
into the program at all (eg. where you want to share
resources provided for a library you do not
actually use).
The bundle for the library gnustep-base is a
special case... for this bundle the
-principalClass
method returns
NSObject
and the
-executablePath
method returns the path to the gnustep-base
dynamic library (if it can be found). As a
general rule, library bundles are not
guaranteed to return values for these
methods as the library may not exist on disk.