All About Resource Editors

By Joel West, MacTutor Contributing Editor

Choosing and Using a Resource Editor

This article is the first of several articles on using resources when developing a Macintosh application. This month, we’ll look at the structure of resources and how the two resource editors available from Apple can be used to free you from RMaker.

If you’re just getting started, you can also use the resource editors to understand how a typical application is put together. The study of actual applications can provide a valuable education in Macintosh development, much as an MBA student studies the case histories of existing businesses.

The article will describe the general structure of resources, and how to choose between the various resource-building tools available to the developer.

Inescapable Resources

If you’ve gone very far with program development on the Mac, then by now you know it’s impossible to write a program of any size without a thorough understanding of resources. Although some might consider them a needless extra step of in program development, they do make it easier to make certain types of changes in a program -- particularly now, two years after the Mac’s introduction, when there are two complete Resource Editors available. One of these editors can, in fact, be adapted to edit just about any sort of data structure.

The proper use of resources also provides a notable benefit over traditional approaches when dealing with the international marketplace. If all the text seen by a user is contained in the application’s resources, then your program can be translated to run in a foreign country -- without making your source code available to someone else.

This article is inteded to provided a brief introduction to resources. The standard reference on the topic is, of course, Inside Macintosh, under the chapter “The Resource Manager: A Programmer’s Guide.” From a survey I’ve taken of developers, it usually takes several readings before most of the details sink in.

Once you understand the general resource concepts, you still don’t know how to use specific resources. They’re described in the respective chapters descripting the corresponding Toolbox libraries, such as the Menu Manager, Font Manager, and so on.

The Structure of Resources

One of the most controversial aspect of the Macintosh design is that every file contains two “forks”, or sections: the data fork and the resource fork. I say controversial, because most files you’ll find on your Mac normally have only one component or the other. For example, the MacWrite file that contains this article has only a data fork; the MacWrite application, the System and the Finder all have only resources. (Other computers have the same sorts of files, but there’s usually a bit somewhere that indicates whether the file has program or data.)

One of the few examples I know of with both data and resources is a MacTerminal document. You can access the data received in a terminal session by editing the data fork with MacWrite. Or, you can reclaim the terminal’s configuration (‘CNFG’) from MacTerminal in the resource fork. For most purposes, you can assume that the data fork contains unformatted ASCII text, which is the most common, but by no means only, situation.

Resources, however, should not just be considered a fancy name for what you’ll find in the .EXE file of your IBM PC (sorry) or the a.out of your UNIX system. Resources are the relational database of Macintosh systems programming: not only do they provide a way of storing information necessary to run a program, but they also provide a standard hierarchy for that information.

Every resource has three identifiers that serve to make it unique. The first idenitifer (or “key”, if you want a database talisman) is, of course, resource file that contains the resource. Traditional repositories of these are the System file and individual applications. The Resource Manager does allow combining resources from several files, as will be discussed later.

The second identifier is a four-character ASCII resource type. Normally, this consists of four capital letters, as in ‘MENU’, ‘WIND’, and ‘CNTL’ for menus, windows, and controls, respectively. However, a few resource names end in a space or number sign, such as ‘STR ’ and ‘STR#’, which refer to strings and a list of strings.

Third, each resource within a given type and file must have a unique 16-bit integer, referred to as the resource ID. In most cases, resources that you assign should be numbered between 128 and 32,767. Resources in the range 0 to 127 are reserved for system (Apple-defined) usages; negative id’s are generally used by resources that are nested within other resources, such as in a desk accessory.

Alternately, each resource of a given type can have a specific name, as for a type font. Although the resource id must always be unique, a unique resource name can be used as the third key. Usually the id or name is used to reference a given type, but not both.

In most cases, the layout of all resources of a given type will follow the same explicit set of rules, no matter what file or id they have. Unfortunately, there are a few types that do not, such as ‘PREC’ and ‘INTL’.

The overall structure of the resource fork of a file is represented by Figure 1. Each resource fork contains both the actual resource data, and the resource map, which is nothing more than a index to where each resource is located. As suggested by the illustration, each resource of a given type and id (or name) can be found by tracing the links from the beginning of the resource map. The links are represented as an offset within the resource map (2 bytes) or within the resource data (3 bytes), depending on where the referenced data lies.

