The Datafile PD-CD 4

home *** CD-ROM | disk | FTP | other *** search

/ The Datafile PD-CD 4 / DATAFILE_PDCD4.iso / utilities / utilsf / fontpool / PoolHelp / HelpData next >

Wrap

Text File | 1995-01-12 | 15.3 KB | 345 lines

FontPool_Hello In: R1 = <Configuration word=>FontPool_Hello_R1> (same as <FontPool_Configure>) Out: R0 -> Menu-pointer. Every client should call this SWI once on startup. 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=>Alphabetize>' won't come into effect until the font-menu is next built. Calling this SWI by itself does not automatically re-generate the menu. To force it to be re-buildt, use FontPool_Configure. <Using FontPool_Hello..=>Using_FontPool_Hello>FontPool_Goodbye In: - Out: - If there are no more clients using FontPool, the internal menu-structure is forgotten and the memory is returned to the RMA. <Using FontPool_Goodbye..=>Using_FontPool_Hello>FontPool_Configure In: R1 = <Configuration word=>FontPool_Hello_R1> (same as <FontPool_Hello>) R2 = <TRUE=>FontPool_Configure_R2> => 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 = &<xxx=>xxxyyy><yyy=>xxxyyy><hh> where xxx = x-point size (*16) yyy = y-point size (*16) hh = Menu-item height. R4 is used only if R3 is not 0! Out: R0 -> <Possibly new menu-pointer=>PossiblyNewMenuPtr>. The menu MUST be rebuilt if changes to the <alphabetisation value=>Alphabetize> 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.) If an anti-aliased font is specified it overrides any forground and background colours that might be configured - forcing them to be black on white. <Using FontPool_Configure..=>Using_FontPool_Configure>FontPool_CreateMenu In: R1 can be any of the following: = Handle of font to be ticked ->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=>PossiblyNewMenuPtr> 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>. You then specify the root-menu in R4 to reproduce the full menu-structure. <Using FontPool_CreateMenu..=>Using_FontPool_CreateMenu>FontPool_CreateSubMenu In: R1 can be any of the following: = Handle of font to be ticked ->FontName = -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=>PossiblyNewMenuPtr> 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. <Using FontPool_CreateSubMenu..=>Using_FontPool_CreateSubMenu>FontPool_MenuSelection In: R1 ->Menu data-structure. or = 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. <Using FontPool_MenuSelection..=>Using_FontPool_MenuSelection>FontPool SWIs available in FontPool v0.12 #Prefix FontPool_ <Hello > <Goodbye > <Configure > <CreateMenu > <CreateSubMenu> <MenuSelection> - - - - - - - - - <Terms of use =>TermsOfUse>R4=&xxxyyyhh xxx = x-point size (*16) yyy = y-point size (*16)R4=&xxxyyyhh 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.) So values above 7 are taken as explicit menu-item height.Using FontPool_Hello & FontPool_Goodbye 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 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. <Note..=>NOTE1>Using 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>). 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. <Note..=>NOTE1>Using 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. <Note..=>Note1>Using 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) 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. Be aware 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 (s)he could use this as an indication that the system-font should be used instead. FontPool keeps no internal reference of which font is currently selected (since there can be many clients). This gives more freedom to the programmer. <Note..=>NOTE2>Using FontPool_Configure This SWI allows you to change FontPool's configuration at any time. 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. <Note..=>NOTE1>FontPool_Configure R2 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_CreateMenu> or <_CreateSubMenu=>FontPool_CreateSubMenu> is called).Configuration word If bit#31 of this word is clear the whole word is ignored, otherwise the following applies: 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=>Alphabetize>' 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. bits#20-30 Reserved. Set to 0! bit#31 must be set or this word is ignored!Alphabetize value The alphabetize value specifies how long the menu can grow before font-families starting with the same initial character are collected in a sub-menu. The value is specified in menu-items.Possibly new menu-pointer Possibly new menu-pointer means that the full menu could not be held in the 'old' RMA-block. This will only happen if the menu is re-build due to a change in the Font$Path.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'.Terms of use FontPool costs nothing unless you use its facilities in a program. Once you do, you should decide what category your program fall under (see below) and pay <me=>Me> at least this minimum charge. If you find FontPool exceptionally useful you are of course welcome to pay more, and if this sum is at least MinimumCharge+£5 you will automatically receive the next version of FontPool as soon as it becomes available. To prevent the nuicance of royalties I have adobted the following scheme: <Personal use..=>PersonalUse> <Shareware.. =>SharewareUse> <Commercial.. =>CommercialUse>Personal use: If you are using FontPool in your own personal programs or programs that are distributed free of charge, you should pay a minimum of £5. This sum covers ALL such programs that originate from the buyer. <Distribution note..=>DistributionNote>Shareware: If you are using FontPool in Shareware programs, or any type of program you charge for, you should pay at least £10. This sum covers ALL such programs that originate from the buyer, and also those mentioned under <Personal=>PersonalUse> <use=>PersonalUse>. An alternative is a swap. If you have produced something that you think I might find useful (and with a low bug- count) we could do an old-fashioned swap. (Then let me know what it is through Arcade before sending anything.) <Distribution note..=>DistributionNote>Commercial: If you are using FontPool in a commercial application it costs £20 for each DIFFERENT application using it. The application's name must then be given when <registering=>Me>. £50 buys the right to use FontPool in all present and future commercial applications that originate from the buyer.Distribution note If FontPool is used as a part of a program that is distributed as public domain, Shareware or any such derivative, FontPool may be enclosed in two ways: - You state clearly in your documentation that your program utilises FontPool's font-menu facilities and that FontPool is a Shareware utility. Also it should say from what general source your copy of FontPool originated (what BBS or Shareware library). You are then allowed to enclose JUST the FontPool module by itself with NONE of the other files. - You enclose a FULL copy of FontPool with ALL associated files in an UNMODIFIED state.Registering: To register as a FontPool user, state your program's category and send money to the following address: Eirik Hansen Industriveien 12 8500 Narvik Norway I can also be contacted at Arcade where I'm user #440 (private mail please). Your comments and suggestions are very much appreciated! Especially if you think there are dissuasive shortcomings that prevents you from using FontPool.