Almost a Fonts Menu for PCMac Basic

By Dave Kelly, MacTutor Editorial Board

The months seem to be flying by and the major improvements to Basic that I have been waiting for are still not released. There are some improvements which are worth mentioning. This month I speak of improvements to the PCMacBasic compiler (now version 2.01). It has been several months since I last spoke of PCMacBasic. The authors were quite busy toward the end of last year finishing up other projects so there wasn’t much progress to talk about. Now there have been some noteworthy improvements, although there are still some weak areas which can and will probably be corrected if we give them enough time.

The first improvement that I noticed was the manual now has a spiral binding. The previous manual I had was stapled and not easy to handle. Documentation style has not changed much, but there has been a little more explanation added to some sections. I still have trouble finding things in it (there is no index). Since the manual is split into two sections, General Information and Alphabetical List of Basic Commands, there are two separate sets of page numbering (one for each). If you don’t know this you could get lost easy if you are looking in the wrong half of the book. Most every section contains more information than was presented in the old manual. However, I felt that a novice user might have trouble understanding somethings the first time through.

LINE LABELS SUPPORTED

A major improvement to PCMacBasic is the ability to use line labels (as opposed to line numbers) in your program source code. If the Line Labels box is checked in the Compile dialog box, your Basic program may have alpha-numeric labels for lines as well as integers. If the Line Labels box is checked, line numbers are considered to be labels of digits. Up to 38 digits are allowed and compared. (When the Line Labels box is not checked, line numbers must be 1 to 65534.) When compiling, each line label is mapped to a line number when it is first encountered. That number is used in place of the label by the compiler. An alpha-numeric label is mapped to the highest number already used plus one. If the highest number, 65535, has already been used, then the highest number available is used.

When the Line Label feature is used, all line labels, even all-digit labels, are stored in the Symbol Table while compiling. This is slower and uses more memory for each label than compiling with the Line Labels feature turned off. Programs with a number on each line should be compiled with Line Labels off, or the numbers should be removed from lines which are not entry points!

HFS SUPPORT

HFS support has been improved. The FILES$ functions return the full path names as it should. However, The FILES$(PROGRAM) function returns only the name of the program file and not the full path name even when the default path name is another volume. This is better support than MS Basic provides, but it would be nice to be able to find out where your application is located. (Note:see June 1987 MacTutor, page 8, for the solution for MS Basic). My SCSI Hard Disk turns out to have a volume number of -1 which is not mentioned in the manual (The manual states that hard disk boot volume is drive number 3, pg. 23. This may refer to Apple HD20????).

TOOLBOX ACCESS

The (improved) PCMacBasic manual now has a better explanation of how to call the toolbox from PCMacBasic. The remainder of this column will discuss the ‘method to the madness’ of calling the toolbox.

It would certainly help you if you have had some experience working with an assembler at some time in your life. It turns out that you don’t need to know how to do assembly to call the toolbox if you know just a few basic assembler codes. Toolbox calls in PCMacBasic are made by way of the USR function/statement. This statement is used for calling routines written in other languages.

At this point it is important that you have a copy of Inside Macintosh to refer to. To understand the toolbox calls listed in Inside Macintosh you need to understand the data types used in the calls. The Pascal data types are:

Type Size

INTEGER 2 bytes

LONGINT 4 bytes

BOOLEAN 1 byte

CHAR 2 bytes

SINGLE (or REAL) 4 bytes

DOUBLE 8 bytes

EXTENDED 10 bytes

COMP 8 bytes

STRING[n] n+1 bytes

Signed Byte 1 byte

Byte 2 bytes

Ptr 4 bytes

Handle 4 bytes

Record or Array 2 or 4 bytes

VAR parameter 4 bytes

Most toolbox calls will use the INTEGER or STRING[n] types of parameters. There are other types which are defined by Pascal which are made of the primary types above. Let’s take a look at an example:

themenu!=USR “ DC.W $A931” (304,title$)