Not shown are the resources which reference other resources, usually by resource ID and an implied resource type. For example, alert and dialog template resources (used by the dialog manager routines) will normally reference a corresponding item list. Item lists can, in turn, reference control, icons, or QuickDraw pictures. And if you want a non-standard control, menu, or window, you would reference a ‘CDEF’, ‘MDEF’ or ‘WDEF’ resource from within a ‘CNTL’, ‘MENU’ or ’WIND’ resource.

The custom is that related resources (e.g., dialogs and item lists) are numbered the same, but this is only a convention, not a requirement of the resource manager. It does, however, make it easier for you (or a foreign marketeer) to modify national or personal preferences.

Fig. 1 Resource Overview

Accessing Resources Within a Program

Normally, a particular resource will be referenced through the appropriate manager routine, e.g., the Menu Manager, Window Manager, or Control Manager. Most such routines only require the resource ID, since they already know the resource type to look for when searching the open resource files of your application.

However, you can always get at an arbitrary resource on a particular file as follows (all examples are given for Megamax C):

resfilno = OpenResFile("System");
if (resfilno >= 0)
 reshandle = GetResource(RT_ICON, rsrcid);
else
 MyQuit(ResError());

NOTE: If you’re just getting started with resources, or you’ve recently switched languages, be aware that there are two possible approaches for passing resource type arguments. For those using assembler, some C’s, and languages that closely follow Lisa Pascal, the resource type will usually be a 32-bit word with the 4 ASCII characters stored high-to-low. Such types can be given in hexadecimal, although some compilers allow you to show it as a character string.

However, most languages define a series of 2 or more characters as a string, which is a 32-bit pointer to the 4 characters. In Megamax C, for example, any resource type argument is passed as a string (pointer), and the interface routine fetches the referenced ASCII word before calling the toolbox.

To tell the two forms apart, look at the menu setup routine of the skeleton application supplied by the vendor. It will probably contain a statement to merge desk accessories into the Apple menu that looks like one of the following:

AddResMenu(myMenus[appleMenu], 'DRVR');
AddResMenu(myMenus[appleMenu], 0x44525652);
AddResMenu(myMenus[appleMenu], "DRVR");

The form used by the second argument to AddResMenu is either by value (first two forms) or by pointer (third form). This is the same form you must use in any other routine that expects a resource type. To make it easy to switch between different programming systems, you should use a symbolic definition, such as the corresponding C declarations:

#define RT_ICON 'ICON'
#define RT_CON 0x49434F4E
#define RT_ICON  "ICON"

Resource Attributes

We’ve already seen how every resource has:

• Four-letter resource type

• 16-bit integer resource id

• (Optional) resource name, as a Pascal string

Each resource also has a 16-bit word holding resource attributes. However, only the low-order byte is used; six of these bits are used as boolean flags, as shown by their symbolic names in Figure 2.

For a new application, you would typically define only three of these attributes. If resPreload is set, the resource to be read into memory when your program launches; you would normally want all your menus declared this way, for example. The resPurgeable flag allows the resource to be purged (removed) any time more memory is needed, while resLocked prevents the resource from being relocated or purged, thus avoiding handle-dereferencing memory problems.

You can gain the resource attribute for any resource you have a handle for by a simple call:

attrs = GetResAttrs(reshandle);

Although the resource type remains fixed, you can change the resource ID, name, or attributes while your program is running. A good example of this would be the

SetResInfo(reshandle, ID, name);
SetResAttrs(reshandle, attrs)

You should distinguish between the original copy of the resource in the resource file, and the copy that is currently in memory. Setting (or resetting) most of these attributes will only have an effect once the changed resource has been written to disk and then re-read. (The exception is resProtected, which takes effect immediately). Instead, if you need to protect the copy of the resource in memory, you should use the customary memory manager routines HLock and HNoPurge.

The one attribute you don’t change directly is resChanged. Instead, you call ChangedResource and then the resource manager will assure that the modified resource is written out at some point. To be on the safe side, you may want to force the changes to be written immediately:

ChangedResource(reshandle);
WriteResource(reshandle);
UpdateResFile(resfilno);

If you want to change the length of the resource -- such as to lengthen a string field -- there is no easy way to do it. Instead, you have the create a new copy of the resource and remove the old copy:

