home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / d / discbase / !DiskBase / FntMenuDoc < prev    next >
Text File  |  1991-03-20  |  17KB  |  354 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 p