In this example the USR function is used to call NewMenu (toolbox function). The USR function will insert $A931 at the point in the program where this statement appears. The “DC.W” is an assembler pseudo-op which instructs the compiler/assembler what to do. (NOTE: A SPACE MUST PRECEDE THE DC.W). Page 11 of Appendix F (PCMacBasic manual) lists the valid pseudo-op codes. Unless you like assembly language you probably won’t have to remember more than a couple of these (DC.W being the most frequently used in toolbox calls). Macro names may be substituted for the assembler pseudo-op “DC.W”. The PCMacBasic manual states that all you have to do is “copy the macro definitions from the appropriate files for the assembler you are using into the BASICMacConst file”. This is stupid!! First of all, I’m using PCMacBasic compiler not somebody’s assembler! The compiler should be smart enough to take care of this for me! Besides, they didn’t even include the assemble macro definitions in a file on the PCMacBasic disk to include in the BASIC MacConst file or directions on how to add my own. They’re assuming that I know how (or want to) program in assembly. In fact, I like Basic because I don’t have to go through all the trouble that assembly provides. Well, at least PCMacBasic provides a way to do the calls I want even if it does make it harder than it should be. If you have to use “DC.W” then you will have to look up the appropriate address for the macro name in Appendix C of Inside Macintosh vol. 3 .

