Resource Formats for Asm, RMaker and Lisa

By David Wilson, Personal Concepts

Creating Resources

When I first began to program the Mac, the accepted way to create resources was to define them in a text file (named something like ExampleR.text) using the Lisa Workshop. You then ran the text file through the Lisa's RMaker to compile this high-level "resource language" into the correct format for each resource on disk.

In the Fall of 1984, I began to present Apple's three-day Macintosh Technical Training seminars, designed to teach the basics of Mac programming, and we used this approach to do our in-class programming with the Lisa Pascal Workshop.

Things have gotten more complicated during the last year, with the development of various utility programs to help you create and modify resources, and even decompile them into text files. Furthermore, as the readers of MacTutor long ago recognized, programming directly on the Mac has grown tremendously in popularity. Many programmers still use the text file approach, but use the RMaker that runs on the Mac - one with a slightly different format from that used on the Lisa.

I had to deal with these format differences when we developed Apple's new four-day Macintosh Programing Seminars , using TML Pascal on the Mac for in-class programming. I had to convert my sample programs' source code from the Lisa Workshop to TML Pascal, and finally created the table that follows to help in the process. It is presented here in the hope that you will also find it useful.

"But wait", you cry! "I never use a Lisa - why should I care about it's obscure RMaker format?" Good question. Here are some answers:

1. There are still many Lisa source code samples, from Apple and other sources, that you may want to use. This table will help you painlessly convert them to your Mac development system.

2. There are useful utility programs, such as DialogCreator and REdit that produce text files only in the Lisa format. Again, you must do the conversion.

3. Other utility programs, such as ScrnEdit, will produce text files in either format, but the text files often become a bit garbled in the process - you will need some reference to put things in order, and the table may also be helpful in that case.

Of course, you may have decided not to use text files at all, since resources can be created directly with ResEdit, and "included" with the RMaker or Linker step. The disadvantage to this approach is that you lose the documentation provided by the text files, and you sometimes will have more difficulty in exactly aligning the rectangles for scroll bars, dialog items. etc.

In any case, good luck in your Macintosh programming, and remember Scott Knaster's motto for all Mac programmers: "Everything you know is wrong."

