Advanced Search
Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

< Previous PageNext Page >

User Resources in Applications

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 Resources directory 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 this section:

Application Help
Application Preferences
Document Resources

Application Help

In Mac OS X, the Help 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 Resource directory. 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 .lproj directories in the application bundle’s Resource directory. 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 (Info.plist) 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 Resources directory. If the key CFBundleHelpBookName is also present, and the string value of this key is the AppleTitle tag 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 help, including /Library/Documentation/Help and Library/Documentation/Help in 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.

Application Preferences

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 Library/Preferences directory 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.

Document Resources

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”:

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

Get information on Apple products.
Visit the Apple Store online or at retail locations.

Copyright © 2003 Apple Computer, Inc.
All rights reserved. | Terms of use | Privacy Notice