home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / programs / fonts / a_q / fontwindow / !FntWinDoc / FntWinDocs < prev    next >
Text File  |  1993-03-02  |  21KB  |  634 lines
  1. Overview
  2.  
  3. Introduction
  4.  
  5.     The FontWindow module provides support for maintaining anti-aliased 
  6. font icons across screen resolution changes.  It also supports the use of 
  7. anti-aliased fonts in menus.
  8.  
  9.     The current situation is that if a window is opened at one screen 
  10. resolution and the user then changes screen resolution, then fonts are at 
  11. the wrong 'size'.  This is not acceptable.
  12.  
  13. Assumptions
  14.  
  15.     To do its' job the FontWindow module must make some assumptions 
  16. about each client:
  17.  
  18.     •    It is a wimp application (has a task handle)
  19.     •    The window definitions come from a template file
  20.     •    All windows are loaded from the template file at the same time
  21.     •    None of the fonts are closed by the program
  22.     •    The order of the icons must not change
  23.  
  24.     These are fairly mild restrictions, to say the least.  The reason why the 
  25. windows must be loaded (although not necessarily created) at the same 
  26. time is so that the font handles in all windows all have 'base' values.
  27.  
  28. Abstract window handle
  29.  
  30.     The FontWindow module uses an abstract window handle, and relies on 
  31. the client to map this to an actual (wimp) window handle.  In use this 
  32. usually means the abstract handle is one of the following:
  33.  
  34.     •    the actual wimp window handle
  35.     •    a pointer to a word containing the wimp window handle
  36.     •    a pointer to a structure used to hold information about a window
  37.  
  38.     There is built in support for the first two cases.
  39.  
  40.     If the abstract handle is the actual window handle, then windows with 
  41. anti-aliased title bar icons can not be handled − the title bar will remain 
  42. in the 'wrong' font across a resolution change.
  43.  
  44. Errors
  45.     The following errors may be generated by the FontWindow module:
  46.  
  47.     &110    Unknown FontWindow operation
  48.     &465C0    Unknown FontWindow task
  49.     &465C1    Unknown FontWindow window
  50.     &465C2    Bad version number for FontWindow
  51.     &465C3    FontWindow: reserved flags not zero
  52.     &465C4    FontWindow is currently active
  53.     &465C5    FontWindow: Window manager too old / not present
  54.     &465C6    FontWindow: illegal attempt to de/register menu
  55.     &465C7    Unknown FontWindow menu
  56.  
  57.     It should be fairly obvious how and when these would be generated.
  58.  
  59.  
  60. Menus
  61.  
  62.     From v1.10 it is possible for FontWindow to maintain a group of menus 
  63. with an anti-aliased font used for the item text.  The font is fixed for all 
  64. menus, but can be defined at initialisation.  Currently anti-aliased menu 
  65. title bars are not supported.
  66.  
  67.     Furthermore, it is possible to only allow the anti-aliased font to be used 
  68. in high resolution screen modes (>= 90 dots per inch), using the system 
  69. font at lower resolutions.
  70.  
  71.     All the client has to do is register each (sub) menu once, and that's all!  
  72. Registered menus are automatically updated at time of registration and 
  73. on a screen mode change.
  74.  
  75.     Note that due to a bug in the window manager v3.16, if you use an anti-
  76. aliased font in menus, and some of those menu items are NOT 
  77. indirected, then it SOMETIMES will not display that menu item.  From 
  78. v1.20 FontWindow can be told to automatically indirect such items.
  79.  
  80.     Because anti-aliased fonts are (generally) proportionally spaced, it is 
  81. possible that the (anti-aliased) menu may be too wide or, more likely, too 
  82. short.  From v1.20 FontWindow can be told to compute the width of the 
  83. menu.
  84.  
  85.  
  86. Revision History
  87.  
  88.     version 1.00 19-Jan-1993
  89.         Window support
  90.  
  91.     version 1.10 19-Feb-1993
  92.         Support for anti-aliased menus
  93.  
  94.     version 1.20 27-Feb-1993
  95.         Extension to anti-aliased menus, to auto-width the menu
  96.         and kludge around a window manager v3.16 bug
  97.  
  98.     version 1.21 02-Mar-1993
  99.         SWI allocation from Acorn: FontWindow, &465C0
  100.  
  101. The SWI's
  102.  
  103.     This chapter details the SWI's provided by the FontWindow module.
  104.  
  105. FontWindow_Initialise
  106. (SWI &465C0)
  107.  
  108.  
  109.     Register task with FontWindow module.
  110.  
  111. On entry    R0 = task handle
  112.     R1 = pointer to routine to allocate memory (see below)
  113.     R2 = pointer to routine to de-allocate memory (see below)
  114.     R3 = pointer to routine to decode an abstract window handle (see below)
  115.     R4 = pointer to routine to recreate a window (see below)
  116.     R5 = routines' R12
  117.     R6 = pointer to 256-byte font table to use while loading templates
  118.              zero to allocate and initialise one inside the RMA
  119.     R7 = version number * 100 of FontWindow that client knows about
  120.              bit 16    menus are to always have anti-aliased fonts
  121.              bit 17    menus are to have anti-aliased fonts only in high
  122.         resolution screen modes (>= 90 dots per inch)
  123.              bit 18    automatically calculate menu width if anti-aliasing
  124.              bit 19    force all menu items to be indirected if anti-aliasing
  125.              bits 20-31 are currently reserved and must be zero
  126.     R8 = (if flags in R7) pointer to block defining font to use in menus
  127.         +0    font x size, in points * 16
  128.         +4    font y size, in points * 16
  129.         +8    CR-terminated font name (strlen() < 40)
  130.  
  131. On exit    R0 = pointer to 256-byte font table to use while loading templates
  132.  
  133. Interrupts    -
  134.  
  135. Processor Mode    Processor is in SVC mode
  136.  
  137. Re-entrancy    SWI is re-entrant
  138.  
  139. Use    This call registers a wimp application with the FontWindow module.  
  140. The client supplies the address of routines used to de/allocate memory 
  141. and process the abstract window handle.  Fortunately there are default 
  142. routines supplied for the most common cases.
  143.  
  144.     If R6=0 then a 256-byte font table is allocated for you.
  145.  
  146.     The version supplied in R7 must be >= 100.
  147.  
  148.     If the client wishes to use anti-aliased fonts in menus then set bit 16/17 
  149. of R7, ensure that the version >= 110, and point R8 to a block defining 
  150. which font to use.  If R8=0 then the default font is used − Homer
  151. ton.Medium at 14 points.
  152.  
  153.     Due to a bug in the window manager v3.16 if you mix indirected and 
  154. non-indirected menu items with anti-aliased fonts, then the occasional 
  155. non-indirected item will not display.  To remedy this, setting bit 19 of 
  156. R7 (and setting the version to >= 120) will cause FontWindow to force 
  157. all items to be indirected.  This appears to work.
  158.  
  159.     If you use fonts in menu items then the occasional item may become too 
  160. wide for the menu (with a width calculated using the system character 
  161. set).  Since it is inconvenient to change the text of menu items, FontWin
  162. dow can compute the width of anti-aliased menu items by setting bit 18 
  163. of R7 (and setting the version to >= 120).
  164.     The routines are all entered in SVC mode, with R12 set as requested, and 
  165. R13 pointing to the usual SVC full-descending stack.  The routines may 
  166. corrupt R0-R3, R10-R12, R14.  All PSR flags must be preserved, except 
  167. as indicated.
  168.  
  169. R1 − allocate memory
  170. On entry    R0 = byte-aligned size of memory to allocate
  171. On exit    R0 = pointer to word-aligned memory
  172.     PSR_V clear if ok
  173.     PSR_V set and R0 = error block if error
  174.  
  175.     If R1 = 0 then a suitable routine that allocates memory from the RMA is 
  176. used.  Note that the routine is entered in SVC mode.
  177.  
  178.     This routine is used to allocate memory for each window registered, and 
  179. also to allocate a temporary buffer used when recreating a window.
  180.  
  181.  
  182. R2 − de-allocate memory
  183. On entry    R0 = pointer to previously allocated memory, or zero [do nothing]
  184. On exit    -
  185.  
  186.     If R2 = 0 then a suitable routine that de-allocates memory from the RMA 
  187. is used.
  188.  
  189.     This is called when a window is deleted, or to delete the temporary 
  190. buffer used when recreating a window.
  191.  
  192.  
  193. R3 − decode abstract window handle
  194. On entry    R0 = abstract window handle
  195. On exit    R0 = wimp window handle
  196.  
  197.     If R3 = 0 then a suitable routine that treats the abstract window handle as 
  198. the actual window handle is used.
  199.  
  200.     If R3 = 1 then a suitable routine that treats the abstract window handle as 
  201. a pointer to the actual window handle is used.
  202.  
  203.     This is called at many different points.
  204.  
  205.  
  206. R4 − recreate window
  207. On entry    R0 = abstract window handle
  208.     R1 = pointer to wimp_winfo block [ie after Wimp_GetWindowInfo]
  209. On exit    -
  210.     PSR_V clear if ok
  211.     PSR_V set and R0 = error block if error
  212.     The entry R1 block contains a wimp_openstr for the recreated window
  213.  
  214.     This routine will be called when a windows' title bar is anti-aliased and 
  215. needs to be changed to a new font.  The only way to do that is to: read 
  216. the current window definition, delete the window, change the title bar 
  217. icon, and immediately re-create the window.
  218.  
  219.     On entry R1+0 is the wimp window handle and R1+4 is the window 
  220. definition, the title bar icon has been altered.  This routine should delete 
  221. the window, immediately re-create it and then update its' copy of the 
  222. wimp window handle.  Incase the window was already open, the 
  223. FontWindow module may need to re-open it and so the (new) wimp 
  224. window handle should be stored at R1+0 before returning.
  225.  
  226.     If R4 = 0 then a suitable routine that treats the abstract window handle as 
  227. the actual window handle is used.  This means that it is not possible to 
  228. recreate the window (since the caller will not know about the new 
  229. window handle) and so the routine simply clears PSR_V and returns.
  230.  
  231.     If R4 = 1 then a suitable routine that treats the abstract window handle as 
  232. a pointer to the actual window handle is used.
  233.  
  234. FontWindow_CloseDown
  235. (SWI &465C1)
  236.  
  237.  
  238.     Remove task from FontWindow module.
  239.  
  240. On entry    R0 = task handle
  241.     R1 = non-zero if close all open fonts
  242.     R2 = non-zero if should delete window(s) as well
  243.  
  244. On exit    -
  245.  
  246. Interrupts    -
  247.  
  248. Processor Mode    Processor is in SVC mode
  249.  
  250. Re-entrancy    SWI is re-entrant
  251.  
  252. Use    This call removes a wimp application, and any registered windows, from 
  253. those registered with the FontWindow module.  At the time of this call 
  254. the task must be active.
  255.  
  256.     If R2 is non-zero then the registered windows are actually 
  257. Wimp_DeleteWindow'ed as well.  This is usually not necessary.
  258.  
  259.     If R1 is non-zero then the 256-byte font table is used to close all fonts 
  260. opened by the application.  This is usually quite handy.
  261.  
  262. FontWindow_ModeChange
  263. (SWI &465C2)
  264.  
  265.  
  266.     Handle screen mode being changed.
  267.  
  268. On entry    R0 = task handle
  269.  
  270. On exit    -
  271.  
  272. Interrupts    -
  273.  
  274. Processor Mode    Processor is in SVC mode
  275.  
  276. Re-entrancy    SWI is re-entrant
  277.  
  278. Use    This should be called whenever a Message_ModeChange message is 
  279. received by the task.  If this is not done then the FontWindow module 
  280. can not work.
  281.  
  282.     If the screen resolution has changed (unlikely) the fonts used by the 
  283. application are closed and then re-opened at the new resolution.  If any 
  284. registered windows are currently open then they are automatically 
  285. updated.  This strategy ensures minimum overhead in the most common 
  286. case − nothing to be done.
  287.  
  288.     In actual fact the fonts are not closed.  This is because of a bug in the 
  289. Wimp v3.10 demonstrated by the following sequence.  Start application 
  290. (load template with writable icon) in a high-resolution mode; go down to 
  291. a low-resolution mode; change wimp_createstr block so fonts point to 
  292. new font handles for current screen resolution; call 
  293. Wimp_CreateWindow; press Reset button.
  294.  
  295.     To get around this FontWindow currently leaves fonts open once at each 
  296. resolution used by the application.  Not ideal, but it works.
  297.  
  298. FontWindow_CreateWindow
  299. (SWI &465C3)
  300.  
  301.  
  302.     Create the window.
  303.  
  304. On entry    R0 = task handle
  305.     R1 = pointer to wimp_createstr block
  306.     R2 = abstract window handle, or zero
  307.  
  308. On exit    R0 = window handle
  309.     R1 = non-zero if window contained anti-aliased font icon(s)
  310.     R1 block updated to reflect current resolution
  311.  
  312. Interrupts    -
  313.  
  314. Processor Mode    Processor is in SVC mode
  315.  
  316. Re-entrancy    SWI is re-entrant
  317.  
  318. Use    This call may update the windows' icons if necessary, then does a 
  319. Wimp_CreateWindow.  If the window contains any anti-aliased font 
  320. icons then the details of these are cached for later operations on the 
  321. window.
  322.  
  323.     This SWI can be called at any time, but the wimp_createstr block must 
  324. have come directly from the template file (so all windows passed to this 
  325. routine have 'base' font handles).
  326.  
  327.     The special case where R2 = 0 is used for simple applications, and sets 
  328. the internal copy of the abstract window handle to the wimp window 
  329. handle.  In all other cases it is necessary for the caller to store the details 
  330. of the window handle as returned.
  331.  
  332.     The return value in R1 can be used to determine if the window did 
  333. contain any anti-aliased font icons.
  334.  
  335. FontWindow_DeleteWindow
  336. (SWI &465C4)
  337.  
  338.  
  339.     Delete a window that has cached information.
  340.  
  341. On entry    R0 = task handle
  342.     R1 = abstract window handle
  343.  
  344. On exit    -
  345.  
  346. Interrupts    -
  347.  
  348. Processor Mode    Processor is in SVC mode
  349.  
  350. Re-entrancy    SWI is re-entrant
  351.  
  352. Use    This call removes a previously registered window, and then deletes it 
  353. (using Wimp_DeleteWindow).
  354.  
  355. FontWindow_OpenWindow
  356. (SWI &465C5)
  357.  
  358.  
  359.     Update a registered windows' anti-aliased icon definitions (if necessary) 
  360. and then open the window.
  361.  
  362. On entry    R0 = task handle
  363.     R1 = pointer to wimp_openstr block [window handle not filled in]
  364.     R2 = abstract window handle
  365.  
  366. On exit    -
  367.     R1+0 holds current window handle
  368.  
  369. Interrupts    -
  370.  
  371. Processor Mode    Processor is in SVC mode
  372.  
  373. Re-entrancy    SWI is re-entrant
  374.  
  375. Use    This call will update the windows' icons if they contain references to 
  376. font handles opened to a different resolution than the current screen 
  377. resolution.  It then opens the window at the requested position.
  378.  
  379.     This call is almost redundant.  Because the FontWindow_CreateWindow 
  380. leaves the window ready for the current resolution this SWI is only 
  381. necessary if you create your windows in one go and only open them at 
  382. some later time.
  383.  
  384.     There is no need (normally) to use this call when the application receives 
  385. a Message_OpenWindow, as the window would already be open − and 
  386. hence contain the correct font handles.
  387.  
  388. FontWindow_Update
  389. (SWI &465C6)
  390.  
  391.  
  392.     Update a registered windows' anti-aliased icon definitions.
  393.  
  394. On entry    R0 = task handle
  395.     R1 = abstract window handle
  396.  
  397. On exit    -
  398.  
  399. Interrupts    -
  400.  
  401. Processor Mode    Processor is in SVC mode
  402.  
  403. Re-entrancy    SWI is re-entrant
  404.  
  405. Use    This call will update the windows' icons if they contain references to 
  406. font handles opened to a different resolution than the current screen 
  407. resolution.  Consider it as a pre-processor before opening the window.
  408.  
  409.     This call is usually used on dialogue boxes used as a sub-menu.
  410.  
  411. FontWindow_RegisterMenu
  412. (SWI &465C7)
  413.  
  414.  
  415.     Register a wimp menu with the FontWindow module.
  416.  
  417. On entry    R0 = task handle
  418.     R1 = pointer to wimp menu block
  419.  
  420. On exit    -
  421.  
  422. Interrupts    -
  423.  
  424. Processor Mode    Processor is in SVC mode
  425.  
  426. Re-entrancy    SWI is re-entrant
  427.  
  428. Use    This call will allow FontWindow to transparently update the registered 
  429. menu's anti-aliased font status in accordance with the flags set by 
  430. FontWindow_Initialise.
  431.  
  432.     Note that this call does not register any of the menus' sub-menus.  Each 
  433. sub-menu must be registered separately.
  434.  
  435.     It is assumed that the menu being registered uses the system font for its' 
  436. menu items − which is not unreasonable.  After this call the menus' items 
  437. may now be anti-aliased, if necessary.
  438.  
  439.     Anti-aliased menu title bars are not currently supported.
  440.  
  441.     Note that if you intend to swap a menu between font/system and the 
  442. menu contains items coloured other than black text on a white back
  443. ground, then it is essential that these items be indirected and include a 
  444. validation string with an "F<back><fore>" validation.  This is particu
  445. larly true for 'colour-selection' menus.  If no such validation string is 
  446. found then when converting from font to system, FontWindow will 
  447. make the item black text on a white background.
  448.  
  449.     Each registered menu uses approximately 28 bytes of (user-supplied) 
  450. memory, plus any extra memory required if items are forced to become 
  451. indirected (24 bytes each).
  452.  
  453. FontWindow_DeRegisterMenu
  454. (SWI &465C8)
  455.  
  456.  
  457.     De-register a wimp menu from the FontWindow module.
  458.  
  459. On entry    R0 = task handle
  460.     R1 = pointer to wimp menu block
  461.     R2 = non-zero if force menu items to system font
  462.  
  463. On exit    -
  464.  
  465. Interrupts    -
  466.  
  467. Processor Mode    Processor is in SVC mode
  468.  
  469. Re-entrancy    SWI is re-entrant
  470.  
  471. Use    This call pulls the previously registered menu from the list that are 
  472. automatically maintained by the FontWindow module.
  473.  
  474.     If the menus' items were anti-aliased at the start of this call, and R2<>0 
  475. then the menu will be converted back to using the system font.  This uses 
  476. any "F<back><fore>" validation string if found, defaulting to black text 
  477. on a white background if not found.
  478.  
  479.     All registered menus are automatically de-registered by the call to 
  480. FontWindow_CloseDown.
  481.  
  482. *Commands
  483.  
  484.     This chapter documents the *Commands provided by the FontWindow 
  485. module.  All two of them.
  486.  
  487. *FontWindow
  488.  
  489.     This does nothing, it is provided as a *Help command to display a short 
  490. description of the purpose of the module.
  491.  
  492. *Desktop_FontWindow
  493.  
  494.     This command causes the FontWindow module to be entered as the 
  495. current application.  This starts a wimp application that monitors tasks 
  496. dyeing, and takes some actions if the task was initialised for use with the 
  497. FontWindow module.
  498.  
  499.     This feature can be used while developing applications that 'crash' 
  500. without exiting cleanly.  The FontWindow wimp task will quietly close 
  501. all fonts opened by the application.  This is useful over a long program
  502. ming session or where font handles become scarce.
  503.  
  504.     However, this can only be done if the default memory de/allocation 
  505. routines are used and the font-table was auto-allocated.
  506.  
  507.     Since the FontWindow task has no icon bar icon, and informs the wimp 
  508. that it is only interested in Message_TaskCloseDown, there should be no 
  509. performance degradation in using this debugging aid.
  510.  
  511.     The total memory usage of this feature is <3/4K.
  512.  
  513. Examples
  514.  
  515.     This chapter shows how you would actually incorporate these routines 
  516. into your current wimp (basic/arm) libraries.  In practise, ARM programs 
  517. are extremely easy to convert to use of FontWindow.  Basic programs 
  518. less so.
  519.  
  520.     The !Demo application contains Basic source code for two types of 
  521. application − simple stuff that never clones template windows, and a 
  522. full-blown multi-document application.
  523.  
  524. !Run files
  525.  
  526.     You wouldn't forget to include something like the following, would you:
  527.  
  528.     Set App$Path <App$Dir>.,System:Modules.
  529.  
  530.     RMEnsure FontWindow 1.21 RMLoad App:FontWindow
  531.     RMEnsure FontWindow 1.21 Error FontWindow module too old
  532.  
  533.     Note that you should use v1.21 in the above RMEnsures, as before this 
  534. FontWindow used a (user) SWI chunk.
  535.  
  536. Simple app's
  537.  
  538.     By simple, it is meant an application that never clones any of its' 
  539. template windows.  It just creates one window from each window in the 
  540. template.  Also, no window will have anti-aliased title bar icons.  The 
  541. vast majority of applications fall into this range.
  542.  
  543.     Just after your Wimp_Initialise add the following:
  544.  
  545.     FontWindow_Initialise, <task handle>, 0, 0, 0, 0, <R12>, 0, 100 TO 
  546. <font table>
  547.  
  548.     This font table should then be used when you load templates.
  549.  
  550.     Now, just before your Wimp_CloseDown insert:
  551.  
  552.     FontWindow_CloseDown, TRUE, FALSE
  553.  
  554.     which closes all the fonts for you.
  555.  
  556.     Don't forget to add a call to FontWindow_ModeChange if you receive a 
  557. Message_ModeChange − this is essential.
  558.  
  559.     Now, instead of calling Wimp_CreateWindow, you would use 
  560. FontWindow_CreateWindow.  Use the returned window handle as the 
  561. 'abstract window handle' in all future calls regarding this window.
  562.  
  563.     For dialogue boxes use a call to FontWindow_Update before the call to 
  564. Wimp_CreateSubMenu.
  565.  
  566.     If you do open the window later use FontWindow_OpenWindow in 
  567. place of Wimp_OpenWindow.
  568.  
  569.     That's all there is to it.
  570.  
  571.  
  572. Large app's
  573.  
  574.     These include multi-document applications and ones that contain 
  575. windows with anti-aliased title bar icons.
  576.  
  577.     These are the most awkward, as there are both cloned windows and 
  578. (constant) dialogue boxes − but everything has to be treated the same in 
  579. respect to the FontWindow module.
  580.  
  581.     We use the 'built-in' abstract handle that is a pointer to the real window 
  582. handle.  Other than that you follow the same steps as for small appli
  583. cations.  So, to start up use:
  584.  
  585.     FontWindow_Initialise, <task handle>, 0, 0, 1, 1, <R12>, 0, 100 TO 
  586. <font table>
  587.  
  588.     Now for each dialogue-box window you have to reserve a word of 
  589. memory to store the actual window handle, and use this pointer as the 
  590. abstract window handle.  This means all references in the source code to 
  591. the window handle now need to be changed to refer to the contents of 
  592. this word of memory.  Ho hum.
  593.  
  594.     For 'document' windows it is assumed you already store the window 
  595. handle as part of a larger structure, and so the use of this is trivial.
  596.  
  597. Allocate routine
  598.  
  599.     Here's the default memory allocation routine:
  600.  
  601.             MOV     R1, lr
  602.             MOV     R3, R0
  603.             MOV     R0, #ModHandReason_Claim
  604.             SWI     "XOS_Module"
  605.             MOVvc   R0, R2
  606.             BICvcS  pc, R1, #PSR_V
  607.             ORRS    pc, R1, #PSR_V
  608. Deallocate routine
  609.  
  610.     Here's the default memory de-allocation routine:
  611.  
  612.             MOV     R1, lr
  613.             MOVS    R2, R0
  614.             MOVne   R0, #ModHandReason_Free
  615.             SWIne   "XOS_Module"
  616.             MOVS    pc, R1
  617.  
  618. Recreate routine
  619.  
  620.     Here's the default routine used to recreate a window if the abstract 
  621. window handle is a pointer to the actual window handle:
  622.  
  623.             MOV     R3, R0
  624.             MOV     R2, lr
  625.             SWI     "XWimp_DeleteWindow"
  626.             ADDvc   R1, R1, #4
  627.             SWIvc   "XWimp_CreateWindow"
  628.             STRvc   R0, [R3], #0
  629.             SUBvc   R1, R1, #4
  630.             STRvc   R0, [R1, #u_handle]
  631.             BICvcS  pc, R2, #PSR_V
  632.             ORRS    pc, R2, #PSR_V
  633.  
  634.