Hierarchical Menus from Forth

By Jörg Langowski, MacTutor Editorial Board, Grenoble, France

Feedback dept.

We got some interesting reader’s comments again, so before moving on to the main topic, I’ll open my mailbox. The first letter comes from Sweden, I got it after having sent off the September column, and here’s someone who can read thoughts:

“ I have used MacForth (level 1), NEON and I am now using MACH2, mainly as an instrument for trying out assembler subroutines and algorithms.

I found MacForth rather disappointing, it simply hides too much of the Mac environment and consequently you have to learn far too many special words. That could also be said of NEON of course, but this was a special case. I found the object oriented environment quite fascinating. I deliberately use the past tense, I have heard nothing from Kriya after the launching of the Mac Plus, NEON support seems to have stopped. MACH on the other hand is an excellent compromise, almost pure Forth, a reasonable Mac user interface, a very fine assembler and - a disassembler.

That brings me to the actual point of this letter, a suggestion for your MacTutor column. Dan Weston mentions FKEYs in his fantastic books but only in passing. So, I wanted to take a look at one of the regular ones in the system file. Lacking Nosy or anything similar, I opened FKEY 3 with ResEdit and transferred the data to my MACH editor. The data was then converted to DC.W strings and loaded into MACH. You can see the result of the disassembly in the enclosed copies. I believe it was worth the trouble, there seems to be quite a bit of interesting code there.

There ought to be a simpler way of doing this however, a small MACH program should make it easier to peek at code on disk and perhaps even in ROM. I could always buy NOSY of course, but I still think this is a rather nice idea for a MacTutor article!”

Bertil Holmberg

Well, Bertil, you’ll have been pleased to see that FKEYs have actually been treated in last month’s column. As to the disassembly problem, I think that your way of doing it is actually rather efficient, if one does not want to use Nosy. Another way to go would be to do a GetResource on the interesting piece of code (DRVR, FKEY, MDEF, etc ), get the address from the handle and then do a disassembly from Mach2 on the code block, using the IL word.

Another long letter deals with Mach2 features, and some bugs:

“I read your comparison of Mach2 and MacForth Plus in the April 1987 issue of MacTutor with great interest. I have used both systems and tend to agree with your conclusions. I particularly like two features of Mach2: the uniform toolbox access using CALL and the standard Motorola assembler syntax. I think in summary that the Mach2 system is more oriented towards the Macintosh and the 68000 than is the MacForth system.

I recently received the latest update to Mach2 (v2.11) [ok, it’s 2.13 as I write this - JL] from PASC that contains the integrated editor and several bug corrections. Unfortunately there are several bugs in the new system also. Specifically I noted the following:

(1) Editor

The editor leaves a lot to be desired - not the least of which is the single open window and 32K limitation (like MockWrite). It seems to me that this editor is only useful for single standalone files. For other situations I still use Edit2.1.

[Well, I must agree with your comments there. It is a shame that a powerful development system like Mach2 still lacks a reasonable integrated editor. At least multiple windows should be possible, and an MPW-like ‘worksheet’ conception, with command execution from within the Editor, would be really nice. When is someone going to port the excellent Sibley editor from MacForth into the Mach2 environment? My standard development system is Mach2.13 with its editor and MockWrite, plus Edit under Switcher if required. JL]

(2) IOTASK

The new system provides the source for the IOTASK code and allows you to replace the IOTASK with your own custom IOTASK. The IOTASK code needed to be modified in three places: (RUN-GROW) and (RUN-DRAG) do not have reasonable limits - you can shrink the window to a line and drag it off the screen. Also in (RUN-GROW), the window contents are erased if the window is made smaller [this has been fixed in 2.13 - JL]. I modified the IOTASK in these three areas and successfully replaced the IOTASK.

Another minor thing I noticed in the IOTASK code is that there is a location reserved at the end of the EVENT-RECORD for an empty menubar handle i.e.:

: EmptyMenuBar ( - a ) EVENT-RECORD $1E + ;