[For those of us fanatics that insist on doing our resources in assembly language, we've also included the assembly formats from an earlier issue of MacTutor, listed below. Following the assembler formats are the RMaker resource formats for both the Macintosh and the Lisa. -Ed.]

Assembly  Resource Formats
;
;Resource Prototypes for Assembler usage
;by
;Frank Alviani
;
;NOTES -
;
;ALL resources using local labels (labels starting with @)
;must be bracketed by regular labels; local labels can be
;re-used only if the duplicates are separated by regular
;labels. This applies even if no warning appears in the 
;  resource prototype!
;
;     These are arranged roughly alphabetically, altho the
;DLOG/ALRT/DITL are grouped together at the end.
;
;In general # represents a numeric field normally filled in.
;The name and attribute fields on the RESOURCE line are 
;optional.
;
;The idea is to have this in one editor window, and to copy
;to the resource file being built as needed. This will
;hopefully speed the process, and give flexability the 
;RMaker doesn't.
;
;There are some additional explanatory comments with 
;various resources.
;
;Some of this is copied from MacTutor Vol. 1 No. 4.

;RESOURCE ATTRIBUTES

SYSREF  EQU 128
SYSHEAP EQU 64
PURGABLEEQU 32
LOCKED  EQU 16
PROTECTED EQU    8
PRELOAD EQU 4
CHANGED EQU 2

;RESOURCE FILE ATTRIBUTES

READONLYEQU 128
COMPACT EQU 64
MAPCHANGEDEQU    32

;DITL TYPE EQUATES
BUTTON  EQU 4
CHKBOX  EQU 5
RADIO   EQU 6
RESCTL  EQU 7
;
STATEXT EQU 8
EDITEXT EQU 16
ICONITM EQU 32
QDPICT  EQU 64
USERITM EQU 0
;
DISABLE EQU 128

;WINDOW TYPES
DOCBOX  EQU 0  ;standard doc window
ALERT   EQU 1  ;alert
PLAIN   EQU 2  ;plain
PLAINSHDEQU 3  ;plain with shadow
NOGROWDOC EQU    4 ;doc window w/o grow box
ROUNDBOXEQU 16 ;rounded-corner window  ;(see IM for setting corner radius..)

;CONTROL TYPES
CBUTTON EQU 0  ;simple button
CCHKBOX EQU 1  ;check box
CRADIO  EQU 2  ;radio button
USEWFNT EQU 8  ;add to above to use 
 ;window's fonts
CSCROLL EQU 16 ;scroll bar

; IDENTIFICATION resource - needed for Finder to locate Icon
RESOURCE'WCA1' 0 'IDENTIFICATION'
 DC.B AA1-@1
@1:DC.B 'Ver. 0.1 3/31/85'
AA1:

;BUNDLE resource
.ALIGN  2
RESOURCE'BNDL' ### 'name' [(attr)]
 DC.L 'WCA1';signature
 DC.W 0,1 ;data (doesn't change)
 DC.L 'ICN#';icon mappings
 DC.W 0 ;number of mappings - 1
 DC.W 0,128 ;map 0 to icon 128
 
 DC.L 'FREF';FREF mappings
 DC.W 0 ;number of mappings - 1
 DC.W 0,128 ;map 0 to fref 128

;CONTROL resource
;
;NOTE - although the assembler definition of this claims
;that the "control type" field is a long word, IT LIES.
;Control type is a 16-bit field!!

.ALIGN  2
RESOURCE'CNTL' ### 'name' [(attr)]
 DC.W # ;top
 DC.W # ;left
 DC.W # ;bottom
 DC.W # ;right
 DC.W # ;initial value
 DC.W 0 ;visible (T/F)
 DC.W # ;max value
 DC.W # ;min value
 DC.W # ;control type
 DC.L 0 ;refCon
 DC.B @2-@1 ;title length (at least 1)
@1:DC.B 'xxx'    ;title
@2:


;CURSOR resource
.ALIGN  2
RESOURCE'CURS' ### 'name' [(attr)]
 DC.L #,# ;1st 8 bytes of cursor
 DC.L #,# ;2nd 8 bytes
 DC.L #,# ;3rd 8 bytes
 DC.L #,# ;4th 8 bytes

 DC.L #,# ;1st 8 bytes of mask
 DC.L #,# ;2nd 8 bytes
 DC.L #,# ;3rd 8 bytes
 DC.L #,# ;4th 8 bytes    
 DC.W #,# ;h,v of hot spot
 
;FREF resource
RESOURCE'FREF' ### 'name' [(attr)]
 DC.B 'APPL',0,0,0
 
;ICN# resource
.ALIGN  2
RESOURCE'ICN#' ### 'name' [(attr)]
;there'd usually be an 'include' here...

;MENU resource
;
;NOTE - the "enable field": bits are number right to left 0-15.
;Bit 1 is the first menu item. A "0" bit in the mask disables
;that item. I haven't tried it, but I think turning off bit 0 of the
;mask disables the entire menu..

.ALIGN  2
RESOURCE'MENU' ### 'name' [(attr)]
lbl:    DC.W1    ;MENU ID
 DC.W 0 ;width holder
 DC.W 0 ;height holder
 DC.L 0 ;std menu pro holder
 DC.L $1FF;enable all items
 DC.B @2-@1 ;title length (in bytes)
@1:DC.B 20;title (this is the apple)
@2:

;MENU ITEM resource
 DC.B # ;item length
 DC.B 'xxx' ;menu item
 DC.B 0 ;no icon
 DC.B 0 ;keyboard equivalent
 DC.B 0 ;marking character
 DC.B 0 ;style of item's text
 
 DC.B 0 ;END OF MENU ITEMS
 
;PATTERN stuff
.ALIGN  2
RESOURCE'PAT ' ### 'name' [(attr)]
 DC.L #,# ;1st, 2nd 4 bytes of pattern
 
.ALIGN  2
RESOURCE'PAT#' ### 'name' [(attr)]
 DC.W # ;# of patterns
 DC.L #,# ;1st, 2nd 4 bytes of pattern #1

;STRING resource
.ALIGN  2
RESOURCE'STR ' ### 'name' [(attr)]
 DC.B @2-@1 ;text length
@1:DC.B 'xxx'    ;text
@2:

;STRING LIST resource
.ALIGN  2
RESOURCE'STR#' ### 'name' [(attr)]
 DC.W # ;count of strings
 DC.B @2-@1 ;text length - string #1
@1:DC.B 'xxx'    ;text
@2:
label:  ;REQUIRED REGULAR LABEL HERE!

;WINDOW resource
.ALIGN  2
RESOURCE'WIND' ### 'name' [(attr)]
 DC.W # ;top
 DC.W # ;left
 DC.W # ;bottom
 DC.W # ;right
 DC.W # ;window type
 DC.W # ;visible (T/F)
 DC.W # ;draw goAway (T/F)
 DC.L 0 ;refCon (available)
 DC.B @2-@1 ;title length
@1:DC.B 'xxx'    ;title
@2:

; --- Dialog / Alert / DITL are grouped together ---

;DIALOG resource
.ALIGN  2
RESOURCE'DLOG' ### 'name' [(attr)]
 DC.W # ;top
 DC.W # ;left
 DC.W # ;bottom
 DC.W # ;right
 DC.W # ;window type
 DC.B # ;visible (T/F)
 DC.B 0 ;IGNORED
 DC.B # ;goAway flag (T=has close box)
 DC.B 0 ;IGNORED
 DC.L 0 ;refCon
 DC.W # ;ID of DITL list  
 DC.B @2-@1 ;text length
@1:DC.B 'xxx'    ;text
@2:

;ALERT resource
.ALIGN  2
RESOURCE'ALRT' ### 'name' [(attr)]
 DC.W # ;top
 DC.W # ;left
 DC.W # ;bottom
 DC.W # ;right
 DC.W # ;resource ID of DITL list  
 DC.W # ;stages (see IM for details..)

;DITL resource
.ALIGN  2
RESOURCE'DITL' ### 'name' [(attr)]
 DC.W # ;# of items - 1

lbl:    DC.L0    ;handle holder
 DC.W # ;top
 DC.W # ;left
 DC.W # ;bottom
 DC.W # ;right
 DC.B type;item-type
 DC.B @2-@1 ;item length (MUST BE EVEN)
@1:DC.B 'xxx'    ;item
@2:

; items must be even length
; item types are as follows
;  control item = item + 4
;     button0
;check box1
;radio button  2
;resource 3
;
;static text8
;edit text16
;icon item32
;quickdraw pict  64
;user item0
;
; disable item = item + 128
; system icons
;stop   0
;note   1
;alert  2

RMaker Formats

The chart on the next four pages summarizes the Resource text file formats by the RMaker used by most Macintosh programming systems, including TML Pascal, Consulair C, Megamax C, and the MDS Assembler. The formats are shown in the left-hand column, with comments in the far right-hand column.

The center column shows the differences to be aware of when using the Lisa Pascal Workshop RMaker. In may cases there are no differences, but when there are, they are often subtle and easily missed, so check carefully.

The most subtle difference involves defining scroll bars, with the Macintosh RMaker needing the minimum, then maximum, then initial setting of the thumb. The Lisa RMaker wants miminum, initial, and then maximum. Your scroll bars will not work if you get these confused.

Other problems include the Macintosh RMaker's requirement that you separate items with a truly blank line (containing only a carriage return), and define a string resource with "STR(space)". The Lisa RMaker is more tolerant in these areas.

The format for dialog items (DITL) is that for Macintosh RMaker 2.0D2, shipped with the December 1985 Software Supplement (Volume I, Issue II). The ealier version is similar, but not quite as powerful.

                                 Macintosh            Lisa                          Comments

------------------------------ Bundles of Finder Information -------------------------------------------
Type BNDL
                                 ,128
JEN4 0                      Creator, Signature, Owner
ICN#                         Finder Icon and Mask
0  129  1  130                                       applic. is 129; document is 130
FREF                                                      File type
0  131  1  132                                       APPL is 131;  SCRN is 132

                                                             Type BNDL
                                                             ,128
                                                             JEN4 0                       Local ID 0
                                                             2                               2 types follow
                                                             ICN# 2                       2 Iicon lists
                                                             0  129                       local ID 0 goes with ICN# ID 129
                                                             1  130
                                                             FREF 2                       2 file references
                                                             0  131                       local ID 0 goes with FREF ID 131
                                                             1  132

Type JEN4 = STR                                   Creator name
                                 ,0                         Local ID of 0 for ICN# and FREF
This is for your own use                                                                      Any text that you want

Type FREF                 File reference (file type)
                                 ,130                     Resource ID = 130
APPL 0                                                  Application; local ID = 0.

                                 ,131                     Resource ID = 131
SCRN 1                                                  Document file type; local ID = 1.

Type ICN# = GNRL     Icon and Mask for Finder
                                 ,129                     Use IDs from 128 to 255
.H                                                          Hexadecimal data will follow
0001 8000 0002 4000                          16 lines of 16 hex digits for icon
.                                                            .
.                                                            .
000F F000 000F F000                                                                         16  lines of 16 hex digits 
for mask

                                                             Type ICN#
                                                             ,129
                                                             2                               icon and mask follow
                                                             00018000                 32 lines of 8 hex digits for icon
                                                             ...                              32 lines of 8 hex digits for mask

------------------------ Using CODE resources  from Linker output ------------------------------
Include TML1:T13      Type CODE            From Linker
                                                             Demo9L,0                  Use Demo9L.obj; start with CODE 
0
---------------------- Controls, such as scroll bars, push buttons, etc. ---------------------------
Type CNTL                                             Control
                                 ,401                     Resource ID
Vertical bar                                           Title; doesn't show on scroll bars
-1 416 273 432        top left bottom right (local coord)
Visible                                                   Can see it right away
16                                                         Scroll bar
0                                                           32-bit reference constant  = 0
0  70  35                                               minimum  maximum  current
                                                             0  35  70                   minimum  current      maximum
----------------------------------- Cursor definition -------------------------------------------------------
Type CURS = GNRL                                 Cursor
                                 ,401
.H                                                          Hexadecimal data will follow
2000 ... 0000                                        64 hex digits for cursor data
FFFF ... FFFF              64 hex digits for mask data
0003 0003                                            top left (y x)

                                                             Type CURS
                                                             ,401
                                                             2000...0000
                                                             FFFF...FFFF
                                                             0003 0003
-------------------------------- Dialog and Alert boxes --------------------------------------------------
Type ALRT                Same                     Alert box
                                 ,503                     Resource ID
70 131 190 381                                    top left bottom right (global)
603                                                       Use DITL number 603
F432                         Stages list  (stages 4321)

Type DLOG                                             Dialog window
                                 ,401                     ID
About T13               Dialog window title
30 12 326 500                                      top left bottom right (global)
Visible  NoGoAway                                 or Invisible, or GoAway
1                                                           Dialog window type
0                                                           Dialog window reference constant
501                                                       Use DITL 501

                                                             Type DLOG
                                                             ,401
                                                             30 12 326 500
                                                             Visible 1 NoGoAway 01 = window type; 0 = ref constant
                                                             501                           Use DITL 501
                                                             About Demo9            Title

Type DITL                  Same                    Dialog Item List
                                 ,501                     (Optional) name, ID
9                                                           Number of items in list

BtnItem                     BtnItem Enabled     Push button, enabled
85 382 155 465                                    top left bottom right (local)
Put Away                  words to go in button

ChkItem Disabled       ChkItem Disabled    Check box, disabled
185 260 205 420                                  Includes check box and words
Some words              Put to right of check box

EditText Disabled       EditText Disabled  Editable text, with frame
185 10 205 245
Modify these words   Up to 240 characters

IconItem                    IconItem Enabled    Icon, but no mask
12 14 76 78                                          Icon scaled to fit this rectangle
257                                                       Use ICON   ID = 257

PicItem                     PicItem Enabled      QuickDraw Picture (PICT)
35 25 90 110                                        Picture scaled to fit this rectangle
128                                                       Use PICT ID = 128

RadioItem                  RadioItem Enabled  Radio button
245 260 265 420                                  Button and words inside rectangle
1200 Baud                                             Words to right of radio button

ResCItem                   ResCItem Enabled  Scroll bar
0 400 260 415                                      Fit in this rectangle
512                                                       Use CNTL ID = 512

StatText                   StatText Enabled    Static text
210 10 230 245                                    Word-wrapped inside rectangle
Cannot fix this                                       Up to 240 characters

UserItem                   UserItem Enabled   User-defined
------------------------ Icons for menu, dialog box, or in your program ------------------------
Type ICON = GNRL                                  Icon, with no mask
                                 ,257                     Use IDs from 256 to 511
.H                                                          --------                    No .H for Lisa
00FFAA11                                             32 lines of 8 hex digits
----------------------------- Menu titles and items -----------------------------------------------------
Type MENU                Same                     Menu
                                 ,401                     (Optional) name, ID
\14                                                       Hex 14 = ACSII 20 =  
                                 About T13 ^1                                                    Use ICON (256 + 1) = 257 
on the left
                                 (-                         Disabled dotted line
--------------------------- Procedures as resources ----------------------------------------------------
Type PROC                --------------------                             Procedure, such as CDEF, MDEF
                                 ,128                     Resource ID
MyProcedure                                         filename for procedure (from Linker)
-------------------------- A single string (use GetString ROM call) ----------------------------------
Type STR_                Type STR               Use blank after STR for Mac version
                                 ,300
This is a message      Up to 255 characters
----------------------------- A list of strings (use GetIndString) ----------------------------------------
Type STR#                List of strings
                                 ,400
2                                                           Number so strings in the list
This is the first string                                                                         Item 1
Here is another string                            Item 2
                                                             Type STR#
                                                             ,400
                                                             This is the first string
                                                             Here is another string
------------------------------------- Window template ----------------------------------------------------
Type WIND                 Same                    Window template
                                 ,401                     Resource ID 
Untitled                     Title
40 64 327 495                                      top left bottom right (global)
Visible  GoAway        or Invisible, or NoGoAway
4                                                           Window type
0                    Reference constant