newresh = NewHandle(newsize);
BlockMove(*reshandle, *newresh, oldsize);
/* Now put the new data in ...
*/
RmveResource(reshandle);
AddResource(newresh, restype, ID, name);
DisposHandle(reshandle);
reshandle = newresh;

If you’re just getting started, you should note that it’s generally very dangerous to pass a dereferenced handle as an argument, because a heap compaction would move the blocks pointed to by the pointer. However, if you have“Trap List”, published by Apple, you can look up BlockMove and see that it doesn’t call any memory manager routines, so there’s no need to HLock the two handles.

Resource-Building Tools

Any professional development system for the Mac will be shipped with some sort of resource compiler, such as the RMaker of the MDS system, which is also shipped on several other systems. It takes the definition of a resource in a line-oriented, symbolic form to produce the binary version stored in the resource fork of a file.

A complete description of the Lisa Pascal resource compiler is contained in the Inside Macintosh chapter “Putting Together a Macintosh Application.” The input format for other compilers is usually somewhat different, so double-check the manual that came with your system, after reading Inside Mac. Also, some resource types recognized by the Lisa Workshop compiler must be simulated under other compilers, as discussed later.

The standard resource compiler format consists of:

• Resource type

• Resource name (optional)

• Resource ID

• Resource attributes

• Type-specific resource data

For example, an ICON is a 32-by-32 pixel resource that used for symbols, such as the disk shown when you swap disks (if you own, or ever owned a 128K Mac, this should be a familiar sight by now!)

To build an Icon with a resource compiler, you would define the bit map as a pattern, typically a series of 32 integers, each 32 bits wide. Thus, an icon might be defined by the following (the numbers are shown four per line for compactness):

Type ICON
  ,0(32);; no name, ID=0, purgeable at any time
FFFFFFFF807FFFFF 807FFFFF 807FFFFF
807FFFFF807F807F 887E001F 887C000F
88781C0780781C07 80701C03 80701C03
80701C0380701C03 80701C03 80701C03
80701C0380701C03 80701C03 80701C03
87F0000381F01C03 81F01C07 81F01C07
81F0000F81E0001F 8F80007F 81FFFFFF
81FFFFFF81FFFFFF 81FFFFFF FFFFFFFF

Development is made easier, however, if you have one of two resource editors written at Apple and distributed through various informal channels. You should not confuse the two, which have differing strengths and design points.

REdit was written by Gerard Schutten in Apple’s Netherlands office for translating programs to foreign languages. Release 1.0, dated March 1985, was given to developers in the Software Supplement of July (“May”) 1985, and is contained on the MacTutor Utility Disk No.1.

The Jack-in-the-Box icon ResEdit was prototyped by Rony Sebok and Steve Capps in Cupertino and is now being completed by Gene Pope of Apple. It has been floating around in pre-release form for a year and a half now. At press time, the latest version available was Release 1.0D7 from the March 1986 (officially, “December 1985”) Software Supplement. ($25 from Apple). Most of the versions released thus far have a tendency to crash, some more than others. Whichever ResEdit you use, be sure to take Apple’s advice, and don’t attempt to edit any file that you haven’t backed up.

Choosing a Resource Editor

How do you choose between the resource editors? Figure 3 shows a list of the standard resource types, and a subjective evaluation of which is best for each type.

REdit is oriented towards customizing an application for a particular country. As a result, it is designed for use by quiche-eating marketting types, rather than Real Programmers. REdit makes easy for just about anyone to modify certain types of resources by changing resources likely to contain text or other nationalisms.

However, some of its idiot-proof features can get in the way. Perhaps the most annoying is that you can’t open a resource file that’s in use, in case you might want to modify it. This means that even if you just want to look at a resource in the System file, you have to load a spare disk, because you’re not allowed to open the boot system.

REdit also contains a built-in decompiler for those types, which builds a file compatible with the Lisa Workshop resource compiler. You can use this to study the structure of an application, for further modification or imitation.

On the other hand, ResEdit was written for use by programmers. It is designed to completely replace the use of a resource compiler and, in its current edition, does just that.

For most types, ResEdit presents data comparable to the line-oriented RMaker format, displayed in a series of editable text fields within a dialog box. Cursors, fonts, icons and patterns can be edited in a “Fat Bits” format, while alerts, dialogs and windows can be sized and positioned either graphically or through a dialog box.