If your application has only one menubar, but multiple windows, you could place a handle to your menubar in this location as follows:

 MBarHandle @ EmptyMenuBar !

where MBarHandle is a handle to your menubar

then your menubar will always be present no matter which window is active. One of the things I didn’t like about the way Mach2 applications ran was that if you clicked in a window without a menubar a blank menubar resulted. The above words (including the EmptyMenuBar word) should be placed in your application code, not in the IOTASK code.

Now that we have the IOTASK source, wonder if we could get PASC to provide the multitasking Kernel source? [Let’s hope JL]

(3) The infamous 8 byte record from Quickdraw

I think this bug fix was well worth the update all by itself. There were several parts of my application that always crashed for unknown reasons when I tried to execute them in the interactive mode (but strangely enough did not crash or crashed very seldom after turnkeying). With this new version of Mach2 the crashes are gone. Therefore I would conclude that the use of the common stack area and the register exchange D4 <-> A7 before and after calls to the Toolbox fixed these problems.

I assume that you also have to include the register exchange lines of code in any assembler code where you call the toolbox [see this month’s example - JL]

One might ask whether the register exchange needs to be made for toolbox calls that are register based - i.e. ones that don’t use A7. However, many toolbox calls themselves make calls to other toolbox routines. Therefore, the safe approach seems to be to always put in the register exchange instructions.

(4) Subroutine stack space

The notes with the new Mach2 system state that you can make the subroutine stacks smaller (i.e. 1K rather than 8K) provided that there are no calls to LOADSEG after your program starts to run. I reduced the size of all my task subroutine stacks from 8K to 1K and the application appears to run OK. I am pretty sure that there are no calls to LOADSEG after the program is first initialized since I explicitly call initialization routines in all segments (so they all should be loaded at program startup).

I understand from PASC that they have a fix that avoids this problem - i.e. LOADSEG can be allowed with only 1K subroutine stacks. They will put this fix on GEnie RoundTable - however I think it would be worthwhile to publish this fix in MacTutor for those of us not on GEnie. [This fix is part of Mach2 v.2.12 and later; it is also contained on the source code disk. I am, however, checking how I can get access to GEnie from overseas - JL]

Other comments:

(1) Global variables

This does not have anything to do with the new Mach2 update but is just something I didn’t know. All variables are Global - i.e. you can access any variable from any segment without declaring it as global [this is logical since variable addresses are taken as offsets from A5, not PC-relative - JL]. The same is true of a constant. I’m not sure about CREATE though - is an array defined by CREATE globally accessible? [No. Any word defined within the segment space will not be globally accessible unless GLOBALized beforehand. This is true for colon definitions as well as for CREATE - JL].

(2) TMON

You mentioned in your April 87 MacTutor article that you used TMON for debugging Mach2 code. I tried TMON and was able to get into it ok (by using the interrupt switch), however when I attempted to get back to my application via Exit, TMON bounced me right back to the debugger screen with an illegal instruction. How do you get back to the application from TMON? [This error has not occured in any of my tests, sorry. 2.11 to 2.13 seem to work OK with TMON. Check the value of the DEBG resource in your Mach2 application. It should be =2 to make Mach2 collaborate with TMON - JL].

(3) Multitasking code

I have noticed that assembler code for the 68000 is not much more difficult to read than some high level languages. (In particular, I think that C is more cryptic than assembler level). [Aha! How about Forth? - JL]. However, if we want to write a multitasking application in assembly, we need a multitasking shell. Therefore I think a good article for MacTutor would be a multitasking shell written in assembly. It probably would not have to be as extensive as the Mach2 multitasker since it would be used for stand alone applications only. [Well, here’s an interesting task for our assembler specialists submissions welcome - JL].

Well, that’s all I have to say for now - keep up the good work in MacTutor. I find something useful in almost every month’s edition.” --James J. Merkel

[Thanks for these interesting comments on Mach2. I think PASC will have responded before you even read this ]

Hierarchical Menus

After this question-and-answer session, we’ll treat a subject that is closely connected with the new System 4.1 / Finder 5.5 release. The new system contains a new menu manager, which supports hierarchical menus. These are menus which can contain submenus associated with a menu item.

