home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / utilities / utilst / wimpres / Modules / MenuUtil / SWIs < prev   
Text File  |  1993-01-23  |  25KB  |  719 lines
  1.  
  2.  
  3.              Documentation for the MenuUtils module v.0.10
  4.  
  5.                        © Petrov Software 1992
  6.  
  7.                                 
  8.  
  9.                          Description of SWIs
  10.  
  11. SWI chunk prefix for the MenuUtils module is MenuUtil_ and base number
  12. is &45BC0. My thanks to Acorn for the allocation of SWI chunk.
  13.  
  14.           Module MenuUtils provides the following SWIs:
  15.  
  16.                         "MenuUtil_Initialise"    
  17.                         "MenuUtil_New"           
  18.                         "MenuUtil_Add"           
  19.                         "MenuUtil_Delete"  
  20.                         "MenuUtil_Decode"
  21.                         "MenuUtil_Show"    
  22.                         "MenuUtil_ShowSubMenu" 
  23.                         "MenuUtil_Info"    
  24.                         "MenuUtil_Text"    
  25.                         "MenuUtil_Tick"
  26.                         "MenuUtil_Dots"    
  27.                         "MenuUtil_Fade"    
  28.                         "MenuUtil_Warning" 
  29.                         "MenuUtil_Writable"
  30.                         "MenuUtil_SubMenu" 
  31.                         "MenuUtil_ColourMenu"  
  32.                         "MenuUtil_Colours" 
  33.                         "MenuUtil_TickOnly"
  34.  
  35. All calls to MenuUtils module (with the exception of
  36. MenuUtil_Initialise and MenuUtil_New) expect in R0 the handle of the menu
  37. or of the menu item. If the handle is omitted (R0=0) then the current menu
  38. or current menu item is assumed (interpretation depends on particular SWI).  
  39.  
  40.  
  41.  MenuUtil_Initialise (SWI &45BC0)
  42.  --------------------------------
  43.  To register the task as MenuUtils client
  44.  
  45.  Entry:
  46.      R0 last MenuUtils version number known to task * 100                
  47.      R1 initialisation type (see later)
  48.         bit 0
  49.             0 - "BASIC"
  50.             1 - "machine code" (not supported by current version)
  51.  Exit:
  52.      R0 version number * 100
  53.      R1,R2 preserved     
  54.  
  55. MenuUtil_Initialise should only be called once when the task starts up. It
  56. must be called after Wimp_Initialise has been called and before any
  57. other call to the MenuUtils module is made.
  58.  
  59. MenuUtils performs all the closedown work automatically when the
  60. task finishes so no special MenuUtil_CloseDown SWI is provided.
  61.  
  62.  Example code:
  63.  Register the task with any version of the module
  64.  SYS "MenuUtil_Initialise"
  65.  
  66.  
  67.  
  68.  MenuUtil_New (SWI &45BC1)
  69.  -------------------------
  70.  Creates new empty menu.
  71.  
  72.  Entry:
  73.      R1 pointer to menu title string
  74.      R2 approximate number of items (default 5)
  75.  
  76.  Exit:
  77.      R0 handle of created menu
  78.     
  79. This call creates new empty menu with specified title string. Colours
  80. and dimensions of the menu are in standard RISC OS style. You can
  81. specify number of items you are going to have in this menu. This is
  82. optional but it can speed up the process of menu creation. It
  83. may be important for big menus (for example for oldstyle fonts menu).
  84.  
  85. As Window Manager doesn't allow you to have menus absolutely without
  86. menu items so each new menu is created together with one special item.
  87. This item is created with the only aim to prevent crashes in case you
  88. will accidentially try to open unfinished menu. The special item will
  89. be removed automatically just after you add your first item to this
  90. menu.
  91.  
  92. If your program has complex menu structure with submenus then you can
  93. use this call to create not only main menu but also all submenus. And
  94. you have to remember the handles of all submenus in order to link them
  95. later to corresponding menu items in parent menu. If on the other hand
  96. your program have only one menu without submenus then you may ignore
  97. the returned menu handle because it will be anyway used as default in
  98. all future calls to MenuUtils.
  99.  
  100. After this call the new menu becomes the current menu.
  101.  
  102.  Example code:
  103.  Start construction of simple menu like one in Palette Utility
  104.  SYS "MenuUtil_New",,"Palette" 
  105.  
  106.  If you program has complex menu structure (like Source Editor) then you
  107. have to remember the handles of all submenus
  108.  SYS "MenuUtil_New",,"SrcEdit" TO mainMenu%
  109.  SYS "MenuUtil_New",,"Display" TO dispMenu%
  110.  SYS "MenuUtil_New",,"Fonts",200  TO fontsMenu%
  111.  
  112.            
  113.  
  114.  
  115.  MenuUtil_Add (SWI &45BC2)
  116.  -------------------------
  117.  Adds new item to existing menu.
  118.  
  119.  Entry:
  120.      R0 handle of the menu or of the menu item or zero for current menu
  121.      R1 pointer to item text
  122.      R2 pointer to item handler
  123.  
  124.  Exit:
  125.      R0 handle of menu item
  126.      R1,R2 preserved
  127.  
  128.  
  129. This call adds one item to the existing menu. If handle is the handle
  130. of menu then new item will be added to the end of this menu. If handle
  131. is the handle of the item then new item will be inserted into menu
  132. just before this item. If R0 is zero on entry then item will be added
  133. to the end of current menu.
  134.  
  135. During this call the current menu may be moved in memory so if you
  136. keep direct pointers to the menu data structure they may become
  137. invalid. On the other hand if there are any menu items linked with
  138. this menu by means of MenuUtil_Submenu then all pointers will be
  139. recalculated automatically by the module and will remain valid.
  140.  
  141. MenuUtils makes his own copy of the string pointed to by R1 but
  142. inspite of this you still can easily change it with MenuUtil_Text. If R1
  143. is zero on entry then null string ("") will be used as item text.
  144.  
  145. If R2 is not zero on entry then interpretation of it contents depends
  146. on the initialisation type specified early during the call to
  147. MenuUtil_Initialise. If initialisation type was specified as "BASIC" then
  148. it is assumed that R2 is a pointer to the ctrl-terminated text string.
  149. In this case the module makes his own copy of the string for later use
  150. in MenuUtil_Decode. If initialisation type was "machine code" (not
  151. supported by current version) then only the contents of R2 is saved by
  152. the module. This feature allows you to attach a handler to the menu
  153. item. In case of "BASIC" you can provide the name of BASIC function.
  154. In case of "machine code" - the address of ARM subroutine. See also
  155. MenuUtil_Decode and for possible use of item handlers.
  156.                
  157.  
  158.  Example code:                              
  159.  
  160.  Add item "Info" to the current menu
  161.  SYS "MenuUtil_Add",,"Info" TO infoItem%    
  162.  
  163.  Add item "Quit" and then insert item "Create" just before it.  Let's
  164. the first item will have the handler. The handler is assumed to be
  165. BASIC function FNquit. (See MenuUtil_Decode on how this handler may be
  166. called) 
  167.  SYS "MenuUtil_Add",,"Quit","quit" TO quitItem%
  168.  SYS "MenuUtil_Add",quitItem%,"Create" TO createItem%                                  
  169.  Create menu similar to Display submenu in Filer. When items are added
  170. to current menu menu handle (dispMenu%) may be omitted as it will be
  171. used by default.
  172.  SYS "MenuUtil_New",,"Display" TO dispMenu%
  173.  SYS "MenuUtil_Add",,"Large icons" TO largeItem%
  174.  SYS "MenuUtil_Add",,"Small icons" TO smallItem%
  175.  SYS "MenuUtil_Add",,"Full info" TO fullItem%
  176.  
  177.           
  178.  
  179.  
  180.  MenuUtil_Delete (SWI &45BC3)
  181.  ----------------------------
  182.  Removes menu or menu item
  183.  
  184.  Entry:
  185.      R0 = handle of the menu or of the menu item or zero for current menu
  186.      if R1<>0 then recursively delete all submenus 
  187.  Exit:
  188.      R0,R1 preserved
  189.  
  190. This call allows you to delete the whole menu or the particular menu item.
  191. If you will delete menu item then remained items of this menu which are
  192. positioned bellow it will be automatically shifted in memory to fill the
  193. hole. Despite the fact that memory location and position in menu of some
  194. items may be changed the handles of the items will remain valid.
  195.  
  196. If you want to delete not only the item but also the whole menu subtree
  197. connected with it then you must set R1<>0 on entry. If R0 contains the
  198. handle of menu then this menu will be deleted alone or together with all
  199. submenus depending on R1. 
  200.  
  201. Use recursive deletion with caution as you may accidentally delete
  202. submenus which are connected with other menu items.
  203.  
  204. This call is supposed to be used when menus with variable number of items
  205. are needed. It may be for example menu with the list of currently opened
  206. documents or archives.
  207.  
  208.  Example code:
  209.  Delete item with handle tmpItem%
  210.  SYS "MenuUtil_Delete",tmpItem%
  211.  
  212.  Recursively delete all menus linked with mainMenu%
  213.  SYS "MenuUtil_Delete",mainMenu%,TRUE
  214.      
  215.                                        
  216.  
  217.  
  218.  
  219.  
  220.  Men