************************************************************************* * >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. 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.