Note that for most types where you have a choice, REdit is preferred, primarily because it has a cleaner graphical interface. For example, REdit uses graphical interface to set size and position of the dialog box and allows you to easily go through all the items in Dialog ITem List (‘DITL’). Each item can be resized or repositioned both graphically or through a dialog box.

One futher area where REdit has an advantage is in text fields, both in item lists and in string resources. REdit allows 6 lines of data, while ResEdit allows 3 lines for item lists, and 2 lines for ‘STR ’ and ‘STR#’ resources. This limitation is particularly annoying when editing alerts, such as “Printing in progress. To cancel printing ”

On the other hand, ResEdit allows you to set the alert-specific parameters that determine whether a particular alert will beep or display a window. And it also gives you more flexibility in adding new items or changing the item types for dialog item lists.

Overall, once you’ve set up your dialogs and alerts, you’ll probably find yourself using ResEdit more often, because it supports the common resource types. I have one development floppy with the public domain RamStart set to load the system, finder, ResEdit and a text editor.

Using the Resource Editors

To get a feel for the structure of an application, grab a resource editor and a spare boot disk. There are more resource examples in a typical boot disk than in the 1800+ pages of Inside Macintosh.

Once you’ve booted the editor, use Open in the File menu to open the System file. (If you’re using REdit, it CAN’T be the one on the boot volume). This will create a window with a list of resource types, in text for ResEdit, and iconic for REdit. In the case of REdit, unknown types are shown by a question mark.

Open the type ‘ICON’ and you will get a list of resources of that type. If you’ve used ResEdit, your choices will resemble the window shown in Figure 4.

Double-click the icon resource that you want to edit. Both resource editors will open a new window and offer a Fat Bits-style display, such as shown in Figure 5. If you make any changes, they will be reflected the next time you save the resource file.

Once you select a specific resource, the Get Info menu option of ResEdit allows you to change the resource ID, resource name, and resource attributes. Be careful not to set the resource ID to the same value as other resources of the same type. A unique ID will be automatically assigned, when you create a new resource.

Both resource editors know how to edit only certain types of resources. Unknown types will be shown as a series of bytes in hexadecimal for ResEdit, and in hex and ASCII for REdit. You can also force this format in ResEdit for any resource by using Open general.

Resource Type vs. Creator

Apple has a list of standard resource types that should be used only for their official purpose, and also reserves names containing only lower-case letters. Most of the standard types are shown in Figure 4; for more information, see Macintosh Technical Note #32, available from Apple.

Other than these restrictions, you’re free to invent your own resource type names for whatever purpose you want. For example, you must invent a new type for an application’s signature. This is a four-letter code that MUST be unique across all the disks currently loaded on your Mac. For commercial software, this unique signature is assigned by Apple; otherwise, just watch out for duplicates.

Normally, the signature will show up in two places:

• In the creator field of the application and any documents it creates;

• As a resource in the application.

Figure 6 shows the relationship of the fields for MacWrite, a representative application. There are three types of files that can be found with a creator of ‘MACA’, while each has a different file type.

There will always be at least one file with the creator matching the signature -- the one with file type ‘APPL’,the MacWrite application itself. Note that only the application contains the ‘MACA’ resource; by convention, this resource contains a version string.

The other two files with the creator ‘MACA’ are documents used by MacWrite. The two files are text-only documents (type ‘TEXT’) and documents with MacWrite formatting controls (type ‘WORD’). The Get Info item of ResEdit allows you to specify both creator and file type fields. When using RMaker, the first eight characters of the second signficant (non-comment) line give the file type (‘APPL’) and creator (‘MACA’).

The Bundled Solution

All of the information for all three file types is obtained from the application -- such as the icon for the corresponding type, and which application to run when the document is opened. This relationship is defined by a ‘BNDL’ resource, which in turn references other resource types.can be edited using ResEdit.

Although bundling would normally be the last step of developing an application, building a bundle adds a satisfying flair to your prototype application, and it’s quite easy to do with ResEdit. The process of bundling is described in the “Structure of a Macintosh Application” chapter of Inside Macintosh, but we can use ResEdit and MacWrite to study an actual example.

Figure 7 shows the MacWrite bundle with the actual ResEdit prompts underlined, and the corresponding fields to the prompts. For ease of understanding, the (icon and file type) values referenced by the bundles are shown, although they’re not actually included in the bundle. Instead, the icons are contained in a ‘ICN#’ referenced by the bundle, while the ‘FREF’ contains the corresponding file types for these icons.

