The Resource Manager: A Programmer's Guide
See Also: Macintosh User Interface Guidelines
Macintosh Operating System Reference Manual QuickDraw: A Programmer's Guide
The Event Manager: A Programmer's Guide The Window Manager: A Programmer's Guide The Font Manager: A Programmer's Guide The Menu Manager: A Programmer's Guide Macintosh Control Manager Programmer's Guide The Dialog Manager: A Programmer's Guide The Desk Manager: A Programmer's Guide Putting Together a Macintosh Application
Modification History: First Draft (ROM 2.0) Second Draft (ROM 4) Third Draft (ROM 7) Errata added
Caroline Caroline Caroline Caroline
/RMGR/RESOURCE
Rose 2/2/83 Rose 6/21/83 Rose 10/3/83 Rose 3/8/84
ABSTRACT Macintosh applications make use of many resources, such as menus, fonts, and icons. These resources are stored in resource files separately from the application code, for flexibility and ease of maintenance. This manual describes resource files and the Resource Manager routines.
Errata:
The low-order bit of the resource attribute byte is no lo~ger available for use by your application; it's now reserved for internal use by the Resource Manager.
There's a new function:
FUNCTION SizeResource (theResource: Handle) : INTEGER;
Given a handle to a resource, SizeResource returns the size of the resource in bytes. If the resource isn't in memory, the size is read from the resource file. If the given handle isn't a handle to a resource, SizeResource will return -1 and the ResError function will return the error code resNotFound.
TABLE OF CONTENTS
3 About This Manual
4 About the Resource Manager 6 Overview of Resource Files 8 Resource Specification
10
Resource References13 Using the Resource Manager 15 Resource Manager Routines
15 Initializing the Resource Manager 16 Opening and Closing Resource Files 17 Checking for Errors
18 Setting the Current Resource File 18 Getting Resource Types
19 Getting and Disposing of Resources 22 Getting Resource Information
23 Modifying Resources 28 Advanced Routines
29 Resources within Resources 31 Format of a Resource File
33 Notes for Assembly-Language Programmers 35 Summary of the Resource Manager
37 Summary of the Resource File Format 38 Glossary
Copyright (c) 1984 Apple Computer, Inc. All rights reserved. Distribution of this draft in limited quantities does not constitute publication.
ABOUT THIS MANUAL
This manual describes the Resource Manager, the part of the Macintosh User Interface Toolbox through which an application accesses various resources that it uses, such as menus, fonts, and icons.
***
Eventually it will become part of a large manual describing the entire Toolbox.
***
It discusses resource files, where resources are stored.Resources form the foundation of every Macintosh application; even the application's code is a resource. In a resource file, the resources used by the application are stored separately from the code for flexibility and ease of maintenance.
- You can use an existing program for creating and editing resource files, or write one of your own. These programs will call
Resource Manager routines.
- Usually you'll access resources indirectly through other Toolbox units, such as the Menu Manager and the Font Manager, which in turn call the Resource Manager to do the low-level resource operations. In some cases, you may need to call a Resource
Manager file-opening routine and possibly other routines to access resources directly. familiar with the Macintosh User Interface Guidelines, Lisa Pascal, and the Macintosh Operating System's Memory Manager. You should also be familiar with the following:
- The basic functions of the Finder, which are performed with the
10/3/83 Rose CONFIDENTIAL /RMGR/RESOURCE.2
section deals with resource references; you can skip it if you're only going to access resources through other Toolbox units.
Next, a section on using the Resource Manager introduces you to its routines and tells how they fit into the flow of your application.
This is followed by detailed descriptions of all Resource Manager procedures and functions, their parameters, calling protocol, effects, side effects, and so on.
There's a resource file associated with each application, containing the resources specific to that application; these resources include the application code itself. There's also a system resource file, which contains standard resources shared by all applications (also called system resources).
Your application's resource file is opened when the application starts up. When instructed to get a certain resource, the Resource Manager
You refer to a resource by passing the Resource Manager a resource specification, which consists of a type and either an 10 number or a name. Any resource type is valid, whether one of those reserved by the Toolbox (such as for menus and fonts) or a type created for use by your application. Given a resource specification, the Resource Manager will read the resource into memory and return a handle to it. the application uses, thus ensuring that those resources will accompany the application if you should copy it to a disk that has a different system resource file on it. References to system resources can be added or removed with Resource Manager routines.
Resource files are not limited to applications; anything stored in a file can have its own resources. For example, documents usually have resource files containing references to the system resources they use, such as fonts and icons. As in an application's resource file, these
10/3/83 Rose CONFIDENTIAL /RMGR/RESOURCE.2
were opened. Since the system resource file is opened when the Resource Manager is initialized, it's always searched last. Usually the search starts with the most recently opened resource file, but you can change it to start with a file that was opened earlier. (See Figure 1.)
Order of
opening:
Opened
last
Opened second
Opened
first
Document's re8Oll'Ce file
Appl