home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / f / fonter / !Fonter / FntMenuDoc < prev    next >
Text File  |  1990-04-28  |  15KB  |  333 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 FontM