Refer to page I-351 of Inside Macintosh to find the parameters that must be passed to the toolbox function. There you will find the first parameter is menuID which is an INTEGER type. INTEGER types are passed directly to the stack . In the example 304 is the menuid which is passed directly to the stack. A variable such as Menuid% could have been used in place of 304 (provided that Menuid% is set equal to 304 before using the NewMenu function. The INTEGER type, as you can see, is simple to use. Life starts to get tougher when other types must be passed.

The main thing to keep in mind here is how many bytes need to be passed and how many bytes each PCMacBasic variable uses. The PCMacBasic manual covers this very briefly on page 4-6. Fortunately, the variable types are similar to those used in MSBasic so it might be easy to guess.

PCMacBasic Size

Integers 2 bytes

single 4 bytes

double 8 bytes

strings 4 byte descriptor

records VARPTR

Integers are 2 bytes, single precision are 4 bytes, double precision are 8 bytes. Strings are stored in the heap with a 4 byte descriptor. Integers and single precision may be passed directly. When calling Pascal records you have to use VARPTRs, since Pascal passes addresses for anything over 4 bytes rather than the actual data on the stack.

Now back to the example. The menuTitle parameter is type Str255 (according to Inside Macintosh) . Str255 represents a STRING type with up to 255 characters. The Pascal string is consists of a length byte and the string information following it. Therefore, the menu title must be converted to a Pascal string before it can be passed to the NewMenu function. The PCMacBasic suggests a couple of ways to do this. The easiest is to concatenate the length to the beginning of the string as follows:

title$=chr$(len(“Fonts”))+”Fonts”

The problem with this method is that it is really much slower than it should be. Page 4 of Appendix C (PCMacBasic manual) gives alternative methods. This is one of the weak parts of the PCMacBasic Compiler’s methods for using the Mac toolbox. I feel that the call itself should take care of this type of conversion for you. It just complicates the process. It would be better if there were a Basic string to Pascal string conversion routine (both directions) built into PCMacBasic.

Since most (if not all) of the Quickdraw routines are outlined in Appendix C (mostly passing all integer types), I’ll refer you there for more examples which pass integers. Remember you can’t use macro names unless you define them first. One of the best things about PCMacBasic is that the toolbox calls are completely compatible with all of the PCMacBasic command set. That’s not like some basics which won’t let you mix quick draw with their own graphics commands (or limit their use) and won’t give you handles and pointers to their own menus and controls so you could use them from your own toolbox calls.

Another tricky conversion example: During my studies of PCMacBasic’s toolbox calls I had trouble in converting a parameter of type ResType for use in a call. The solution isn’t readily found (it’s not documented) in the PCMacBasic manual although it is consistent with the way that the USR statement works. Try the AddResMenu call for example. I like this one. In fact this is a call that ZBasic and MSBasic still can’t do properly. Page I-353 of Inside Macintosh shows the format for the AddResMenu call. All that is needed is the menu handle and the resource type and the call searches all open resources of the type and appends the names to the menu. Simple! Well, it turns out that if you use “FONT” as the resource type passed that the routine doesn’t find the FONT resources. IF you convert to a Pascal string by adding the length byte at the beginning of the string it still can’t find the resources. The key comes in realizing that ResType is a packed array [1..4] or CHAR. This Pascal lingo means that it is four characters (not a string). Well, remember that each character takes up one byte (that’s 4 bytes total). That means we need to get 4 bytes transferred to the stack. We know that integers will transfer 2 bytes so by defining two integers we are able to transfer 2 characters in each. Here is when you need to think about hex representation of numbers for a moment. We are trying to put “FONT” on the stack. That converts to 70797884 in decimal (ASCII code) or 464F4E54 in hex. Therefore the first integer should be F1%=$464F and the second F2%=$4E54. Convert this to decimal to get F1%=17999 and F2%=20052. Now plug into the call:

USR “ DC.W $A94D” (themenu!,F2%,F1%)

realizing that the integers will be pull off the stack with last byte on is the first byte off (LIFO). Personally I would like to be able to just enter the string “FONT” and have statement work. The PCMacBasic calls are not actually built in to the compiler (you insert them yourself). I consider this a sort of a kludge although very effective if you realize what is going on.

RESOURCE FILES

A few words about resource files: If you want your program to function like a true Macintosh application then you must use a resource file. If no resource file is specified then PCMacBasic will use the demo resource file named PCDemoR. It contains a sample set of resources that will keep the applications happy while your program is running. To create your own resource file, I recommend making a copy of the PCDemoR file and modifying it to meet the needs of your own application. The Resource Compiler is documented in Appendix F of the manual. This is the same Resource Compiler as used in McAssembly compiler from Signature Software. The legal pseudo-op codes are defined in appendix F along with details on the format of the various resources that are used.

In the sample program I have modified the resource file slightly to customize it for this program. I stripped out some of the error code stuff so as to save some space but your may want to keep it in your own file.

The first part of the resource file that you will want to customize is the program signature. This string is inserted in the application resource file to give the version number and applicable information. Next the menus are declared. The Apple menu may be deleted from the resource file if you don’t want desk accessories available to your application. Desk accessories will automatically be loaded (like it or not). The File menu items may be customized as you like. The Edit menu is set up in the standard Edit menu format and should probably be left as is for most applications. Other menus should be added from this point on.

The next resources are used for various dialog boxes used for debugging and for the About dialog box. Next are default controls and windows.

You may want to use your own custom icon for the application and files created by the application. Refer to previous issues of MacTutor for tutorials on adding icons to your applications. I recommend that you use ResEdit to copy the hex representation of the icon and the past it into the resource file and format it as shown in the sample resource files.

The runtime configuration resource is used by PCMacBasic to set default attributes. Don’t mess with these unless you either know what you are doing or don’t care if you mess something up.

The FREF resource defines the file id numbers for the application and the document file. Note that the signature I used in the sample is PROF which was declared toward the beginning of the resource file and is used in the bundle resource so that the application’s icon will be displayed properly.

DISASTER STRIKES!

OK, now you are probably wondering why the sample program doesn’t do anything. Well it turns out that PCMacBasic has some problems that I didn’t know about until the very last few minutes of writing this column. The problem is that there is no way to trap the font items which we have so carefully read in using the AddResMenu statement. It turns out that the problem exists for all menus created dynamically from within our program.

Page 32 of the Alphabetical List of BASIC Commands section of the manual gives the explanation, in very fine print I might add. It states that the “runtime allocates space for as many function keys as you put in the resource file so nothing is wasted”. Menu events can only be read by the ON KEY function. ON KEY was designed to simulate function keys used in IBM PCBasic. As long as the menu is defined in the resource file the runtime code of the compiler will allocate space for the ON KEY function. I suppose that if you know how may items will be in your menu you could define a dummy menu with dummy items which you could later change. This “dummy” method is only for “dummies”. Another PCMacBasic user set up an event loop with GETNEXTEVENT and trapped the menu as you would in PASCAL (or some other superior language). If you plan to go to all that trouble then it would be better to just write your application in PASCAL to begin with.

The bottom line is that if you need to dynamically define your menus then PCMacBasic is NOT for you. However, as long as your program will only use the menus defined in the resource file you should be able to get by just fine. PCMacBasic is still the only choice for porting Basic programs over from the PC to the Macintosh. Until Pterodactyl Software decides to the ON KEY command to correctly return both a menu ID and a menu item ID, this problem will remain. As a result, like all the other Basics for the Mac, there is still no Basic which adequately provides both for the complete supprt of the Mac user interface, and the high level of use of the Basic language at the same time.

REM PCMacBasic Toolbox Sample
REM ©MacTutor 1987 by Dave Kelly
Start
break on
ERROR OFF
F1%=256*asc(“F”)+asc(“O”)
F2%=256*asc(“N”)+asc(“T”)
Fonttitle$=chr$(len(“Fonts”))+”Fonts”
themenu!=USR “ DC.W $A931” (304,Fonttitle$)  :REM NewMenu
USR “ DC.W $A94D” (themenu!,F2%,F1%) : REM AddResMenu
USR “ DC.W $A935” (themenu!,0) : REM InsertMenu
USR “ DC.W $A937”:REM _DrawMenuBar
x%=USR “ DC.W $A950” (themenu!):REM CountMItems
ERROR ON
LOCATE ,,,1,1:REM Get rid of stupid black carret when program closes.
print”There are “;x%;” items in the ‘Fonts’ menu”
on key(1) gosub quit
Loop
goto loop

quit
BEEP:END

;
; Resource File For Basic Program
;
; some equates we’ll need:
chkequ  $12 ;ascii for check mark character
visible equ $FFFF;TRUE boolean
invisible equ  0 ;FALSE boolean
nogoawayequ 0  ;FALSE boolean
goaway  equ $FFFF;TRUE boolean
button  equ 4  ;DITL BUTTON
chkbox  equ 5  ;DITL CHECK BOX
radio   equ 6  ;DITL RADIO BUTTON
stattextequ 8+128;DITL STATIC TEXT (DISABLED)
editxtdsequ 16+128 ;EDIT TEXT DISABLED
iconitemequ 32 ICON in dialog box
;
; Signature of program
;
[[ PROF,0
 TEXT #”PCMacBasic Demo  Version 1.0  May 23, 1987"
]]
; Apple menu

$$ MENU,1,4 Menu ID 1
0,0,0   Placeholders
$FFFFFFFB enable mask - 2 disabled
“/$14”  menu title = apple char
2two items in this menu
;item 1:
About this program...the menu item
0,0no icon, no keybd equivalent
0,0no marking char, text style = plain
;item 2:
-------------------- the menu item
0,0,0,0 no icon, no keybd, no mark, plain text

;
; Files menu
;

$$ MENU,302,4    Menu ID 302
0,0,0   Placeholders
$FFFFFFFF enable mask - none disabled
Files   menu title
1three items in this menu
;item 1:
“Quit”
0,0no icon, no keybd equivalent
0,0no marking char, text style = plain


; Edit menu

$$ MENU,301,4    Menu ID 301
0,0,0   Placeholders
$FFFFFFF9 enable mask - 1st & 2nd disabled
Edit    menu title
6six items in this menu
;item 1:
“Can’t Undo”the menu item
0,0,0,0 no icon, no keybd equivalent no marking char, text style = plain
;item 2:
“----------”the menu item
0,0,0,0 no icon, no keybd, no mark, plain text
;item 3:
“Cut”
0,’X’,0,0 no icon, no keybd, no mark, plain text
;item 4:
“Copy”  the menu item
0,’C’,0,0 no icon, keybd, no mark, plain text
;item 5:
“Paste” the menu item
0,’V’,0,0 no icon, keybd, no mark, plain text
;item 6:
“Clear” the menu item
0,0,0,0 no icon, keybd, no mark, plain text

; STOP or apple/period dialogue list

$$ DITL,302,32 Dialog item list, ID = 302, ATTR=32
55 items in list

;item 1:
0handle holder
50,175,65,190    display rectangle
chkbox  item type
“ “

;item 2:
0handle holder
50,200,65,330    display rectangle
StatTextitem type
“Quit”  the item

;item 3:
0handle holder
50,10,65,25 display rectangle
chkbox  item type
“ “

;item 4:
0handle holder
50,35,65,165display rectangle
StatTextitem type
“Continue”the item

;item 5:
0handle holder
10,10,30,400display rectangle
StatTextitem type
“Program interrupted in line number ^1”;the item

; fatal error dialogue list

$$ DITL,400,32 Dialog item list, ID = 400, ATTR=(32)
55 items in list

;item 1:
0handle holder
10,100,30,400    display rectangle
StatTextitem type
“Fatal program error”  the item

;item 2:
0handle holder
25,10,40,25 display rectangle
chkbox  item type
“ “

;item 3:
0handle holder
25,35,40,165display rectangle
StatTextitem type
“Restart” the item

;item 4:
0handle holder
40,10,55,400display rectangle
StatTextitem type
“Error ^0 in Line Number ^1”  the item

;item 5:
0handle holder
55,10,70,400display rectangle
StatTextitem type
“^2”    the item

; invalid keyboard entry alert list

$$ DITL,301,32 Dialog item list, ID = 301, ATTR=(32)
33 items in list

;item 1:
0handle holder
80,200,97,310    display rectangle
button  item type
“I’m sorry !”    the item

;item 2:
0handle holder
30,70,50,455display rectangle
StatTextitem type
“Invalid input in line number ^1” the item

;item 3:
0handle holder
50,25,70,455display rectangle
StatTextitem type
“Please start over from the beginning.” ;the item

; ‘About’ Dialog List

$$ DITL,300,32 Dialog item list, ID = 300, ATTR=(32)
33 items in list

;item 2:
0handle holder
30,25,50,455display rectangle
StatTextitem type
“About this program  ”      the item

;item 3:
0handle holder
50,25,70,455display rectangle
StatTextitem type
“This is a sample PCMacBasic program.” ;the item

;item 4:
0handle holder
70,25,90,455display rectangle
StatTextitem type
“©MacTutor 1987, by Dave Kelly” ;the item

;  ‘About’ Dialog Box

$$ DLOG,300,32 dialog, ID = 300, ATTR=32
100,15,250,495 bounds rectangle
1type = modal dialog box
visible initial state
nogoawayno close box
0refcon
300resc ID of DLOG’s item list
|no title

;  Function Key Dialog Box

$$ DLOG,501,32 dialog, ID = 501, ATTR=32
45,15,300,495    bounds rectangle
1type = modal dialog box
visible initial state
nogoawayno close box
0refcon
501resc ID of DLOG’s item list
|no title

;  Debugger Dialog Box

$$ DLOG,650,32 dialog, ID = 650, ATTR=32
100,60,280,450 bounds rectangle
1type = modal dialog box
visible initial state
nogoawayno close box
0refcon
650resc ID of DLOG’s item list
|no title


;  invalid keyboard input alert box

$$ ALRT,301,32 alert, ID = 301, ATTR=32
100,15,210,345 bounds rectangle
301resc ID of DLOG’s item list
$7655   stages

;  BASIC default Window

$$ WIND,300,4    Window, id=300, attr=4
40,10,325,500
0type of window
visible
goaway
0refcon
Untitledtitle


; Vertical scroll bar for WIND 300

$$ CNTL,300
20,400,220,416
0initial value
Invisible 
12000   max value
0min value
16 scroll bar
0refcon
“vertical scroll bar”   ;title


; Horizontal scroll bar for WIND 300

$$ CNTL,400
200,20,216,400
0initial value
Invisible 
12000   max value
0min value
16 scroll bar
0refcon
“horizontal scroll bar”   ;title

; Cursor
$$ CURS,300,4
$01801A70,$2648264A,$124D1249,$68099801
$88024002,$20022004,$10040808,$04080408
$00000000,$00000000,$00000000,$00000000
$00000000,$00000000,$00000000,$00000000
$0008,$0008


; Professor Mac Icon & Mask for Program Icon
$$ ICN#,128
$00000000,$00000000,$00000000,$00070000
$000F8000,$001FE000,$003FF800,$007FFE00
$00FFFF00,$01FEFF00,$01FFBE00,$00FFEC00
$005FFE00,$0087FD00,$00B9E480,$00B445C0
$00800480,$008005C0,$00A02480,$00BFE400
$009DC5DB,$00400895,$00201095,$001FE000
$00102000,$001FE000,$00601800,$01800600
$02186100,$04C30C80,$04000080,$07FFFF80
$00000000,$00000000,$00000000,$00070000
$000F8000,$001FE000,$003FF800,$007FFE00
$00FFFF00,$01FFFF00,$01FFFE00,$00FFFC00
$007FFE00,$00FFFD00,$00FFFC80,$00FFFDC0
$00FFFC80,$00FFFDC0,$00FFFC80,$00FFFC00
$00FFFDDB,$007FF895,$003FF095,$001FE000
$001FE000,$001FE000,$007FF800,$01FFFE00
$03FFFF00,$07FFFF80,$07FFFF80,$07FFFF80

; Document Icon and mask for Document Icon
$$ ICN#,129
$00000000,$7FFFFF80,$403FFD40,$407FFD20
$40FFFD10,$41FFFD08,$43FFFDFC,$47FFFC04
$4FFEFFFC,$5FFD01F4,$4FFEFE64,$47FFFFC4
$41FFFFA4,$423FFF94,$440FFE94,$4463FCBC
$44F0F894,$44C830AC,$44000094,$4518C4AC
$457DF494,$45FFFCAC,$44FDF894,$4438E0AC
$44000084,$43FFFF04,$47FFFF84,$4C0000C4
$518CCC24,$60000014,$7FFFFFFC,$7FFFFFFC
$00000000,$7FFFFF80,$7FFFFFC0,$7FFFFFE0
$7FFFFFF0,$7FFFFFF8,$7FFFFFFC,$7FFFFFFC
$7FFFFFFC,$7FFFFFFC,$7FFFFFFC,$7FFFFFFC
$7FFFFFFC,$7FFFFFFC,$7FFFFFFC,$7FFFFFFC
$7FFFFFFC,$7FFFFFFC,$7FFFFFFC,$7FFFFFFC
$7FFFFFFC,$7FFFFFFC,$7FFFFFFC,$7FFFFFFC
$7FFFFFFC,$7FFFFFFC,$7FFFFFFC,$7FFFFFFC
$7FFFFFFC,$7FFFFFFC,$7FFFFFFC,$7FFFFFFC

; Runtime Configuration for Macintosh

[[ CFIG,301
;  .I
; SCREEN buffer & Update method
;   2 = Text buffer with attributes
;   6 = Text buffer without attributes
;  10 = Text buffer exists but don’t use for
;automatic update
;  14 = Text buffer without attributes but
;don’t update
 DC.W 2 ; String Space growth rate
 DC.W 4096; File Buffer Space
 DC.W 4096; Document Width
 DC.W 640 ; Document Height
 DC.W 400 ; Border Width
 DC.W 40; Border Height
 DC.W 30; Horiz Point Scale * 16
 DC.W 16; Vert Point Scale * 16
 DC.W 16; Aspect *16
 DC.W 16; Default font
 DC.W 4 ; Default font size
 DC.W 12; Character cell Height
 DC.W 12; Character cell Width
 DC.W -1
]]

; File reference for program

$$ FREF,128 FREF resc, ID = 128
APPL    filetype
0local ID for icon list
|no filename follows the application

; File reference for document

$$ FREF,129 FREF resc, ID = 129
TEXT    filetype
1local ID for icon list
|no filename follows the application

; Bundle

$$ BNDL,128 bundle resc, ID = 128
PROF    the application’s signature again
0ID is again 0 by convention
2two resc types in the BNDL list:
ICN#,2  map one icon list:
0,128   local ID 0 -> actual ID 128
1,129
FREF,2  map one FREF list:
0,128   local ID 0 -> actual ID 128
1,129