*************************************************************************
* >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)
		  b31 set if help text present for 'no item selected' state
	#&10	Module offset of 'update menu code' (0 if none)
	#&14	Help text pointer (only present if b31 of width word set)
		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.

The menu text strings are MessageTrans tokens if the mode has its
MessageTrans flag bit set (see e_mode in E-Entry); however, the menu title is
taken as a literal string if it starts with a NUL (this NUL is then ignored).

The menu help data consists of (n+1) strings, where n is the number of
entries in the menu. Each string takes one of three forms:
  1. Literal string, NUL terminated
  2. Byte &1B (ESC), token name, NUL terminated
  3. Byte &01, unterminated.
Form 3 is a shorthand for repeating the most recent help string of
either of the other two forms.
The first string is for when the pointer is over the menu but not over a menu
entry; it cannot be of form 3. The second string is for the first menu 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
	#-16	= Pointer to menu help text block (0 if none).
		  This is of the form
		    +0   = ptr to 'no item' help text
		    +4   = ptr to item 0 help text
		    +8   = ptr to item 1 help text
		    +x   = ptr to item y help text
		    +x+4 = -1
		    +x+8 = the help text: one NUL-terminated string per entry
		  Pointers may be null (0) if there is no corresponding help
		  text.
	#-12	= Reserved for internal use. Menus not built by Zap_LoadMenu
		  must have this set to 0.
	#-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.
		  Otherwise this gives the address of user specific code to 
		   do the updating (see below).


	menu entry string buffer pointer
	#-16	= flags
		  b0-3 Parameter type for interpret code if it is a Command.
		       See E-Command bits 3-5
		  b30  Set if the submenu warning code is a Zap Command.
		  b31  Set if the interpret code is a Zap Command.
	#-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 b30 of #-16 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 b31 of #-16 is set then it is the address of a Zap
		   command to be executed when the menu entry is clicked on.
		  b0-3 of #-16 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.
