Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 1 - Introduction to the Macintosh Toolbox / Overview of the Macintosh Toolbox

Resources

Resources are basic elements of every Macintosh application. By defining descriptions of menus, windows, controls, dialog boxes, sounds, fonts, and icons in resources, you can make these and other elements easier to create and manage. Using resources also eases translation of user interface elements into other languages.

A resource is any data stored according to a defined structure in the resource fork of
a file; the data in a resource is interpreted according to its resource type. You usually create resources using a resource compiler or resource editor. This book shows resources in Rez format; Rez is a resource compiler provided with the Macintosh Programmer's Workshop (available from APDA). You can also use other resource tools, such as ResEdit (also available from APDA), to create the resources for your application.

Most of the managers described in this book use the Resource Manager to read resources for you. For example, you can use the Menu Manager, Window Manager, Dialog Manager, and Control Manager to read descriptions of your application's menus, windows, dialog boxes, and controls from resources. These managers all interpret a resource's data accordingly once it is read into memory. While you'll typically use these managers to access resources for you, you can also directly use the Resource Manager
to read and write resources.

The chapter "Resource Manager" in Inside Macintosh: More Macintosh Toolbox describes the Resource Manager in detail. However, to help you understand how the Menu Manager, Window Manager, Dialog Manager, and Control Manager use resources, this section gives a brief overview of resources and provides a general introduction to the Resource Manager.

Macintosh system software treats a file as a named, ordered sequence of bytes stored
on a Macintosh volume and divided into two forks, the data fork and the resource fork. The data fork contains data that usually corresponds to data created by the user; the application creating the file can store and interpret the data in the data fork in whatever manner is appropriate. The resource fork of a file consists of a resource map and the resources themselves.

When you write data to a file, you write to either the file's resource fork or its data fork. You typically read from and write to a file's data fork using File Manager routines and read from and write to a file's resource fork using Resource Manager routines.

You typically store as resources data that has a defined structure--such as icons and sounds--and descriptions of menus, controls, dialog boxes, and windows. When you create a resource, you assign it a resource type and resource ID. A resource type is a sequence of four characters that uniquely identifies a specific type of resource, and a resource ID identifies by number a specific resource within that type. (You can also
use a resource name in place of a resource ID to identify a particular resource within a resource type.) For example, to create a description of a menu in a resource, you create
a resource of type 'MENU' and give it a resource ID or resource name that is unique from any other 'MENU' resources that you have defined. Some resources have restrictions on the numbers you can use for resource IDs; in general, numbers 128 through 32767 are available for your use.

System software defines a number of standard resource types, such as 'ALRT', 'CNTL', 'CODE', 'DITL', 'DLOG', 'FONT', 'ICN#', 'ICON', 'MBAR', 'MENU', 'STR ', 'STR#', and 'WIND'. You can use these resource types to define their corresponding elements (for example, use a 'WIND' resource to define a window). You can also create your own resource types if your application needs resources other than the standard resource types defined by the system software.

The Resource Manager does not interpret the format of an individual resource type. When you request a resource of a particular type with a given resource ID, the Resource Manager looks for the specified resource and, if it finds it, reads the resource into memory and returns a handle to it. Your application or other system software routines can use the Resource Manager to read resources into memory. For example, when you use the Window Manager to read a description of a window from a 'WIND' resource, the Window Manager uses the Resource Manager to read the resource into memory. Once the resource is in memory, the Window Manager interprets the resource's data and creates a window with the characteristics described by the resource.

System software stores certain resources used by the system software in the System
file. Although many of these resources are used only by the system software, your application can access some of these resources if needed. For example, the standard images for the I-beam and wristwatch cursors are stored as resources of type 'CURS'
in the System file. You can use these resources to change the appearance of the cursor used by your application.

Occasionally you may need to write resources to the resource fork of a file. For example, if your application saves the last position and size of a window (as determined by
the user), you can store this information in the resource fork of the document in a resource defined by your application. The next time the user opens the document, your application can read the location saved in this resource and position the document accordingly.

You typically store the resources specific to your application, such as descriptions of its menus, windows, controls, and dialog boxes, in the resource fork of your application. You can store resources specific to a document created by your application in the resource fork of the document file.

The resource map in the resource fork of a file contains entries that provide the location of each resource in the resource fork. When the Resource Manager opens the resource fork of a file, it reads the resource map into memory. As the Resource Manager reads resources into memory, it replaces their entries in the resource map with handles to their data in memory. The Resource Manager always searches the resource map in memory, not the resource map of the resource fork on disk, when it searches for a resource. If a requested resource is in memory, the Resource Manager uses the resource in memory; otherwise it reads the resource from the resource fork on disk into memory.

Once the Resource Manager has opened a resource fork and read its resource map into memory, it keeps the map in memory until the file is closed. You can specify that a resource be read into memory immediately when the Resource Manager opens a file's resource fork, or you can specify that the Resource Manager read it into memory only when needed. The Resource Manager stores resources from resource forks opened by your application in relocatable blocks in your application's heap. You can also specify whether the Resource Manager should purge a resource from memory in order to make room in memory for other data. If you specify that a resource is purgeable, you need to use the Resource Manager to make sure the resource is in memory before accessing it through its resource handle.

When a user opens your application, system software opens your application's resource fork. When your application opens a file, your application typically opens both the
file's data fork and the file's resource fork. When your application requests a resource from the Resource Manager, the Resource Manager follows a specific search order.
(If necessary, your application can change the search order using Resource Manager routines.) The Resource Manager normally looks first for the resource in the resource fork of the last file that your application opened. So, if your application has a single file open, the Resource Manager looks first in that file's resource fork. If the Resource Manager doesn't find the resource there, it continues to search each resource fork open to your application in the reverse order that the files were opened. After looking in the resource forks of files your application has opened, the Resource Manager searches your application's resource fork. If it doesn't find the resource there, it searches the resource fork of the System file.

This search path allows your application to use resources defined in the System file, to override resources defined in the System file, to share resources between files by using resources stored in your application's resource fork, and to override your application- defined resources and use resources specific to a document.

A Macintosh file always contains both a resource fork and a data fork, although one
or both of those forks can be empty. Document files typically contain the document's data in the data fork and any document-specific resources--such as preference settings, window location, and the document icon--in the resource fork. The resource fork
of an application typically includes resources that describe the application's menus, windows, controls, dialog boxes, and icons, as well as the code itself, which is also stored as a resource.

Whether you store data in the data fork or the resource fork of a document file depends largely on whether you can structure that data in a useful manner as a resource.
For example, it's often convenient to store document-specific settings, such as the document's previous window size and location, as a resource in the document's resource fork. Data that is likely to be edited by the user is usually stored in the data fork of
a document.

A resource fork can contain at most 2700 resources. The Resource Manager uses a linear search when searching a resource fork's resource types and resource IDs. In general, you should not create more than 500 resources of the same type in any one resource fork.

Inside Macintosh: More Macintosh Toolbox describes resources and the use of the Resource Manager in more detail. For information on writing data to a file's data fork, see Inside Macintosh: Files.