This Technical Note describes resource structure formats for previously-unpublished types.
Changes since December 1991: Added information on rFont resources. Clarified the note about rVersion resources to note that version numbers must increase with subsequent releases for the Finder's benefit.
The format used to describe the resources is similar to that used in File Type Notes, where the offsets, given in the form (+xxx), determine the offset from the beginning of the resource.
The following describes the Sampled Sound resource format. It consists of a ten-byte header followed by the sample data bytes.
The resource compiler template follows:
#define rSoundSample $8024 /*---------------------- rSoundSample --------------------*/ type rSoundSample { integer; /* format */ integer; /* wave size */ hex integer; /* rel pitch */ integer; /* stereo channel */ unsigned integer; /* sample rate */ hex string; /* raw 8 bit sound data */ };
The following describes the Cursor resource format:
We will call the first byte beyond the image offset "ei" for "end of image."
We will call the first byte beyond the mask offset "em" for "end of mask."
The resource compiler template follows:
#define rCursor $8027 /*---------------------- rCursor --------------------*/ type rCursor { height : hex integer; /* height */ width : hex integer; /* width in words */ hex string[2*$$Word(height)*$$Word(width)]; /* cursor image */ hex string[2*$$Word(height)*$$Word(width)]; /* cursor mask */ hex integer; /* hotspot Y */ hex integer; /* hotspot X */ hex integer; /* flags */ hex longint = 0; /* reserved */ hex longint = 0; /* reserved */ }; };
Following is a simple cursor example:
resource rCursor(1,fixed) { 5, /* height */ 2, /* width */ $"ffff0000" $"f00f0000" $"f00f0000" $"f00f0000" $"ffff0000", $"ffff0000" $"ffff0000" $"ffff0000" $"ffff0000" $"ffff0000", 2, /* hotspot Y */ 2, /* hotspot X */ $80 /* 640 mode */ };
Note that the resource is marked fixed so that its handle can be dereferenced and passed to SetCursor.
Files may include a version resource with ID=1 for display by programs such as the Finder. All rVersion resource IDs other than 1 are reserved for future definition. The following describes the version resource format:
The resource compiler template follows:
#define rVersion $8029 // Equates for the country code of an rVersion resource #define Region \ verUS, verFrance, verBritain, verGermany, verItaly, verNetherlands, verBelgiumLux, verFrBelgiumLux = 6, verSweden, verSpain, verDenmark, verPortugal, verFrCanada, verNorway, verIsrael, verJapan, verAustralia, verArabia, verArabic=16, verFinland, verFrSwiss, verGrSwiss, verGreece, verIceland, verMalta, verCyprus, verTurkey, verYugoslavia, verYugoCroatian = 25, verIndia = 33, verIndiaHindi = 33, verPakistan, verLithuania = 41, verPoland, verHungary, verEstonia, verLatvia, verLapland, verFaeroeIsl, verIran, verRussia, verIreland = 50, verKorea, verChina, verTaiwan, verThailand /*------------------- rVersion ------------------*/ type rVersion { ReverseBytes { hex byte; // Major revision in BCD hex bitstring[4]; // Minor vevision in BCD hex bitstring[4]; // Bug version hex byte development = 0x20, // Release stage alpha = 0x40, beta = 0x60, final = 0x80, /* or */ release = 0xA0; hex byte; // Non-final release # }; integer Region; // Region code pstring; // Short version number pstring; // Long version number };
Following is a simple version example for "Super Graphics Destroyer", version 2.0:
resource rVersion(1) { { $02,$0,$0,release,$00 }, /* version 2.0 release */ verUS, /* US version */ "Super Graphics Destroyer", /* our app's name */ "(C) 1991 Pretty as a Picture, Inc." /* the copyright notice */ };
Note: For compatibility with the Finder, keep the name field identical across different versions of the same application, and make sure the version field increases on each later version released to your customers. The moreInfo field is not critical; if it changes between versions, it's no big deal.
Files may include a comment resource with ID=1 for display by programs such as the Finder. All rComment resource IDs other than 1 are reserved for future definition. The following describes the comment resource format:
The resource compiler template follows:
#define rComment $802A /*---------------------- rComment --------------------*/ type rComment { string; };
A tagged strings resource lists pairs of Word values and Pascal strings.
The resource compiler template follows:
#define rTaggedStrings $802E /*------------------- rTaggedStrings --------------------*/ type rTaggedStrings { integer = $$Countof(StringArray); array StringArray { hex integer; /* Key integer */ pstring; /* String */ }; };
Following is a simple rTaggedStrings example:
resource rTaggedStrings(1) {{ $0050, "red", $0033, "green", $0100, "blue" }};
A pattern list resource contains zero or more 32-byte QuickDraw II patterns. (This resource type exists for your convenience. The System Software contains no direct support for resources of this type.)
The resource compiler template follows:
#define rPatternList $802F /*-------------------- rPatternList ---------------------*/ type rPatternList { array { array[32] { hex byte; }; }; };
The rectangle list (type rRectList) is provided to allow an extensible, easily modifiable collection of QuickDraw II rectangle structures. This capability can enhance a developer's ability to modify on-screen displays without recompiling an entire application. This resource also enables easier cross-development and parallel development for the Apple IIgs and the Macintosh.
The following describes the rectangle list resource format:
The resource compiler template follows:
#define rRectList $C001 type rRectList { integer = $$Countof(RectArray); array RectArray { Rect; }; };
As a convenience for applications, a print record may be included as a resource of type $C002 (rPrintRecord). If more than one of these resources is present, the one to use as the document's primary print record is the first one. You can get this resource's ID by calling GetIndResource with type rPrintRecord and index 1. Storing the primary print record with ID = 1 is a good way to start.
Since the print record is filled in and interpreted by the printer driver, you can't always programmatically set options that are driver-specific. For example, although the ImageWriter driver stores the color-vs.-black and white option in one place, not all color printers will do the same thing. If you want to use driver-specific options on many printers, you can use those printer drivers to create print record that reflect the options you want and store those records as resources. Then, if you need a pre-initialized print record with the options you want, you may already have one.
Since applications shouldn't create print records from scratch, but rather allow printer drivers to fill them in with PrDefault and PrVerify, the resource compiler template that follows only allocates 160 bytes for storage.
#define rPrintRecord $C002 /*-------------------- rPrintRecord ------------------*/ type rPrintRecord { array[160] { hex byte; }; };
Some applications wish to keep fonts with the application itself instead of in a separate font file. This isn't always advisable -- fonts not in font files can't be easily used in other applications, which may confuse users who, for example, use text-editing desk accessories and can't get at certain fonts except in certain applications. Also, fonts not in the Fonts directory must be completely memory-resident where normal Fonts are only loaded from disk when they're needed.
Nevertheless, in some cases keeping fonts inside an application file is necessary or desirable. In such cases, the rFont resource is a convenient way to keep a font around. The resource is a QuickDraw II Font, as defined in Apple IIgs Toolbox Reference, Volume 2. The font family name is the resource's name -- the same Pascal string that normally precedes the QuickDraw II font record in the font file.
Since the font record is a bunch of variable-sized tables, and since you probably want to use a font editor (and not the resource compiler) to create fonts, the following resource compiler template isn't very revealing.
/*-------------------- rFont ------------------*/ type rFont { hex string; };
This and all of the other Apple II Technical Notes have been converted to HTML by Aaron Heiss as a public service to the Apple II community, with permission by Apple Computer, Inc. Any and all trademarks, registered and otherwise, are properties of their owners.