home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / programs / fonts / a_q / font_em / !Font'em / FntMenuDoc < prev    next >
Text File  |  1992-10-08  |  15KB  |  334 lines
  1.  
  2.  
  3.                Documentation for the FontMenu module v.1.06
  4.  
  5.                              © J.RÖling 1990
  6.  
  7.  
  8.  
  9.                                Introduction
  10.  
  11.  As more and more outlined fonts for the Archimedes are becoming available,
  12. a problem arrises for applications accessing these fonts. The number of
  13. fonts is not known in advance, so to create a font menu the application has
  14. to figure out the number of fonts, claim enough space to hold a font menu,
  15. and create it. This can be done in the dull single level (straight foreward)
  16. way. This saves some space, and code complexety, but it is not prefered, as
  17. the user will be presented by a sometimes very long menu containing items
  18. with the same prefix, e.g. 
  19.  
  20.                              Trinity
  21.                              Trinity.Bold
  22.                              Trinity.Bold.Italic
  23.                              Trinity.Medium
  24.                              Trinity.Medium.Italic
  25.                              etc.
  26.  
  27.  The more fonts become available, the longer this menu becomes, the more
  28. irritating it is. 
  29.  
  30.  Many applications now are even uncapable of creating menus longer then a
  31. certain amount. Examples of these are !Edit (48 entries), !Draw (64
  32. entries), and even !Impression reacts sick.
  33.  
  34.  When running more then one application with a font menu, there is arises
  35. another disadvantage of this method. Several applications using a identical
  36. menu structure but not sharing the resource, is not the policy of Acorn on
  37. other subjects. 
  38.  
  39.  So here is a neat solution for everyone who wants a proper font menu,
  40. without the hassel to create one, and without claiming extra space.
  41.  
  42.                                                  
  43.                           
  44.  
  45.                           What does FontMenu do ?
  46.  
  47.  The FontMenu module is able of creating a multi-level font menu, and lets
  48. every application share the joy. It contains several SWI's to create, and
  49. access this resource. If no application is using the structure anymore
  50. (because they were all quited for example) the memory for the menu structure
  51. will be realesed by FontMenu, so no unnecessary memory is in use. It has no
  52. problems if more than one font directory is in use. The menu is sorted
  53. alphabeticly (even when more than one font directoris are used), so the user
  54. is able to find the required font at an instance. It requires a minimum of
  55. disc access when a new menu is created. New menus are only created if one is
  56. required, and there isn't already a valid one. When a font menu exsists, and
  57. the user has selected a new font directory, the font menu will be rebuild as
  58. soon as the application accesses this font menu. 
  59.  
  60.  FontMenu creates an multi-leveled font menu. In the example above this is a
  61. menu where 'Trinity' occurs only once, but it will have a submenu containing
  62. two items: 'Bold' and 'Medium'. Because there are two types of
  63. 'Trinity.Bold' ('Trinity.Bold' and 'Triniy.Bold.Italic') 'Bold' will have
  64. another submenu. In this submenu the first item will be 'Plain'. This name
  65. is made up, but it is more clear then a empty meny entry. The second entry
  66. will of course be 'Italic'.
  67.  
  68.  
  69.  
  70.                           How does FontMenu work ?
  71.  
  72.  To use FontMenu it is necessary to understand how the Wimp works, and how
  73. to create a application on the Archimedes environment. It is assumed that
  74. the reader understands the above for the rest of this document.
  75.  
  76.  When a application wants to access the FontMenu menu structure, it has to
  77. call SWI "FontMenu_Create" before any other FontMenu SWI's are called. This
  78. will assure that a proper font menu structure will be available. This can be
  79. done on initialisation of the application, but is not absolutly necessary.
  80. When exiting the application, SWI "FontMenu_Release" has to be called, so if
  81. this was the only application using the font menu, FontMenu can release the
  82. memory for it. Every time SWI "FontMenu_Create" is called, a counter is
  83. incremented, and if it was zero (this is the initial value), it will create
  84. a new font menu. When calling SWI "FontMenu_Release", the counter is
  85. decremented, and if it reached zero FontMenu will release the menu memory,
  86. as no application is using the menu structure anymore.
  87.  
  88.  
  89.  From here on there are two ways of programming when using FontMenu. The
  90. first is the simple one, the second a little bit more complicated, as it
  91. involves the use the Wimp message system.
  92.  
  93.  The easy way
  94.  ------------
  95.  Whenever the user opens the menu structure of the application by pressing
  96. the MENU button, a call has to be made to FontMenu_Select with R0 pointing
  97. to a point sepearted (zero terminated) font string, and in R1 the value 0 or
  98. 1 to tell FontMenu if it allows the user to select the SystemFont. The call
  99. will return with a pointer to the font menu structure in R1. Now it is up to
  100. the programmer what to do with this pointer. When passed in R1 when calling
  101. Wimp_CreateMenu, the menu tree will consist entirely of FontMenu structures.
  102. If the font menu should be a submenu of the applications own menu structure,
  103. the pointer should be put in the submenu-word of the parent menu entry, and
  104. Wimp_CreateMenu should be called with a pointer to the applications own menu
  105. structure.
  106.  
  107.  When a menu selection was done, the application should determine by the
  108. returned 'menu tree so far' values if the user selected a entry in the font
  109. menu. If so, it should set an internal flag (say 'FontMenuSelected') to
  110. TRUE, else it should set it to FALSE, so later on it is still known if the
  111. user may have selected a new font. After that it should call SWI
  112. "FontMenu_DecodeFontMenu" with R0 pointing to the first menu selection in
  113. the 'menu tree so far' block wich determines the selected font. R1 should
  114. point to a buffer to contain the answer. This buffer must be at least 48
  115. bytes. If on return of this call R0 > 0, the user selected a new font. The
  116. buffer passed in R1 will contain the font name (a point seperated, zero
  117. terminated font string).
  118.  
  119.  After a menu selction, and taking appropriate actions, the application
  120. should check the mouse button state to see if it has to call SWI
  121. "Wimp_CreateMenu" again. If adjust was used to make the selection, it has to
  122. check  the 'FontMenuSelected' flag to determine if the user selected a font
  123. menu entry. If so, it should call FontMenu_Select as discribed above. This
  124. should be done with R0 pointing to the string FontMenu_DecodeFontMenu
  125. returned. The menu pointer returned by FontMenu_Select has to be put in the
  126. 'sub-menu pointer' word of the 'Fonts' entry. Now the call to
  127. Wimp_CreateMenu can be done. In this way it is possible for the user to
  128. click with adjust in the font menu, and keeping the menu on screen after the
  129. selection.
  130.  
  131.  There is one little drawback of this method. If the user selected a new
  132. !Fonts directory, it will be noted be the FontMenu_Select code, and a new
  133. font menu structure will be generated. This is always the case, also with
  134. the method discribed below. But it could be possible that the user was going
  135. to do something else in the menu, not selecting a font at all. He could for
  136. instance want to quit. Now he (she) has to wait for the FontMenu module to
  137. create the new menu structure, before he (she) is able to access the 'Quit'
  138. entry. So the next solution is to wait with calling FontMenu_Select, until
  139. the user wants to select a new font. This can only be done by making use of
  140. the Wimp message system. The difficult thing of this method (as discribed
  141. later) is that the Wimp is unable to re-open the menu structure entirely
  142. after a menu selection using the ADJUST button. So a little trick has to
  143. solve this problem.
  144.  
  145.  The hard way
  146.  ------------
  147.  In the applications own menu structure, there should be a menu entry (e.g.
  148. 'Fonts') with bit 3 if its menu flags set. The application has to assure
  149. that this bit is set whenever it calls SWI "Wimp_CreateMenu" as it may be
  150. corrupted (see below). So whenever the user puts the pointer above the arrow
  151. on the right of this entry, a warning message (&400C0) will be send by the
  152. Wimp. On receiving of this message, the application should respond by calling
  153. SWI "FontMenu_Select" with R0 pointing to a point sepearted (zero
  154. terminated) font string, and in R1 the value 0 or 1 to tell FontMenu if it
  155. allows the user to select the SystemFont. The font string may be a zero
  156. length string, wich means that no current font is selected. FontMenu will
  157. select the font in its menu structure. If 1 was passed in R1, the first item
  158. in the menu structure will be 'SystemFonts'. In case R1 = 0, this entry will
  159. not be there. This call will return with a pointer to the menu structure in
  160. R1. This pointer should be passed to SWI "Wimp_CreateSubMenu".
  161.  
  162.  When a menu selection was done, the application should determine by the
  163. returned 'menu tree so far' values if the user selected a entry in the font
  164. menu. If so, it should set an internal flag (say 'FontMenuSelected') to
  165. TRUE, else it should set it to FALSE, so later on it is still known if the
  166. user may have selected a new font. After that it should call SWI
  167. "FontMenu_DecodeFontMenu" with R0 pointing to the first menu selection in
  168. the 'menu tree so far' block wich determines the selected font. R1 should
  169. point to a buffer to contain the answer. This buffer must be at least 48
  170. bytes. If on return of this call R0 > 0, the user selected a new font. The
  171. buffer passed in R1 will contain the font name (a point seperated, zero
  172. terminated font string).
  173.  
  174.  After a menu selction, and taking appropriate actions, the application
  175. should check the mouse button state to see if it has to call SWI
  176. "Wimp_CreateMenu" again. If adjust was used to make the selection, it has to
  177. check  the 'FontMenuSelected' flag to determine if the user selected a font
  178. menu entry. If so, it should call SWI "FontMenu_Select" as discribed above.
  179. This should be done with R0 pointing to the string SWI
  180. "FontMenu_DecodeFontMenu" returned.  As the MenuWarningFlag in the menu
  181. flags of the menu entry (e.g. 'Fonts') preceding the font menu was set
  182. (phhh!), the Wimp is unable to recreating the whole menu tree automaticly.
  183. So a litle trick has to assure that it will work correct. The menu pointer
  184. returned by SWI "FontMenu_Select" has to be put in the 'sub-menu pointer'
  185. word of the 'Fonts' entry, and the MenuWarningFlag (bit 3) of the menu flags
  186. word of this entry should be cleared. Now the call to SWI "Wimp_CreateMenu"
  187. can be done. In this way it is possible for the user to click with adjust in
  188. the font menu, and keeping the menu on screen after the selection. The next
  189. time the user opens the application menu, the MenuWarningFlag (bit 3) should
  190. be set again, as other applications may have used the font menu in the
  191. meanwhile, and it is necessary that SWI "FontMenu_Select" is called just
  192. before the font menu opens.
  193.  
  194.  Because it is possible that SWI "FontMenu_Create" takes some time to create
  195. a new menu, it is recomended that there is a SWI "Hourglass_On" before, and
  196. a SWI "Hourglass_Off" after this call. In case of a SWI "FontMenu_Select",
  197. when Font$Path has changed (so a new font menu has to be created), this call
  198. may take some time aswell, so the two Hourglass SWI's should be used here as
  199. well.
  200.  
  201.  
  202.  
  203.  
  204.                             Notes from the author
  205.  
  206.  The reason why I wrote this module, is because I'm not only a programmer,
  207. but also a user who likes to work with the Archimedes. This is because it's
  208. a fast machine and because most parts of Risc-OS allow applications to be
  209. very intuitive. I didn't like the way the available fonts were presented in
  210. most applications, so I started to figure out a proper solution: FontMenu.
  211.  
  212.  I hope that future applications adopt to this method, so please pass it on.
  213. Everybody is free to use it, even in commercial code. The only restriction
  214. is that this document should not be seperated from the FontMenu module, and
  215. that both the module and this document remain unchanged. In case of
  216. commercial use I would like to know this in advance (I could than provide
  217. you with its latest release). My address is at the end of this document. You
  218. can always contact me if you found some bug, or when having other
  219. suggestions.
  220.  
  221.  
  222.  
  223.  
  224.                                 FontMenu SWI's
  225.  
  226.            Below are the short discriptions of the FontMenu SWI's.
  227.            
  228.  
  229. FontMenu_Create &8D080
  230. ----------------------
  231. On entry: --
  232. On exit : R0 = Number of fonts found
  233.  
  234.  This will create a font menu structure in RMA, if not already done so. An
  235. error occurs if there is not enough room in RMA to create the menu.
  236.  
  237.  
  238.  
  239. FontMenu_Release &8D081
  240. -----------------------
  241. On entry: --
  242. On exit : --
  243.  
  244.  This will release the memory taken by the font menu if no tasks are using
  245. it anymore.
  246.  
  247.  
  248.  
  249. FontMenu_Select &8D082
  250. ----------------------
  251. On entry: R0 = pointer to point seperated, ctrl terminated font string 
  252.           R1 = SystemFont flag            
  253.  
  254. On exit : R0 = State flag
  255.           R1 = pointer to font menu structure
  256.  
  257.  This will tick the font passed in R0 on entry. R1 determines if
  258. 'SystemFont' should occur in the menu as follows:
  259.  
  260.   Value Meaning
  261.     0   'SystemFont' does not occur in the menu
  262.     1   'SystemFont' does occur in the menu
  263.                          
  264.  On exit R0 shows the selection state as follows:
  265.  
  266.   Value Meaning
  267.     0   To be selected font not found, no ticks
  268.     1   To be selected font found, and ticked  
  269.     2   No font entries found, menu consists one item; 'SystemFont',
  270.         and is ticked
  271.                                                                                   
  272.  R1 will point to the font menu on exit. An error occurs if no font menu exists. 
  273.  
  274.  
  275.  
  276. FontMenu_Deselect &8D083
  277. ------------------------
  278. On entry: ---
  279. On exit : --
  280.  
  281.  This will clear all ticks and marks of the font menu. It is not necessary
  282. to call this SWI before a FontMenu_Select call, as FontMenu_Select will take
  283. care of cleaning up old selection. An error occurs if no font menu exists. 
  284.   
  285.                               
  286.  
  287. FontMenu_DecodeFontMenu &8D084
  288. ------------------------------
  289. On entry: R0 = pointer to a list of font menu selections
  290.           R1 = pointer to a buffer to contain the answer 
  291.                (at least 48 bytes long)
  292. On exit : --
  293.  
  294.  This will decode the font menu selection into a font string for the
  295. FontManager. This string can be passed back to FontMenu_Select to tick the
  296. appropriate entries. An error occurs if no font menu exists. This call makes
  297. use of Wimp_DecodeMenu, but as it is possible that the returned string ends
  298. with 'Plain' (a made up name to distinguise an empty sub-name from the rest
  299. of the sub-names), it has to check for this, and throw away this last
  300. sub-name so the FontManager can recognise the required font.
  301.  
  302.  
  303.  
  304. FontMenu_Smash &8D085
  305. ---------------------
  306. On entry: --
  307. On exit : --
  308.  
  309.  This will release the font menu memory without looking at the amount of
  310. times FontMenu_Create was called.
  311.  
  312.  
  313.  
  314. FontMenu_ReCreate &8D086
  315. ------------------------
  316. On entry: --
  317. On exit : R0 = Number of fonts found
  318.  
  319.  This will release a existing font menu, and recreate it.
  320.  
  321.  
  322.  
  323.        ===========================================================
  324.  
  325.                 To contact the author of FontMenu, please write to:
  326.  
  327.                                            Joris RÖling
  328.                                            Verlengde Willemstraat 8a
  329.                                            9725 AW Groningen
  330.                                            The Netherlands
  331.  
  332.                                 Telephone: 050-271895
  333.  
  334.