How does a hierarchical menu show up on the screen? Fig. 1 shows an example; the main menu item is followed by a small arrow, and if you leave the cursor on the item for some short time, the submenu appears to the side of the main item. Then, you can select an item from the submenu as usual.

Hierarchical menus can make the menu setup much more compact, and are therefore of great advantage if you have a lot of parameters that you want the user to change - like in a telecommunications program where you adjust baud rates, data formats and the like.

There is a certain procedure which you have to follow if you want to make use of such menus. I have implemented this procedure in Mach2, using the ‘dumb terminal’ program from the Mach2 example disk as a skeleton. The example will create a stand-alone terminal program which supports desk accessories and allows selection of parameters through a hierarchical menu as in Fig. 1.

Fig. 1 Miniterm example with hierarchical Menus

Creation of submenus

The requirements for using hierarchical menus are:

- 128K (or larger) ROMs;

- a menu definition routine with version number 10 or higher;

- the new menu manager (System 4.1 or higher);

- and the availability of the traps GetItemCmd ($A84E) and SetItemCmd ($A84F), these also being installed in System 4.1 or the 256K ROMs.

Second, there are some recommendations as to the use of hierarchical menus. Those menus, sub-menus, sub-sub-menus and so on may be nested up to 5 levels deep. There is actually a very instructive demo application floating around in network space that fills up the menu bar with a whole lot of hierarchical menus, one of which has the ‘quit’ command hidden in its deepest level. When you’ve finally managed to find it, you’ll know why it is recommended not to use more than one menu sublevel

Also, the commands in a sub-menu should be all of a similar group, so for instance, the settings of a certain parameter, predefined macros, text styles, etc.

What is a submenu? It is created like a regular menu, with its menu ID, title, and items. You can create its menu handle from a resource with GetMenu, or use NewMenu to create it from scratch. Once you have the handle, the call to InsertMenu determines whether it is inserted into the menu bar or stays ‘hidden’ for being displayed as a sub-menu. For sub-menus, you’ll have to call InsertMenu with beforeID = -1.

The submenu is then attached to a menu item in the following way:

- the itemCmd field of the menu item (that which contains the keyboard equivalent) has to contain $1B.

- the itemMark field (where the check mark character is kept) has to contain the ID of the submenu; since this field is one byte wide, this means that the submenu may never have an ID greater than 255.

Once these two conditions have been fulfilled, and the menu has been inserted in the proper way, the item of the main menu will contain the little arrow pointing to - and displaying - the submenu. Selections can be made in the submenu, and the routine MenuSelect will return the proper menu ID and item number.

Implementing the submenu in Forth

The example, Listing 1, is written in Mach2. The trick is that, even though menu handling is done on a level ‘hidden’ from the basic Mac interface, the system allows a menu insertion with beforeID = -1. This is done in the bounds parameter of the menu description. The trap SetItemCmd has to be redefined; notice the stack exchange D4 <-> A7 that is done before and after the trap call.

A submenu that has been properly created (by using -1 menuID menu BOUNDS) may then be inserted as a branch of a hierarchical menu with the word branch. The parameters are: the submenu ID, the main menu ID, and the ID of the item to which the submenu will be attached. branch first checks whether hierarchical menus are allowed, and if so, changes the itemMark and itemCmd fields of the main menu item so that it points to the submenu.

The rest of the listing is a terminal program which might come in handy as a skeleton for a more powerful telecommunication utility (you might for instance add some of the XMODEM routines that I described earlier).

The Apple menu contains an About item which will display an alert with ID=128 if present in a resource file. Our double-clickable version on the source code disk contains such an alert. If you don’t have that disk, get it, or create your own alert.

One last word

