Call Box Commands
Version 2.0 15 Jan-90


CALL ME the MENU commands

Menus are high level tool functions which are dependent on other toolbox functions as well as GS/OS (ProDOS16) commands. The menu functions need to be initialized by using the "high level" startup command CALL TL,2,"Desk" (see CAll TL in this manualfor a complete description). This call will stanup all tools needed for desktop applications ... the Menu Manager is one of them.

Menus are designated as "entities" in the Call Box BASIC driver and these entities are created using the Call Box TPS Menu Editor. The output type "object" must be used for menus that are to be used by the BASIC driver.


Figure 2.9
Figure 2.9 A Menu entity

There are different kinds of menus, some of which appear in windows, behind buttons (pop-ups) or in most any other location. The BASIC driver directly supports the "System Menu" which is the menu that appears across the top of the screen when you have a desktop application active. The first item in a system menu bar is the "Apple" selection. This menu bar selection is where NDA's can be selected from ... simply have this selection avaliable and the BASIC driver (and GS/OS) will put all of the NDAs in your system/desk.aces folder in this menu.

Operating a Menu is automatic, you must load it and open it. The window manager actually operates the menu and the menu item numbers are returned with TaskMaster (see CALL EV) calls in the main loop of your program.

Menu Items and Item I.D. 's
I.D. numbers are automatically assigned by the Call Box Menu Editor when you create a menu. There are 3 ranges of 1.0. numbers, each one handles a different group of menu items.

ID's 1 thru 249 are reserved for menu bar items.

ID's 250 thru 255 are for the Standard EDIT menu which supports NDA's with the functions UNDO, CUT, COPY, PASTE, CLEAR and CLOSE.

ID's 256 and up are for menu items

If you create a menu bar which has (from left to right) colored Apple, File, Alter, Special, and Goodies then the File would be I.D. #1, Alter would be I.D. #2, Special would be I.D. #3 and Goodies would be I.D. #4. The menus that these menu bar titles select follow the same rules but the numbering starts at 256 instead of 1. Suppose that this menu had an About... item under the colored Apple, a Load ... a Save ... and a Quit under the File, Create and Destroy under the Alter and Midnight under Special. The I.D. for About... would be 256, Load ... would be 257, Save ... would be 258, Quit would be 259, Create would be 260, etc. etc.

Standard Edit Menu
This menu is avaliable to accomodate special functions reserved by Apple for the Human Interface of the toolbox. The functions UNDO, CUT, COPY, PASTE, CLEAR and CLOSE have been given special 1.0. numbers (250 thru 255) which never change. Whenever a system window is up (like NDA's) these menu items should become selectable ... when there is no system window active then they should be un-selectable (dimmed). Check Menu (CALL ME,2 ,oo) will activate or de-activate these menu items depending on whether there is a system window active at the time. Place this call in your programs event loop if you are using a Standard Edit Menu.

The Un-Hilite Consideration
When a menu is "pulled-down" the menu bar item is hi-lited (white on black or inverted) and if you select a menu item the item blinks and then the menu closes. At this point you would do the task specified by the menu item. All this time however the menu bar item remains hi-tited and never unhilites. This works that way so that you can see by looking at the menu bar that a process is still going on. When your task is complete you must un-hilite this menu bar item yourself... (using the D value from the TaskMaster call)

V = INT(D/65536) : CALL ME, 7 ,N, V ,0

Failure to do this will result in items randomly being hilited or un-hilited ... a real mess, just remember to handle this little detail and everything will look good.

Menu Operation

After starting-up and initializing Call Box BASIC load a Menu entity created by the Call Box Menu Editor.

10 CALL ME,O,N,"MyMenu"

Next you need to build and display the menu, adding in any NDA's in the colored Apple menu bar selection.

12 CALL ME,1,N

Menus are actually operated by the Window Manager, all you do is check TaskMaster and see if a mouse click or event happened in the system menu bar (Task Code = 17) and take some action based on the menu item I.D. returned in the data variable of the TaskMaster call. If the Task Code indicates a 17 then derive the menu item I.D. and the menu bar item LD. from the TaskMaster data value.:

(Menu Bar item I.D.) = INT(D/65536)
(Menu item I.D.) = D - INT(D/65536}*65536

Menu Commands
There are 10 commands that control menus. Menus must be used only when the desktop is active. (see CALL WN in this manual for a complete description)

COMMAND FUNCTION DESCRIPTION
CALL ME,O,N,"pathname" LOAD MENU: this will load a menu from disk as entity (N = 1-31).
CALL ME,1,N OPEN MENU: this builds and displays the system menu.
CALL ME,2,N CHECK MENU: this hilites or un-hilites the standard Edit menu functions.
CALL ME,3,N CLOSE MENU: this removes the menu from the screen.
CALL ME,4,N,V VISIBLE MENU: this will show (V = 1) or hide (V = 0) the menu.
CALL ME,5,N,I,V ENABLEIDISABLE ITEM: this will enable (V = 1) or disable (V = 0) the menu item specified by (I).
CALL ME,6,N,I,V SYMBOL ITEM: this puts no symbol (V = 0) or a check mark (V = 1) or an ASCII symbol (V = 2-255) to the left of menu item specified by (I).
CALL ME,7,N,I,V HILITE/UNHILITE ITEM: this hilites (V = 1) or unhilites (V = 0) the menu item specified by (I) .
CALL ME,8,N,I,V STYLE ITEM: this sets the text style (V) (see CALL TX) of the menu item specified by (I).
CALL ME,9,N,P GET POINTER: this returns the pointer to the menu manager port.


N
Entity number for this menu (1-31)

I
Item number of an item in the current menu.

V
The value to fetch or put for an item, or action to take.

P
The pointer of the menu manager port.

"pathname"
This is the ProDOS patbname of a menu (filetype $B1 ... $BF) created with the Call Box IPS Menu Editor.