home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / menus / menuutils / a214 / 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.  MenuUtil_Decode (SWI &45BC4)
  221.  ----------------------------
  222.  Decodes menu after user selection.
  223.  
  224.  Entry:
  225.  
  226.      R0 = menu handle or zero if current menu
  227.      R1 -> pointer to the list of menu selections
  228.  Exit:
  229.      R0 -> pointer to item handler or zero 
  230.      R1 -> pointer to block
  231.  
  232. Block pointed to by R1 must contain the list of menu selections in the same
  233. format as returned by Wimp_Poll in case of menu selection event. 
  234.  
  235.                R1 + 0  item in main menu which was selected (starting from 0)
  236.                R1 + 4  item in first submenu which was selected
  237.                R1 + 8  item in second submenu which was selected
  238.                        ...
  239.                        terminated by -1
  240.  
  241. This call maps the list of menu selections onto menu data structure and
  242. determines corresponding menu items. Various information about last two
  243. items from this list (selected item and parent item from menu one level up
  244. if any) is written into special block. Pointer to this block is returned in
  245. R1. Format of the returned block is as follows: 
  246.  
  247.  R1+0  position of selected menu item in menu (starting from 0)
  248.  R1+4  pointer to selected item data
  249.  R1+8  selected item handle or zero if item was created without MenuUtils
  250.  R1+12 pointer to text string of selected item
  251.  R1+16 position of parent menu item in menu (starting from 0)
  252.  R1+20 pointer to parent item data
  253.  R1+24 parent item handle or zero if item was created without MenuUtils
  254.  R1+28 pointer to text string of parent item                         
  255.  
  256. If the item has been selected from the top-level menu then there will be no
  257. parent item and corresponding part of the block will be filled with zeros.                                                                                     
  258. If during creation of this item you have specified the handler then R0 on
  259. exit will contain the pointer to this handler otherwise R0 will be zero.
  260. Interpretation of item handler is determent by initialisation type (see
  261. MenuUtil_Initialise). If initialisation type was "BASIC" then R0 will point to
  262. ctrl-terminated text string. If initialisation type was "machine code" (not
  263. supported by current version) then R0 will contain the value passed in R2 to
  264. MenuUtil_Add. To invoke BASIC handler you can use EVAL statement.
  265.  
  266. Example code:
  267.  Suppose Wimp_Poll has returned reason code 9 (Menu_Selection) and q%
  268. points to the corresponding block. You can use MenuUtil_Decode to call the
  269. item handler in the following way:
  270.  SYS "MenuUtil_Decode",,q% TO handler%                            
  271.  IF handler% THEN
  272.    handler$="FN"+$handler%
  273.    IF EVAL(handler$)
  274.  ENDIF
  275.                 
  276.  
  277.  
  278.  
  279.  
  280.  MenuUtil_Show (SWI &45BC5)
  281.  --------------------------
  282.  Displays menu on screen
  283.  
  284.  Entry:
  285.      R0 = handle of the menu or zero for current menu
  286.      R1 -> pointer to block or zero
  287.  Exit:
  288.      R0,R1 preserved
  289.  
  290. This call may be used to display menu on screen. Screen position for menu
  291. will be calculated according to rules described in PRM. Block pointed to by
  292. R1 must contain the same information as returned by Wimp_Poll in case of
  293. mouse click event (in fact only mouse coordinates and window handle will be
  294. used) :
  295.                      R1 + 0  mouse X
  296.                      R1 + 4  mouse Y
  297.                      R1 + 8  buttons
  298.                      R1 +12  window handle (-2 if icon bar)
  299.                      R1 +16  icon handle                
  300.  
  301. MenuUtils automatically distinguishes iconbar menus from ordinary
  302. window menus. If menu is already on screen and you want to reopen it
  303. after user selection with Adjust button then pointer to the block may be
  304. omitted.
  305.  
  306.  Example code:
  307.  Suppose Wimp_Poll has returned reason code 6 (Mouse_Click) and q% points to
  308. the returned block. Display menu on screen if the click is with Menu button.
  309.  buttons%=q%!8
  310.  IF (buttons% AND2)<>0 THEN SYS "MenuUtil_Show",mainMenu%,q%
  311.   
  312.  Leave menu on screen after selection with Adjust button
  313.  SYS "MenuUtil_Show"
  314.  
  315.  
  316.  
  317.  
  318.  MenuUtil_ShowSubMenu (SWI &45BC6)
  319.  ---------------------------------
  320.  Display submenu after receiving Message_MenuWarning
  321.  
  322.  Entry:
  323.      R0 = handle of the submenu or zero for current menu
  324.      R1 -> pointer to block
  325.  Exit:
  326.      R0,R1 preserved
  327.  
  328. This call may be used to display submenu when a message type MenuWarning
  329. (&400C0) is received by an application. This message is sent by the Wimp
  330. when submenu is about to be accessed by the pointer moving over the
  331. right-pointing arrow of the parent menu. (To find out the handle of the
  332. menu item in parent menu you can use MenuUtil_Decode).
  333.  
  334. R1 on entry must point to message block (in fact only two words at offsets
  335. +24 and +28 will be used).
  336.                  
  337. Note: If you plan to use MenuUtil_Decode then all submenu pointers must be
  338. valid. It means that you have to link submenu pointed to by R0 with
  339. corresponding menu item. This can be done by MenuUtil_SubMenu.
  340.  
  341.  Example code:
  342.  Display fonts submenu on screen after receiving MenuWarning:
  343.  SYS "MenuUtil_SubMenu",fontsItem%,fontsMenu%
  344.  SYS "MenuUtil_ShowSubMenu",fontsMenu%,q%
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  MenuUtil_Info (SWI &45BC7)
  351.  --------------------------
  352. This call returns various information about the whole menu or about the
  353. particular menu item.
  354.  
  355.  Entry:
  356.      R0 = handle of the menu or of the menu item or zero for current item
  357.  Exit:
  358.      R0 -> pointer to block
  359.  
  360. Returned block contains the following information:
  361.    R0 + 0 pointer to menu data structure
  362.    R0 + 4 pointer to item data or zero
  363.  
  364. Menus created with MenuUtils are not static and may be moved in
  365. memory, for example after adding new items. So you must use direct
  366. pointers to this menus with caution until you have completely finished
  367. the menu construction.
  368.  
  369.  
  370.  
  371.  
  372.  MenuUtil_Text (SWI &45BC8)
  373.  --------------------------
  374.  Changes menu title string or text of menu item
  375.  
  376.  Entry:
  377.      R0 = handle of menu item or handle of menu or  zero for current item
  378.      R1 -> pointer to text string 
  379.  Exit:
  380.      R0,R1 preserved
  381.  
  382. This call allows you to change title string of menu or text of menu item.
  383. The structure of menu tree remains unchanged but pointer to item text may be
  384. changed. The handle of the menu or menu item must be specified in R0. If R0
  385. is zero on entry then the text of current item will be changed. R1 must
  386. point to the ctrl-terminated text string. If R1 is zero on entry then null
  387. string will be used. Remember that the length of menu title is limited by 12
  388. symbols.
  389.  
  390.  Example code 
  391.  Set new menu title string:
  392.  SYS "MenuUtil_Text",objectMenu%,"Directory"
  393.  
  394.  Let's variable type% contains one of the values 0,1,2 or 3 depending on the
  395. object selected in Filer window and variable name$ contains the name of the
  396. file or directory selected.  
  397.  
  398. CASE type% OF
  399.   WHEN 0:i$="File ''"
  400.   WHEN 1:i$="File '"+name$+"'":s$="File"
  401.   WHEN 2:i$="Dir. '"+name$+"'":s$="Directory"
  402.   WHEN 3:i$="Selection":s$=i$
  403. ENDCASE
  404.                    
  405. REM fade the item if nothing is selected
  406. SYS "MenuUtil_Fade",objectItem%,type%=0           
  407.  
  408. REM set new item text
  409. SYS "MenuUtil_Text",,i$
  410.            
  411. REM set new submenu title
  412. SYS "MenuUtil_Text",toolsMenu%,s$
  413.  
  414.  
  415.  
  416.  
  417.  MenuUtil_Tick (SWI &45BC9)
  418.  --------------------------            
  419. This call may be used to modify the state of menu flag which controls
  420. the tick displayed on the left of the menu item. 
  421.  
  422.  Entry:
  423.      R0 handle of menu item or zero for current menu item or handle of menu
  424.      R1 defines action
  425.         if R1 =0 then clear tick flag 
  426.         if R1 <>0 then set tick flag  
  427.  Exit:
  428.     R0,R1 preserved
  429.             
  430. R0 must contain the item handle or zero for the current menu item. R1
  431. defines to set or to clear the flag. If R1 is zero then the flag will
  432. be cleared and if R1 is non zero then the flag will be set.
  433.  
  434. If R0 instead of item handle contains menu handle then the state of
  435. the flag will be changed in all items of this menu.
  436.  
  437. It is convenient to pass in R1 the result of logical expression (to
  438. set flag if result is TRUE and to clear it if FALSE).
  439.  
  440.  Example code:
  441.  Tick one of the items depending on the value of variable disp%:
  442.  SYS "MenuUtil_Tick",largeItem%,(disp%=1)
  443.  SYS "MenuUtil_Tick",smallItem,(disp%=2)
  444.  SYS "MenuUtil_Tick",fullItem%,(disp%=3)
  445.                                            
  446.  
  447.  
  448.  
  449.  MenuUtil_Dots (SWI  &45BCA)
  450.  ---------------------------            
  451. This call may be used to modify the state of menu flag which controls
  452. the dotted line displayed bellow the menu item. 
  453.  
  454.  Entry:
  455.      R0 handle of menu item or zero for current menu item or handle of menu
  456.      R1 defines action
  457.         if R1 =0 then clear dots flag 
  458.         if R1 <>0 then set dots flag  
  459.  Exit:
  460.     R0,R1 preserved
  461.             
  462. R0 must contain the item handle or zero for the current menu item. R1
  463. defines to set or to clear the flag. If R1 is zero then the flag will
  464. be cleared and if R1 is non zero then the flag will be set.
  465.  
  466. If R0 instead of item handle contains menu handle then the state of
  467. the flag will be changed in all items of this menu.
  468.  
  469. It is convenient to pass in R1 the result of logical expression (to
  470. set flag if result is TRUE and to clear it if FALSE).
  471.  
  472.  Example code:
  473.  Display dotted line after the current menu item
  474.  SYS "MenuUtil_Dots",,TRUE
  475.  
  476.                                            
  477.  
  478.  MenuUtil_Fade (&45BCB)
  479.  ----------------------            
  480. This call can be used to make menu item non-pickable 
  481.  
  482.  Entry:
  483.      R0 handle of menu item or zero for current menu item or handle of menu
  484.      R1 defines action
  485.         if R1 =0 clear shaded menu flag
  486.         if R1 <>0 fade this menu item (ie. unpickable) 
  487.  Exit:
  488.     R0,R1 preserved
  489.             
  490. R0 must contain the item handle or zero for the current menu item. R1
  491. defines to set or to clear the flag which makes menu item unpickable. If R1
  492. is zero then the flag will be cleared and if R1 is non zero then the flag
  493. will be set and the item will be shaded.
  494.  
  495. If R0 instead of item handle contains menu handle then the state of
  496. the flag will be changed in all items of this menu.
  497.  
  498. It is convenient to pass in R1 the result of logical expression (to
  499. set flag if result is TRUE and to clear it if FALSE).
  500.  
  501.  Example code:
  502.  Fade current menu item:
  503.  SYS "MenuUtil_Fade",,TRUE
  504.  
  505.  Fade all items in "Select" submenu with handle selctMenu%
  506.  SYS "MenuUtil_Fade",selectMenu%,TRUE
  507.  
  508.  
  509.  
  510.  
  511.  MenuUtil_Warning (SWI &45BCC)
  512.  -----------------------------            
  513. This call can be used to make menu item generate a message when moving to
  514. the submenu 
  515.  
  516.  Entry:
  517.      R0 handle of menu item or zero for current menu item or handle of menu
  518.      R1 defines action
  519.         if R1 =0 clear message menu flag
  520.         if R1 <>0 set message flag (ie. message will be generated) 
  521.  Exit:
  522.     R0,R1 preserved
  523.             
  524. R0 must contain the item handle or zero for the current menu item. R1
  525. defines to set or to clear the flag which changes submenu behaviour. If R1
  526. is not zero, then moving over the right arrow will cause a MenuWarning
  527. message (&400C0) to be generated. The application can respond by calling
  528. MenuUtil_ShowSubMenu to display appropriate object.
  529.  
  530. If R0 instead of item handle contains menu handle then the state of
  531. the flag will be changed in all items of this menu.
  532.  
  533. It is convenient to pass in R1 the result of logical expression (to
  534. set flag if result is TRUE and to clear it if FALSE).
  535.  
  536.  Example code:
  537.  Generate message when moving to the fonts submenu:
  538.  SYS "MenuUtil_Warning",fontsItem%,TRUE
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  MenuUtil_Writable (SWI &45BCD)
  545.  ------------------------------
  546.  Makes menu item writable.
  547.  
  548.  Entry:
  549.      R0 = handle of menu item or zero for current item or handle of the menu
  550.      R1 <>0 and
  551.      R2 = buffer size
  552.      R3 -> pointer to validation string, or
  553.  
  554.      R1 =0 makes item not writable
  555. Exit:
  556.      R0-R3 preserved
  557.  
  558. If R1 is not zero on entry then this call will convert existing menu item
  559. into writable item. R0 must contain the handle of the menu item or zero for
  560. current item. If R0 contains handle of the menu then all the items in this
  561. menu will be converted. 
  562.  
  563. R2 on entry contains the length of the buffer for the input string.
  564. The value in R2 must be not less then the length of the current item
  565. text. In the latter case the buffer will remain unchanged.
  566.  
  567. If R3<>0 on entry then it points to the ctrl-terminated validation
  568. string. The module makes its own copy of the string. If R3=0 on entry
  569. then no validation string will be used.
  570.  
  571. If R1 is zero on entry then the item will be converted back into ordinary
  572. menu item. In this case contents of registers R2 and R3 will be ignored.
  573.  
  574.  Example code:
  575.  Make current item writable without validation string
  576.  SYS "MenuUtil_Writable",,TRUE
  577.  
  578.  Make menu item with handle widthItem% writable, with buffer size 40 and
  579. allow to enter to it only digits.
  580.  SYS "MenuUtil_Writable",widthItem%,TRUE,40,"A0-9"
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  MenuUtil_Submenu (SWI &45BCE)
  587.  -----------------------------
  588.  Links submenu to menu item
  589.  
  590.  Entry:
  591.      R0 handle of the menu item or zero if current menu item
  592.      R1 handle of submenu or pointer to submenu or window handle
  593.         if R1<&8000 then R1 is window handle
  594.         if R1>&8000 then R1 is pointer to menu 
  595.         if R1<0 then R1 is menu handle
  596.  
  597.  Exit:
  598.      R0,R1 preserved
  599.  
  600. This call is used for constructing multilevel menus. R0 on entry
  601. contains the handle of menu item. This item is linked with submenu or
  602. dialog box depending on contents of R1. To connect submenu R1 may
  603. contain menu handle (as returned by "MenuUtil_New") or absolute pointer to
  604. the menu data structure. To connect dialog box R1 must contain window
  605. handle of dialog box (as returned by "Wimp_CreateWindow").
  606.  
  607.  
  608.  Example code:
  609.                         
  610.  Connect "About this program" window to the item "Info"
  611.  SYS "Wimp_CreateWindow",,block% TO infoWindow%
  612.  SYS "MenuUtil_Submenu",infoItem%,infoWindow%
  613.  
  614.  Create "Display" item in filer menu  
  615.  SYS "MenuUtil_New",,"Filer"
  616.  SYS "MenuUtil_Add",,"Display"
  617.  SYS "MenuUtil_Submenu",,dispMenu%   
  618.  
  619.  
  620.  
  621.                                 
  622.  MenuUtil_ColourMenu (SWI &45BCF)
  623.  --------------------------------
  624.  Creates a wimp colour setting menu
  625.  Entry:
  626.      R1 -> menu title string
  627.      R2 -> menu handle
  628.  Exit:                 
  629.      R0 = handle of the menu
  630.      R1 preserved
  631.  
  632. This call creates standard WIMP colour setting menu. R1 on entry
  633. points to the title string for the menu. If R2<>0 then it points to
  634. the handler common for all 16 items. (See also "MenuUtil_Add" for more
  635. info about item handlers). Despite the fact that the same handler is
  636. invoked with all items it is still possible to distinguish user
  637. selection. MenuUtil_Decode returns not only pointer to the handler but
  638. also the number (position) of selected item in the menu. Actually this
  639. number is equal to the colour number.
  640.  
  641.  
  642.  Example code:
  643.  Create colour setting menu:
  644.  SYS "MenuUtil_ColourMenu",,"Colour" TO colourMenu%
  645.  
  646.  
  647.  
  648.  
  649.  MenuUtil_Colours (SWI &45BD0)
  650.  -----------------------------
  651.  Sets new foreground and background colours of menu item
  652.  
  653.  Entry:
  654.      R0 = handle of the menu item or zero for current item
  655.      R1 = foreground colour
  656.      R2 = background colour
  657.  Exit:
  658.      R0-R2 preserved
  659.  
  660. This call allows you to change colours of particular menu item. Colours must
  661. be selected from 16 Wimp colours.
  662.                                    
  663.  Example code:
  664.  Change colours of current item to black on yellow
  665.  SYS "MenuUtil_Colours",,7,9
  666.  
  667.            
  668.  
  669.  
  670.  MenuUtil_TickOnly (SWI &45BD1)
  671.  ------------------------------
  672.  Tick only specified menu item
  673.  
  674.  Entry:
  675.      R0 = handle of the menu item or zero for current item, or
  676.           
  677.      R0 = handle of the menu
  678.      R1 = item position in the menu (starting from zero)
  679.  Exit:
  680.      R0,R1 preserved
  681.  
  682. This call ticks specified item and clears tick flags in remaining items in
  683. the menu. If you don't know the handle of the menu then you can specify
  684. handle of the menu in R0 and position of the item in R1.
  685.  
  686.  
  687.  Example code:
  688.  Tick black colour in colour menu
  689.  SYS "MenuUtil_TickOnly",colourMenu%,7
  690.  
  691.  
  692. ----------------------------------------------------------------------
  693.                      Notes from the author
  694.  
  695.  
  696. MenuUtils is freeware software. Everybody is free to use MenuUtils
  697. module, even in commercial code. In case of commercial use I would
  698. like to know this in advance (I could than provide you with the latest
  699. release). You can always contact me if you found some bug, or when
  700. having other suggestions.
  701.  
  702.          To contact the author of MenuUtils, please write to:
  703.                                       
  704.                                         RUSSIA
  705.                                         115541
  706.                                         Moscow
  707.                                         Kavkazsky boulevard, 29
  708.                                         Bld. 1, Flat 107
  709.                                         Alex Petrov    
  710.  
  711.                          E-mail: APetrov@misis.msk.su  
  712.                                  APetrov@arm.msk.su
  713.  
  714.                          FIDO :  2:5020/104.13
  715.                                  
  716.                           phone: +7 095 322 2098
  717.                           fax  : +7 095 236 8350
  718.  
  719.