|< Previous PageNext Page >|
An application can come packaged with a variety of resources.
These resource can range from those that are closely tied to the
application’s executable, such as sound files and localized strings,
to more “external” resources such as application help, preferences,
and clip art. Resources are typically stored in the
of the application bundle.
However, application resources might not be stored in the application package for a variety of reasons. One reason for this separation is to make it possible for applications to run in a net-booted environment. Other reasons are to make the resources accessible in the file system and to separate resources provided by third-party contributors from those provided by the application’s developer. The following sections give information about the preferred locations for several types of resources.
In Mac OS X, the
Viewer application displays help information for applications as well
as more general help. (Help Viewer is part of the
Apple Help product.) You should store application
help files in the appropriate location in the application’s
You put the files in a help book, which is also the standard format
for help in Mac OS 9. You internationalize help books by localizing
their contents (text and images) and putting them in
in the application bundle’s
The text files must be HTML 3.2-compliant and otherwise conform
to the specification for Apple Help books. See Inside
Carbon: Providing User Assistance With Apple Help for instructions
on preparing and indexing help files.
The information property list (
of an application must contain a key, CFBundleHelpBookFolder, whose
value usually is a string that specifies the name of a help-book
directory in the application’s
If the key CFBundleHelpBookName is also present, and the string
value of this key is the
of the book, Help Viewer automatically handles the display of the
book when the user chooses the Help menu item. Note that the name
of each help-book directory, regardless of localization, must be
the same as the value for CFBundleHelpBookFolder—that is, directory
names should not be localized. Your application also can control
how help is opened and presented. The Apple Help API gives applications
several options related to help, such as opening a help book using
the title, opening a help file using the full directory path to
the file, and performing a search for a particular term or anchor.
For more information, see Inside Carbon: Providing User
Assistance With Apple Help.
Although Apple strongly recommends that you put help for an
application in an application bundle, you can also put application
help as well as more general help outside the application package.
Such help should go in one of the standard locations for third-party
a user’s home directory. When the user launches the Help Center
from the Finder, Help Viewer scans these locations and displays
a link to the application help. If your application help is installed
in one of the standard locations for help, you do not need to specify
any special key-value pairs in the application’s information property
list for Help Viewer to handle it.
Applications typically are installed with a default set of preferences that users can then change to suit their working habits. Part of any application’s code is devoted to displaying the range of preference options, accepting user choices, and writing these choices to the preferences system (see the Runtime Configuration programming topic for more information).
Your application should never write user-preference data inside
the application package. Preferences are stored in the
of the logged-in user’s account (local or network) or in the same
location in the machine-local or network domains. You should never
write preferences data directly to these locations; instead use
the APIs offered by Core Foundation Preference Services (CFPreferences)
or, for Cocoa applications, NSUserDefaults. Part of the reason for
the separation of user preferences from the application package
is to make it possible for applications to run in a net-booted environment.
Applications that are document-centric—word processors, spreadsheets, drawing applications, to name a few—often include resources such as templates, clip art, tutorials, and assistants. These items can either be packaged in the application bundle or in a location external to the application package. The rule of thumb for deciding where such a resource goes is similar to that for plug-ins and other loadable bundles (see “Applications and Loadable Bundles”:
SharedSupportdirectory of the application bundle.
As with loadable bundles, the application should provide some kind of resource browser that displays application resources (both internal and external to the package) and allows the user to select from them. The browser, however, should not divulge the inner structure of the application package.
|< Previous PageNext Page >|
Last updated: 2003-08-21