The ‘hacker story’ that I put in two months ago has created a lot of heated discussion with regards to the ethics of software use, licensing agreements, copy protection and the like. [As I write this I have not read any letters to MacTutor regarding this issue, but I’m sure they will come]. Most of the ‘ethics’ discussion, however, was not really to the point. The story was written from the ‘MacTutor Europe Branch’ point of view and meant as one example of the situation of software users vs. publishers on this side of the Atlantic. Namely, this situation still leaves a lot room for improvement. Major points are that copy protection is still considered normal here, software prices are comparatively high and support comparatively low, and many users are getting less than mediocre service without even realizing. A couple of us are at present organizing a group that will try to improve the relations between the three parties in the software business - developers, publishers, and users. This would mean in particular improving the flow of information (which product does what, has which bugs, can/cannot be recommended; getting bug reports back to developers and responses back quickly to users; reasonable update policies, etc.). As soon as this project gets out of the planning phase, I’ll tell you more about it.

Listing 1:   Example terminal program using hierarchical menus
\ routines for hierarchical menu support in Mach2
\ J. Langowski / MacTutor July 1987

\ The terminal emulation routines contained here have originally 
\ been created by Palo Alto Shipping Co. as an example on their 
\ Mach2 distribution disks. The code has been somewhat 
\ modified to integrate with the hierarchical menu example and 
\ to form a stand-alone application.

only forth also assembler also mac also i/o

108 USER TaskMenuBar
164 USER goaway-hook

$4D444546 CONSTANT “mdef
$44525652 CONSTANT “drvr

$28E  CONSTANT ROM85
$B5C  CONSTANT MenuMgrType
$A89F CONSTANT undefTrap

( *** menu record data structure *** )
 0 CONSTANT menuID ( integer )
 2 CONSTANT menuWidth( integer )
 4 CONSTANT menuHeight  ( integer )
 6 CONSTANT menuProc ( handle )
