In: If bit#31 of R1 is set it means it contains some configuration
concerning the presentation of the menus as follows:
bits#0-3 fg col to use on selected items def. 7
bits#4-7 bg.. def. 0
bits#8-11 fg col to use on unselected items def. 7
bits#12-15 bg.. def. 0
The selected menu-items will always be ticked - even if the
specified colour is not the default.
bits#16-19 'Alphabetize value' for the menu. def. 12
This is to make the programmer able to reconfigure the
font-menu if a user with eg. a huge multisync screen
should want a longer menu. This value is probably most
useful if set with FontPool_Configure (below) because
you can there force the menu to be re-built.
bits#20-30 Reserved
bit#31 must be set or this word is ignored!
Out: R0 -> Menu-pointer.
Every client should call this SWI once on startup and FontPool_Goodbye when it terminates (or does not need FontPool anymore). R1 overwrites any earlier configuration that might be present if bit#31 is set - else R1 is ignored and the previous configuration reigns. Note that the value for 'alphabetisation' won't come into effect until the font-menu is next built. Calling this SWI by itself does not automatically regenerate the menu. (To force it to be regenerated use FontPool_Configure.)
In: R1 = Same as for FontPool_Hello (above). Note that bit#31 must be set
or R1 is ignored!
R2 = TRUE => The menu is rebuilt instantly by (re-)reading the
available fonts from disc.
= FALSE => the menu is not rebuilt until FontPool detects a change
in the number of available fonts.
R3 -> FontName for font-menu font. If system-font is required R3
should point to a null-string.
= 0 => Ignored!
R4 = &xxxyyyhh where
xxx = x-point size (*16)
yyy = y-point size (*16)
hh = Menu-item height. Since small values would make the
menu unreadable, values 0 through 7 are reserved for
special actions:
= 0 => check strings before deciding height (will be
somewhat more compact than =1).
= 1 => use natural font-height (line-spacing)
The difference between a value of 0 and 1 becomes
apparent if you try eg. the font 'Portrhouse.Standard'
(at size 10).
2-7 are reserved for future expansion. (Might in the
future be used to specify if the given font should
apply to either selected or unselected menu-items.
This way the selected font can be 'highlighted' by
using bold or italic.)
R4 is used only if R3 is not 0!
Out: R0 -> Possibly new menu-pointer.
Note that the menu MUST be rebuilt if changes to the alphabetisation value is to come into effect. This means that bit#31 of the configuration word (in R1) must be set and R2 must be TRUE. (The alphabetisation value is the only parameter that requires the font-menu to be rebuilt before it is actually applied to the menu.)
You can force the menu to be re-built at ANY time without changing the configuration by calling with R1=0 (actually bit#31 clear) and R2=TRUE. This is to aid RISC OS 3 programmers. This feature would only be rarely needed since re-reading the menu is probably best deferred until the user actually needs to access the font-menu (ie. when either of FontPool_Create(Sub)Menu is called).
Note that if an anti-aliased font is specified the forground and background colours will always be black on white.
->FontName (This is necessary because the old font manager maps
font-handles to different names than what is produced
by Font_ListFonts.)
= -1 => do not tick any
= 0 => do not tick any
R2 = x of top-left corner of menu.
R3 = y..
R4 ->Parent menu or
= 0 => use font-menu directly.
Out: R0 -> Possibly new menu-pointer.
R4 might seem superflous, but it is meant to be used if the user does a menu-selection with ADJUST (to make the menu stay on screen) and the font-menu was opened with FontPool_CreateSubMenu below. You then specify the root-menu in R4 to reproduce the full menu-structure.
If R1 > 255 on entry it is taken as a pointer to a font-name, else it is either a font-handle or null. R1 can also point to a null-string in which case it is the same as calling with R1=0.
= 0 => The top level menu was the font-menu itself.
R2 ->Block as returned by Wimp_Poll(9) - list of MenuSelections
R3 ->Buffer where to put FontName or
= 0 => Use internal buffer for FontName and return pointer in R3.
Out: If the exact menu-item you selected was ticked then
R0 = FALSE (can be regarded as if the system font is selected)
R3 = bogus (actually ->FontName on entry)
else
R0 = TRUE
R3 ->FontName (which might be the same as given on entry)
If it is deduced that the user clicked on an item not in the font-menu, it will be taken as a deselect-all-fonts command (ie. it returns with R0=FALSE & R3=?).
If R3=0 on entry a copy of the returned name should be taken since the internal buffer might be overwritten.
When FontPool_Hello is called (which would in most cases be when an application starts up), the internal font-menu is built (and the memory 'shrinkwrapped' around it). It is only built, of course, if no font-menu already exists in memory. Calling FontPool_Hello also increases an internal 'client-counter'. This counter is decreased every now and then... just kidding!.. it is decreased when FontPool_Goodbye is called. FontPool_Goodbye should be called when an application no longer needs the services of FontPool (eg. when the application terminates). So when there are no more FontPool clients, the internal font-menu is forgotten about, and the memory occupied by the font-menu is returned to the RMA.
In between FontPool_Hello and FontPool_Goodbye there are three SWIs available to utilise the font-menu. These SWIs are:
FontPool_CreateMenu
FontPool_CreateSubMenu
FontPool_MenuSelection
FontPool_CreateMenu
-------------------
When an application wants to show the font-menu directly, FontPool_CreateMenu would be called. This is similar to calling Wimp_CreateMenu and simply displays the full menu at the coordinates specified. In addition to the screen-position, FontPool can be instructed to tick a specified font (eg. the applications current font). This is done by either inputting the font's handle or its name (as read by Font_ListFonts, and also returned by FontPool_MenuSelection below). If a handle is given, it is converted to a font-name by means of Font_ReadDefn. The name is then matched with those currently available in the internal font-menu. If a match is detected, the font is ticked (and possibly coloured).
NOTE that the font-handle way is not safe with old FontManagers. This is because Font_ReadDefn might return a different name than Font_ListFonts did when reading in the menu. The net result is that no font will then be ticked. So for compatibility - use the font-name when instructing FontPool to tick a font.
FontPool_CreateSubMenu
----------------------
FontPool_CreateSubMenu makes it possible to attach the font-menu to another menu-item in a higher level menu (this would in most cases be the way applications show their font-menu). Since the available fonts might change between calls to FontPool (because the Font$Path has changed) FontPool_CreateSubMenu should be called as a result of a Msg_SubMenuWarning. Ie. the menu-entry that is to reveal the font-menu should have bit#3 in its item flags set so that the wimp generates a message when the mouse moves over the item.
FontPool_MenuSelection
----------------------
When the application detects a menu-selection in the font-menu it should call FontPool_MenuSelection with pointers to both the menu-structure and the block returned by Wimp_Poll (reason code 9 - list of menu-selections). The menu-structure pointer can be 0 if the font-menu was opened directly (ie. by using FontPool_CreateMenu). If it was opened indirectly (by the FontPool_CreateSubMenu procedure described above) you need to input the pointer to the root-menu (which is one the application has created itself). This is so FontPool can make sense of the list of menu-selections that is returned in Wimp_Poll and return the correct font-name. On exit from FontPool_MenuSelection you are told if there is a font ticked, and if there is, the name of the font is returned. Note that if the user selects (clicks) the item the font-menu is attached to (ie. one level above the actual font-menu) it is taken as a deselect-all-fonts command. This is deduced by the list of menu-selections passed to FontPool_MenuSelection.
NOTE that it is completely up to the application programmer to decide what to do when FontPool_MenuSelection returns telling you that there is no font currently selected (when the user clicked on an already selected font). The programmer could then either 'keep' the currently selected font, and pass it on to FontPool the next time the menu is opened to make sure it is ticked. Or she could use this as an indication that the system-font should be used instead. Or he could decide to hang upside-down for a few minutes to get the blood back into his bewildered pale face while willing the font to return.
FontPool keeps no internal reference of which font is currently selected (since there can be many clients). This gives more freedom to the programmer.
FontPool_Configure
------------------
This SWI allows you to change FontPool's configuration at any time. The details are found above. Keep in mind though that changing the configuration will affect all applications using FontPool! This might sound as a drawback at first, but the user is actually likely to want the font-menu to look similar (if not identical) in all applications. Also note that FontPool_Configure is the only call that can alter the font used when displaying the menu.
NOTE1
-----
Two points concerning FontPool_Hello, _Configure, _CreateMenu and _CreateSubMenu:
1) They might return with an error if the FontManager is not available, or the Font$Path is stupid. This error should probably be trapped (and ignored) during the startup-process of the application (_Hello). If not, the application is likely to terminate before it has got its wheels in motion.
2) On exit a pointer to the internal menu-structure is returned. This is important to note if you are displaying the menu by means of FontPool_CreateSubMenu since the submenu-pointer should be updated in the relevant higher level menu-item. If this is not done FontPool_MenuSelection can go horribly wrong !! The pointer can change between these calls due to more fonts becoming available.
NOTE2
-----
If the user selects (clicks) on a non-leaf item in the menu - and the item is not selected (ticked), it is regarded as selecting the top-most item(s) in the rest of the selected item's submenu(s). So clicking directly on the item 'Trinity' is regarded as selecting 'Trinity.Bold.(Plain)', and the font-name returned from FontPool_MenuSelection will be 'Trinity.Bold'.
NOTE3
-----
The SWI chunk base number was picked 'semi-random' and was not obtained from Acorn. (The base-number was 'borrowed' from an elderly module that, as far as I know, was never used. If someone out there should experience a clash, please inform me, and I might ask Acorn, the speed-demons, for one.)
