home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / z / zap / !Zap / Docs / E-Menu < prev    next >
Encoding:
Text File  |  1995-06-19  |  5.7 KB  |  133 lines
  1. *************************************************************************
  2. * >E-Menu    Documents Zaps internal menu format            *
  3. *************************************************************************
  4.  
  5. If you are writing your own mode then you may add your own menu to appear off
  6. the the mode menu. See the C mode for an example.
  7.  
  8. You are asked to give an offset to a 'Zap menu structure' at offset e_menu in
  9. the mode table. This file documents the format of this structure.
  10. Alternatively you may wish to use the e_init entry point to set up your own
  11. menu from a menus file. The structure pointed to by e_menu is of the form:
  12.  
  13.     #&00    Menu name (12) (zero terminated)
  14.     #&0C    Menu width (os coords)
  15.     #&10    Module offset of 'update menu code' (0 if none)
  16.     #&14    Menu entries (x n)
  17.         -1 to terminate list of entries
  18.         
  19. Each menu entry is of the form:
  20.  
  21.     #&00    Flags:    b0-b7    Menu flags as for wimp. ie,
  22.             b0    Display tick to left of item
  23.             b1    Dotted line follows
  24.             b2    item writable
  25.             b3    generate submenu warning message (see below)
  26.             b4-b6    reserved
  27.             b7    ignored
  28.             b8-b15    Minimum buffer size to reserve for this menu
  29.                 entry (eg writable icon).
  30.             b16-b23    Reserved - set to 0
  31.             b24-b31    Icon colours / 0 for default
  32.     #&04    Submenu pointer:
  33.         If the submenu warning bit is clear then:
  34.             0=none
  35.             >0 =offset in module of submenu (same structure).
  36.         If the submenu warning bit is set then this gives the module
  37.         offset of the code to be called to open the submenu (see
  38.         below).
  39.     #&08    Index word. This is a 'handle' for this menu entry which is
  40.         passed to the interpret code so the same interpret code
  41.         can be used for several menu entries. Contrary to the
  42.         documentation in previous versions this handle is treated
  43.         as a module offset (if non 0) and updated to an address
  44.         before being passed to your interpret code.
  45.     #&0C    Module offset of the interpret code to call when menu 
  46.         clicked on. (0 if none)
  47.     #&10    Text for this entry (0 terminated string of any length)
  48.     ALIGN before next entry.
  49.     
  50. This structure is relocatable and thus can be stored directly in your mode
  51. extension module. When Zap is run, it converts it into a standard wimp menu
  52. with all menu entries being indirected strings. The size of the indirected
  53. string buffer is set to that of the text for the entry unless offset #4
  54. specifies a greater amount. The other values are stored at negative offsets
  55. from the standard wimp structure:
  56.  
  57.     menu pointer
  58.     #-8    = Counter giving time menu last updated. Used internally.
  59.           Should initially be 0.
  60.     #-4    = Descriptor saying how the menu should be updated when
  61.           opened.
  62.           If 0 then default code used - commands attached to menu
  63.            entries are polled for their tick state - see E-Commands.
  64.           If b31 clear then this gives the address of user specific
  65.            code to do the updating (see below).
  66.           If b31 set then the menu contains some 'transient' items
  67.            (see E-Commands bit 20) and this points to a master
  68.            copy of the menu before the items have been removed.
  69.            This is only used internally by Zap.
  70.                
  71.     menu entry string buffer pointer
  72.     #-12    = Address of subroutine to handle submenu creation:
  73.           If 0 then it assumes the submenu pointer is valid
  74.           If >0 then it is the address of code to call to get the
  75.            leaf window or menu (see below for entry/exit conditions)
  76.           If the top bit is set then it is the address of a Zap
  77.            command to be called with R2=16. (see E-Commands)
  78.     #-8    = Index word (or command data if b31 of #-4 set)
  79.     #-4    = Address of routine to perform menu action:
  80.           If 0 then no action is taken if the entry is clicked on.
  81.           If >0 then it is the address of the interpret code to call
  82.            (see below for entry/exit conditions)
  83.           If the top bit is set then it is the address of a Zap
  84.            command to be executed when the menu entry is clicked on.
  85.  
  86. The update menu sub is called when the menu is created to update the 'ticks'
  87. etc. This is called when a menu is created/recreated. The entry/exit
  88. conditions are:
  89.  
  90.     \E    R0=offset of this menu in previous menu
  91.         R6=w_format value (opt_format if R8=0)
  92.         R7=w_flags value (opt_flags if R8=0)
  93.         R8/R9=window (or 0 if called from iconbar menu)
  94.         R10=address of the start of the wimp menu structure
  95.         R11<>your workspace
  96.     \X    You may corrupt R0-R11 VS on error etc
  97.     
  98. The interpret code is called when the menu is clicked on. Adjust clicks etc
  99. are handled automatically. Perform the menu action. The update code will be
  100. called again if the menu is recreated. The entry/exit conditions are:
  101.  
  102.     \E    R0=offset in menu (=R11!-4)
  103.         R1=index word (=R10!-8)
  104.         R2=address of menu item start
  105.         R3=address of previous menu item start
  106.         R6=w_format value (opt_format if R8=0)
  107.         R7=w_flags value (opt_flags if R8=0)
  108.         R8/R9=window (or 0 if called from iconbar menu)
  109.         R10=address of text for this menu item
  110.         R11=end of list of menu offsets as returned by the wimp
  111.     \X    You may corrupt R0-R11 VS on error etc
  112.     
  113. The menu warning code is called when the menu warning bit is set and Zap gets
  114. a menu warning message. It has entry/exit conditions:
  115.  
  116.     \E    R5=offset of this item in the (now previous) menu
  117.         R8/R9=window (or 0 if called from iconbar menu)
  118.         R10=address of text for this menu item
  119.         R11=menu warning block as returned by the wimp
  120.     \X    R1=pointer to submenu (in wimp format with values at negative
  121.         offsets as described above)
  122.         OR window handle of leaf window to be opened.
  123.         OR 0 in case of an error/not being able to create it.
  124.  
  125. All leaf windows should be warned and opened by returning R1 as the leaf
  126. window handle.
  127.  
  128. Note, after the menu has been converted to wimp format (as described above)
  129. then all submenus are warned so that the 'update menu code' is only called
  130. when that particular submenu is opened. Hence you can have menus used
  131. repeatedly at several different places in the tree with different options on
  132. each.
  133.