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