The figure also shows two conflicting conventions for describing resource lists. “numTypes” is the number of resource types in the bundle, while “# of this type” is one less than the number.

You can copy your bundle from this, because most will be identical to this. The only exception is that your applications might have only one document type, so that the “# of this type” would then be 1.

Special-purpose Resource Tools

In addition to the resource compiler and two general-use resource editors, there are also two resource editors designed for specific purposes.

One is designed for one of the more unusual and important resource types: ’INTL’. This resource type is used to isolate the names of weekdays and months, the currency symbol, date order, and other country-specific information.

There are only two resources of this type, which are contained in the System file and have reserved ID’s of 0 and 1.

Unfortunately, the format of these two resources is different. However, REdit can edit these two resources, because it has been designed to treat the two ID’s differently. This is an excellent way to see what differences are supported, if you have access to a System file customized for another country.

This assumes, however, you know what the appropriate values are for the country in question. For major countries, the easiest way to get these values is with the Localizer utility. It sets the international resources in the System file for the United Kingdom, France, Spain, Italy, Germany, Sweden, Belgium and the Netherlands. Note that although the language is the same, the U.K. and Ireland formats are different from the U.S., primarily in the currency and order of the date.

For the New World, Localizer supports Quebec (French-speaking Canada), while lumping English-speaking Canadians in with the U.S. and Latin America with Spain. At the same time, it can also change the keyboard mapping to target the specific countries, although it obviously won’t do much for the keycap labels. Localizer was included on the “May 85” edition of the Software Supplement.

There’s also a resource editor designed specifically forediting dialogs called Dialog Creator, developed by Michael Bayer of Apple Canada. It allows you to create and modify a dialog specification, including adding new items and changing existing items. It also allows you to see and edit the definition in RMaker source form, as well as saving the compiled resources to the application. The original April 1985 version was limited to only 25 items per dialog, but the version from the “December 1985” supplement supports 60 items, a realistic limit. On the other hand, Dialog Creator has a modal approach that takes a little getting used to.

Conclusion

The handyman’s motto of “the right tool for any job” applies to the building of resources. Each of the tools has an application (excuse the pun) to the construction of a Macintosh program.

Using a resource compiler and its line-oriented descriptive file provides the best permanent documentation. It also allows you to use published program examples as the starting point, such as those provided in MacTutor.

However, many developers find that the Edit-Compile-Test process is too slow for developing new applications. Instead, a resource editor, particularly one that provides a graphical interface, allows you to see the results of the changes as they’re being made.

ResEdit is the best for this purpose. However, keep both REdit and Dialog Creator, particularly if you’re working on dialog boxes.

Commonly used by Applications

Code Description Use (or example) ResEdit REdit

ALRT Alert box Alert template yes* yes

BNDL Bundle Buiding application yes

CODE Program User application -- --

DITL Item list Dialogs, alerts yes yes

DLOG Dialog box Dialog template yes yes

FREF File reference to related document yes

ICN# Icon and mask Application, docs yes yes

MENU Menu lists Menus, menu items yes yes*

SIZE Switcher size Minimum memory yes

STR String Text, file names yes yes*

WIND Window Window template yes yes*

Primarily used by System

CURS 16 x 16 cursor (Watch, I-beam) yes

DRVR Driver (Desk accesories) Ý

FCMT Finder comment Desktop “Get Info” yes --

FKEY Func key Cmd-shift routines -- --

FOND Font family Font manager yes

FONT Font All user fonts yes

INIT Initialization When system loaded

INTL International Country-specific Ý yes

LAYO Finder layour Desktop display

PACK Code Package Code libraries -- --

PAT 8 x 8 pattern (Scroll bar) yes

PAT# Pattern list (MacPaint) yes

Rarely Used

CDEF Custom control -- --

CNTL Control Defaults, scroll bars Ý

FWID Font width -- --

ICON 32 x 32 icon (Author’s face) yes yes

MBAR Menu bar Complete menu set -- --

MDEF Custom menu (keypad, patterns) -- --

PREC Printer custom -- --

PICT QD picture (Help screen) Ý Ý

STR# String list Messages yes yes*

WDEF Custom window (unusual shape) -- --

Ý Limited capability

* Preferred editor

Figure 3: Choosing between resource editors