*************************************************************************
* >E-Menu	Documents Zaps internal menu format			*
*************************************************************************

If you are writing your own mode then you may add your own menu to appear off
the the mode menu. See the C mode for an example.

You are asked to give an offset to a 'Zap menu structure' at offset e_menu in
the mode table. This file documents the format of this structure.
Alternatively you may wish to use the e_init entry point to set up your own
menu from a menus file. The structure pointed to by e_menu is of the form:

	#&00	Menu name (12) (zero terminated)
	#&0C	Menu width (os coords)
	#&10	Module offset of 'update menu code' (0 if none)
	#&14	Menu entries (x n)
		-1 to terminate list of entries

Each menu entry is of the form:

	#&00	Flags:	b0-b7	Menu flags as for wimp. ie,
			b0	Display tick to left of item
			b1	Dotted line follows
			b2	item writable
			b3	generate submenu warning message (see below)
			b4-b6	reserved
			b7	ignored
			b8-b15	Minimum buffer size to reserve for this menu
				entry (eg writable icon).
			b16-b23	Reserved - set to 0
			b24-b31	Icon colours / 0 for default
	#&04	Submenu pointer:
		If the submenu warning bit is clear then:
			0=none
			>0 =offset in module of submenu (same structure).
		If the submenu warning bit is set then this gives the module
		offset of the code to be called to open the submenu (see
		below).
	#&08	Index word. This is a 'handle' for this menu entry which is
		passed to the interpret code so the same interpret code
		can be used for several menu entries. Contrary to the
		documentation in previous versions this handle is treated
		as a module offset (if non 0) and updated to an address
		before being passed to your interpret code.
	#&0C	Module offset of the interpret code to call when menu 
		clicked on. (0 if none)
	#&10	Text for this entry (0 terminated string of any length)
	ALIGN before next entry.

This structure is relocatable and thus can be stored directly in your mode
extension module. When Zap is run, it converts it into a standard wimp menu
with all menu entries being indirected strings. The size of the indirected
string buffer is set to that of the text for the entry unless offset #4
specifies a greater amount. The other values are stored at negative offsets
from the standard wimp structure:

	menu pointer
	#-8	= Counter giving time menu last updated. Used internally.
		  Should initially be 0.
	#-4	= Descriptor saying how the menu should be updated when
		  opened.
		  If 0 then default code used - commands attached to menu
		   entries are polled for their tick state - see E-Commands.
		  If b31 clear then this gives the address of user specific
		   code to do the updating (see below).
		  If b31 set then the menu contains some 'transient' items
		   (see E-Commands bit 20) and this points to a master
		   copy of the menu before the items have been removed.
		   This is only used internally by Zap.

	menu entry string buffer pointer
	#-12	= Address of subroutine to handle submenu creation:
		  If 0 then it assumes the submenu pointer is valid
		  If >0 then it is the address of code to call to get the
		   leaf window or menu (see below for entry/exit conditions)
		  If the top bit is set then it is the address of a Zap
		   command to be called with R2=16. (see E-Commands)
	#-8	= Index word (or command data if b31 of #-4 set)
	#-4	= Address of routine to perform menu action:
		  If 0 then no action is taken if the entry is clicked on.
		  If >0 then it is the address of the interpret code to call
		   (see below for entry/exit conditions)
		  If the top bit is set then it is the address of a Zap
		   command to be executed when the menu entry is clicked on.
		  b27-30 indicate the supplied parameter type: as for b3-5
		  of command flags word, with 8=int expr 9=str expr

The update menu sub is called when the menu is created to update the 'ticks'
etc. This is called when a menu is created/recreated. The entry/exit
conditions are:

	\E	R0=offset of this menu in previous menu
		R6=w_format value (opt_format if R8=0)
		R7=w_flags value (opt_flags if R8=0)
		R8/R9=window (or 0 if called from iconbar menu)
		R10=address of the start of the wimp menu structure
		R11<>your workspace
	\X	You may corrupt R0-R11 VS on error etc

The interpret code is called when the menu is clicked on. Adjust clicks etc
are handled automatically. Perform the menu action. The update code will be
called again if the menu is recreated. The entry/exit conditions are:

	\E	R0=offset in menu (=R11!-4)
		R1=index word (=R10!-8)
		R2=address of menu item start
		R3=address of previous menu item start
		R6=w_format value (opt_format if R8=0)
		R7=w_flags value (opt_flags if R8=0)
		R8/R9=window (or 0 if called from iconbar menu)
		R10=address of text for this menu item
		R11=end of list of menu offsets as returned by the wimp
	\X	You may corrupt R0-R11 VS on error etc

The menu warning code is called when the menu warning bit is set and Zap gets
a menu warning message. It has entry/exit conditions:

	\E	R5=offset of this item in the (now previous) menu
		R8/R9=window (or 0 if called from iconbar menu)
		R10=address of text for this menu item
		R11=menu warning block as returned by the wimp
	\X	R1=pointer to submenu (in wimp format with values at negative
		offsets as described above)
		OR window handle of leaf window to be opened.
		OR 0 in case of an error/not being able to create it.

All leaf windows should be warned and opened by returning R1 as the leaf
window handle.

Note, after the menu has been converted to wimp format (as described above)
then all submenus are warned so that the 'update menu code' is only called
when that particular submenu is opened. Hence you can have menus used
repeatedly at several different places in the tree with different options on
each.
