|
Volume Number: | 3 | |
Issue Number: | 10 | |
Column Tag: | Forth Forum |
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
Malmö, Sweden
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 )
- SPREAD THE WORD:
- Slashdot
- Digg
- Del.icio.us
- Newsvine