10 CONSTANT enableFlags   ( longint )
14 CONSTANT menuData ( Str255 and other data ) 
 ( *** menu Data format *** )
 ( counted string: menu title )
 ( followed by 1 to 31 times: )
 ( counted string: menu item  )
 ( byte: item icon # )
 ( byte: equivalent character )
 ( byte: check mark character )
 ( byte: text attributes )
 ( .... )
 ( end: zero byte. )

CODE setitemcmd
 EXG  D4,A7
 MOVE.L 8(A6),-(A7)
 MOVE.W 6(A6),-(A7)
 MOVE.W 2(A6),-(A7)
 ADDA.W #$C,A6
 _setItemCmd
 EXG  D4,A7
 RTS
END-CODE

CODE getitemcmd
 EXG  D4,A7
 MOVE.L 8(A6),-(A7)
 MOVE.W 6(A6),-(A7)
 MOVE.L (A6),-(A7)
 ADDA.W #$C,A6
 _getItemCmd
 EXG  D4,A7
 RTS
END-CODE

: newrom? rom85 w@ l_ext 0> ;

: newmenus? MenuMgrType @ -1 <> ;

: getItemCmd?  
$A84E call gettrapaddress undefTrap call gettrapaddress <> ;

: MDEF-version “mdef 0 call getresource @ 10 + w@ ;

: branch.menu { subID mainID item# | mainmenu submenu -- }
 newrom? 
 newmenus? AND
 getItemCmd? AND
 MDEF-version 9 > AND
 IFmainID call getMHandle -> mainmenu
 mainmenu 0= abort” Main menu does not exist”
 subID  call getMHandle -> submenu
 submenu 0= abort” Submenu does not exist”
 mainmenu item# subID call setitmmark
 mainmenu item# $1B setItemCmd
 ELSE
 1 abort” System does not support hierarchical menus” 
 THEN
;

Variable baud#
Variable data#
Variable stop#
Variable parity#
Variable hsk#
Variable DAName

400 8000 terminal EMULATOR
NEW.WINDOW TERM
“ Terminal” TERM TITLE
45 25 335 475 TERM BOUNDS
DOCUMENT VISIBLE GROWBOX CLOSEBOX TERM ITEMS

NEW.MBAR TermMenuBar

200 CONSTANT Apple_ID
create apple_string $01 c, $14 c,
NEW.MENU Apple_menu
apple_string Apple_menu TITLE
0 200 Apple_menu BOUNDS
“ About Terminal ;(-” Apple_menu ITEMS

300 CONSTANT Term_ID
NEW.MENU Term_menu
“ Terminal” Term_menu TITLE
0 Term_ID Term_menu BOUNDS
“ Rate;Format;Parity;Handshake;Quit” Term_menu ITEMS

129 CONSTANT baud_ID
NEW.MENU baud_menu
“ Rate” baud_menu TITLE
-1 baud_ID baud_menu BOUNDS \ insert as hierarchical menu
“ 300;600;1200;1800;2400;3600;4800;7200;9600;19200”
  baud_menu ITEMS

130 CONSTANT form_ID
NEW.MENU form_menu
“ Format” form_menu TITLE
-1 form_ID form_menu BOUNDS \ insert as hierarchical menu
“ 5 data;6 data;7 data;8 data;(-;1 stop;1.5 stop;2 stop”
  form_menu ITEMS

131 CONSTANT parity_ID
NEW.MENU parity_menu
“ Parity” parity_menu TITLE
-1 parity_ID parity_menu BOUNDS \ insert as hierarchical menu
“ none;odd;even” parity_menu ITEMS

132 CONSTANT hsk_ID
NEW.MENU hsk_menu
“ Handshake” hsk_menu TITLE
-1 hsk_ID hsk_menu BOUNDS \ insert as hierarchical menu
“ none;xon-xoff;cts” hsk_menu ITEMS

: do.config
 baud# @ CASE
  1 OF $17C ENDOF
  2 OF $BD  ENDOF
  3 OF $5E  ENDOF
  4 OF $3E  ENDOF
  5 OF $2E  ENDOF
  6 OF $1E  ENDOF
  7 OF $16  ENDOF
  8 OF $E   ENDOF
  9 OF $A   ENDOF
 10 OF $4   ENDOF
 ENDCASE
 
 data# @ CASE
  1 OF $0   ENDOF
  2 OF $800 ENDOF
  3 OF $400 ENDOF
  4 OF $C00 ENDOF
 ENDCASE
 +

 stop# @ CASE
  6 OF $4000 ENDOF
  7 OF $8000 ENDOF
  8 OF $C000 ENDOF
 ENDCASE
 +

 parity# @ CASE
  1 OF $0    ENDOF
  2 OF $1000 ENDOF
  3 OF $3000 ENDOF
 ENDCASE
 +

 hsk# @ CASE
  1 OF $0     ENDOF
  2 OF $10000 ENDOF
  3 OF $20000 ENDOF
 ENDCASE
 +
 comm1 MODE IF 10 call sysbeep THEN
;

: init.menus
 TermMenuBar ADD
 TermMenuBar Apple_menu ADD
   Apple_menu @ “drvr CALL AddResMenu 
 TermMenuBar term_menu ADD
 TermMenuBar baud_menu ADD
 TermMenuBar form_menu ADD
 TermMenuBar parity_menu ADD
 TermMenuBar hsk_menu ADD
 baud_ID   term_ID 1 branch.menu
 form_ID   term_ID 2 branch.menu
 parity_ID term_ID 3 branch.menu
 hsk_ID    term_ID 4 branch.menu
 baud_menu   @ 9 -1 call checkitem
 form_menu   @ 4 -1 call checkitem
 form_menu   @ 8 -1 call checkitem
 parity_menu @ 1 -1 call checkitem
 hsk_menu    @ 1 -1 call checkitem
 9 baud# !
 4 data# ! 8 stop# !
 1 parity# ! 1 hsk# !
 do.config
;

: do.about 128 0 CALL alert drop ;

: do.apple   { item# }
 \ item# = 1 (About...)?
 item# 1 =  
 IFdo.about
 ELSE
 Apple_menu @ item# DAName CALL GetItem
 DAName CALL OpenDeskAcc DROP
 THEN ;

: do.baud 
 baud_menu @ over -1 call checkitem
 baud_menu @ baud# @ 0 call checkitem
 baud# !
;
 
: do.format
 form_menu @ over -1 call checkitem 
 dup 5 < IF
 form_menu @ data# @ 0 call checkitem
 data# !
 ELSE
 form_menu @ stop# @ 0 call checkitem
 stop# !
 THEN
;
: do.parity 
 parity_menu @ over -1 call checkitem
 parity_menu @ parity# @ 0 call checkitem
 parity# !
;
: do.hshake 
 hsk_menu @ over -1 call checkitem
 hsk_menu @ hsk# @ 0 call checkitem
 hsk# !
;
: do.term 
 CASE
 5 OF bye ENDOF
 ENDCASE
;
: termmenuhandler ( item# menuID -- )
 CASE
 apple_ID OF do.apple  ENDOF
 baud_ID  OF do.baud   ENDOF
 form_ID  OF do.format ENDOF
 parity_ID  OF do.parity ENDOF
 hsk_ID OF do.hshake ENDOF
 term_IDOF do.term   ENDOF
 ENDCASE
 do.config
 0 call hilitemenu
;
( terminal emulator code from PAS starts here )

$0A CONSTANT LINE_FEED  ( ascii ‘linefeed’ )
$20 CONSTANT SP  ( ascii ‘space’ )

VARIABLE inputbuffer
64 VALLOT ( 68 bytes for holding modem input)

: emit>console ( n - )  ( send a single character to the screen )
 CONSOLE OUTPUT
 EMIT ;
: emit>modem ( n - )  ( send a single character to the modem port)
 COMM1 OUTPUT
 EMIT ;
: ?comm1 ( - n ) ( this word will determine if the Modem Port )
 COMM1 INPUT
 ( has received any characters. The number returned )
 ?TERMINAL ;   
 ( will indicate the number of characters waiting. )
   
: @comm1 ( - n ) ( this word will read one character from the )
 COMM1 INPUT
 ( modem port. If no characters are ready, this )
 KEY ;  ( word will wait. The task will be put to sleep )
 ( and awaken when the ioCompletion routine is )
 ( executed upon receiving a character. )
( type>screen is an enhanced version of the normal TYPE
 routine. )
( this word will filter out linefeeds. A linefeed is printed on )
( the Macintosh as a square box. )
: type>screen { address length } 
 length 0 DO 
  address I + C@ ( throw away 8th bit )
  $7F AND
  address I + C!
  
  address I + C@ LINE_FEED =
 ( look for a Linefeed)
 IF
     sp address I + C!   ( replace LF with SP)
 THEN
  LOOP
  CONSOLE OUTPUT 
  address length TYPE ; ( type out the modified string)

: monitor-modem { | temp }
        ?comm1   ( how many characters are ready ? )
 ?DUP   ( Note: The maximum # of chars must be)
 ( less than 64. This is the default size)
 ( of the Serial Driver buffer. )
 IF
     -> temp     ( save number of unread characters )
     COMM1 INPUT
     inputbuffer temp EXPECT
 ( receive characters from modem)
     inputbuffer temp type>screen  
 ( send this string to screen)
 THEN ;

: goaway-handler bye ;
: PopUp ( - )
 Term dup CALL showwindow CALL selectwindow ;
: start-comm
  ACTIVATE
 ( assign the following code to EMULATOR )
  [‘] termmenuhandler menu-vector !
  [‘] goaway-handler goaway-hook !
         Popup
  termmenubar @ call setmenubar call drawmenubar
  CLS
  CONSOLE OUTPUT .” Ready >” CR
  BEGIN
   CONSOLE INPUT 
   ?TERMINAL     ( has the user pressed a key ? )
   IF
     KEY emit>modem  ( send char to modem. ‘no local echo’ )
   THEN
    monitor-modem( watch the serial port)
  AGAIN 
;
: MODEM 
 term ADD ( make the term window )
 term EMULATOR BUILD 
 ( tie the term window to the EMULATOR task )
 init.menus
 TermMenuBar emulator mbar>task
 EMULATOR start-comm ;  ( launch task )