Res Formats
| Volume Number: | | 2
|
| Issue Number: | | 6
|
| Column Tag: | | Resource Roundup
|
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
