home *** CD-ROM | disk | FTP | other *** search
/ APDL Public Domain 1 / APDL_PD1A.iso / program / menuutils / MenuDoc next >
Encoding:
Text File  |  1993-01-23  |  10.1 KB  |  255 lines
  1.  
  2.  
  3.     Documentation for the MenuUtils module v.0.10 
  4.  
  5.                      © Petrov Software 1992
  6.  
  7.  
  8.  
  9.  
  10.                            Introduction
  11.                                         
  12. This module is mainly intended for people who write RISC OS
  13. applications in BBC BASIC. It can save programmer from the need to
  14. write his own procedures in BASIC for handling menus. MenuUtils module
  15. can perform all the work needed to create, edit, display and decode
  16. menus. The module is very simple in use and is ideal for creating
  17. simple menus. On the other hand module's advanced features allows
  18. easily create and manipulate even very complex multi-level dynamic
  19. menus.
  20.  
  21.  
  22.  
  23.                   What does MenuUtils do ?
  24.  
  25. The MenuUtils module is not the extension to the Window Manager and it
  26. doesn't provide any extra feature. The module only provides a
  27. convenient interface for the programmer to Window Manager's menu
  28. system. The module has a collection of SWIs to do all the low level
  29. work concerned with direct accesses to menu data structures, memory
  30. allocation, etc. It saves the author of application program from the
  31. need to do this routine work himself.
  32.  
  33. MenuUtils provides mechanism of item handlers. It allows to attach
  34. individual handler to each menu item. In case of BBC BASIC the handler
  35. may be simply a BASIC function. When menu item is selected the
  36. corresponding item handler may be invoked automatically. This feature
  37. saves the programmer from the need to decode the list of menu
  38. selections. During program development the use of individual item
  39. handlers simplifies the process of menu modification. You can freely
  40. rearrange menu items without the need to make any changes in other
  41. parts of the program. There is an example in the end of this text
  42. which illustrates the use of item handlers in BASIC programs.
  43.  
  44. MenuUtils automatically allocates memory to hold menu data structures.
  45. And also it takes care about  appearance of menus on screen by forcing
  46. them to be in standard RISC OS style.
  47.                                                
  48.         
  49.  
  50.                       Technical details                     
  51.  
  52. Module MenuUtils may be used only by programs which are WIMP tasks.
  53. Special SWI MenuUtil_Initialise is provided to register the program as
  54. MenuUtils client. MenuUtil_Initialise must be called after
  55. Wimp_Initialise has been called and before any other call to MenuUtils
  56. module is made.
  57.  
  58. All menus created by MenuUtils are kept in RMA. So you have no need to
  59. reserve memory for them. On exit from your program all the memory will
  60. be automatically returned to RMA.
  61.  
  62. Single MenuUtils module can handle menus for several WIMP tasks.
  63.  
  64. Internal format of menu data structures created by the module is the
  65. same as described in RISC OS 2 PRM. So it is possible to combine menus
  66. created by MenuUtils with other menus. To find out address of menu
  67. data structure you can use SWI MenuUtil_Info.
  68.  
  69.  
  70.  
  71.                         Menu handles
  72.  
  73. Menu consists of menu title and one or more menu items. Each menu and
  74. each menu item created with MenuUtils gets unique handle. You can use
  75. this handle to refer to particular menu or menu item.
  76.  
  77. The use of unique handles for each menu item instead of absolute
  78. addresses or positions in menu gives additional flexibility in
  79. manipulation with menu data structure. It allows for example insert
  80. and delete menu items.
  81.  
  82. MenuUtils always remembers the handle used in last operation. This
  83. handle is called current handle and it will be used as default in the
  84. next operation. This is especially convenient when calls to the module
  85. are made from BASIC with SYS command.
  86.  
  87.                                                                
  88.  
  89.                         Menu creation
  90.  
  91. To start new menu you must call MenuUtil_New. Then you may add to it
  92. any number of menu items. To add new item you must call MenuUtil_Add.
  93. Menu always is ready to be displayed on screen and you have no need to
  94. specially inform the module when you have added the last item to the
  95. menu.
  96.  
  97. By default all new items are added to the end of menu. If you want to
  98. insert new item in the middle of menu then you must specify the handle
  99. of the item before which you want to insert the new item.
  100.                                 
  101. All menu flags in added items are cleared. Colours and dimensions are
  102. in standard RISC OS style. Width of menu is adjusted automatically.
  103.  
  104. In order to construct multi-level menu tree you have to connect some
  105. menu items with submenus or with dialog boxes. MenuUtils provides
  106. special SWI to link menu item with submenu. This SWI also allows you
  107. to link menus created by MenuUtils with other menus.
  108.  
  109.                             
  110.  
  111.                       Menu modification
  112.                                                                   
  113. You can in any moment change menu title string as well as the text of
  114. menu items. You can also change foreground and background colours of
  115. menu items.
  116.                                               
  117. Menu item has a number of flags which control its appearance and
  118. behaviour. The flags are tick, fade, dots, submenu, writable and
  119. message. Special SWIs are provided to set or clear each menu flag. As
  120. a special case when you are making menu item writable you can also
  121. specify buffer size and optional validation string. 
  122.  
  123. You can delete single menu item or the whole menu with
  124. MenuUtil_Delete. You can also recursively delete the whole menu
  125. subtree connected with the deleted item or with the deleted menu.
  126.  
  127.                                                                                   
  128.                    Displaying menu on screen
  129.                    
  130. According to RISC OS rules you must display menu on screen when user
  131. clicks with Menu button over one of your windows or iconbar icon. To
  132. find out where to display the menu you have to perform some
  133. calculations. MenuUtils provides a SWI MenuUtil_Show which will
  134. perform all necessary calculations for you and open menu in the right
  135. screen position according to RISC OS standards.
  136.  
  137. Special SWI is provided to display submenu in reply to
  138. Message_MenuWarning.
  139.  
  140.  
  141.  
  142.                Item handlers and menu decoding
  143.                                                          
  144. The mechanism of item handlers allows to link each menu item with
  145. individual item handler. The handler may be invoked automatically and
  146. you have no need to decode the list of selections in order to take the
  147. appropriate action.
  148.  
  149. During the call to "MenuUtil_Initialise" you must specify
  150. initialisation type. Initialisation type defines the interpretation of
  151. item handlers and can be "BASIC" or "machine code" (latter is not
  152. supported in current version). In case of "BASIC" the item handlers
  153. are assumed to be the BASIC functions and in case of "machine code" -
  154. ARM subroutines. If you want to attach a handler to menu item you must
  155. pass the pointer to the name of BASIC function or respectively the
  156. address of the ARM subroutine to MenuUtil_Add.
  157.  
  158. After user selection the corresponding item handler will be found by
  159. "MenuUtil_Decode". To invoke the handler you have to call either the
  160. BASIC function or the ARM subroutine depending on initialisation type.
  161.  
  162.             
  163.                            
  164.                         Other features
  165.                  
  166. Many applications use standard menu allowing user to select a colour
  167. from standard desktop colours. MenuUtils provides a special SWI
  168. "MenuUtil_ColourMenu" which creates such colour setting menu.
  169.  
  170.  
  171.  
  172.                       Application notes
  173.  
  174. This example illustrates the use of menu item handlers in programs in
  175. BBC BASIC. Lets consider simple menu consisting of single item.
  176.  
  177.             +----------------+
  178.             |                |
  179.             |  Simple menu   |
  180.             |                |
  181.             +----------------+
  182.             |  Item#1        |  
  183.             +----------------+
  184.  
  185. To create this menu we must call "MenuUtil_New" and to add an item -
  186. "MenuUtil_Add".
  187.  
  188.  SYS "MenuUtil_New",,"Simple menu"
  189.  SYS "MenuUtil_Add",,"Item#1","func1"
  190.  
  191. - here "Simple menu" is menu title, "Item#1" - item text and "func1" -
  192. name of the item handler. The name of the handler is "func1" so we
  193. must have a function with the name "FNfunc1".
  194.  
  195.  DEF FNfunc1
  196.  ...
  197.  =TRUE
  198.  
  199. Then we organize the main Wimp_Poll loop in the following way.
  200.  
  201.  DIM q% &100
  202.  REPEAT SYS "Wimp_Poll",,q% TO reason%
  203.    CASE reason% OF
  204.      ...         
  205.      REM Mouse click
  206.      WHEN 6
  207.             IF q%!8=2 THEN SYS "MenuUtil_Show",,q%
  208.  
  209.      REM Menu selection  
  210.      WHEN 9
  211.             SYS "MenuUtil_Decode",,q% TO handler%
  212.             IF handler% THEN
  213.               handler$="FN"+$handler%   
  214.               IF EVAL handler$
  215.             ENDIF
  216.      ...
  217.    ENDCASE
  218.  UNTIL FALSE
  219.     
  220. If the user clicks with Menu button we will call "MenuUtil_Show" to
  221. display menu on screen. If user selects something from our menu we
  222. will call "MenuUtil_Decode" to find out corresponding item handler.
  223. Variable handler% will contain pointer to the handler name. In our
  224. example if user will select item "Item#1" variable handler% will point
  225. to string "func1". The full name of the handler will be
  226. "FN"+$handler%. And EVAL statement is used to call it.
  227.                                                                  
  228.  
  229. ------------------------------------------------------------------------
  230.                     Notes from the author
  231.  
  232.  
  233. MenuUtils is freeware software. Everybody is free to use MenuUtils
  234. module, even in commercial code. In case of commercial use I would
  235. like to know this in advance (I could than provide you with the latest
  236. release). You can always contact me if you found some bug, or when
  237. having other suggestions.
  238.  
  239.          To contact the author of MenuUtils, please write to:
  240.                                       
  241.                                         RUSSIA
  242.                                         115541
  243.                                         Moscow
  244.                                         Kavkazsky boulevard, 29
  245.                                         Bld. 1, Flat 107
  246.                                         Alex Petrov    
  247.  
  248.                          E-mail: APetrov@misis.msk.su      
  249.                                  APetrov@arm.msk.su
  250.                                  
  251.                          FIDO :  2:5020/104.13
  252.  
  253.                           phone: +7 095 322 2098
  254.                           fax  : +7 095 236 8350
  255.