home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / desktop / outlnwimp_1 / !WimpPatch / !Help next >
Text File  |  1995-11-21  |  18KB  |  511 lines
  1. Instructions for !WimpPatch and OutlineWimp by Andrew Sellors
  2.  
  3. *****************************************************************************
  4. * NOTE:                                                                     *
  5. * !WimpPatch and OutlineWimp (outlnwimp) are Shareware.                     *
  6. * They are part of the Outline Wimp desktop enhancement package and must    *
  7. * not distributed without the accompanying files.                           *
  8. *                                                                           *
  9. * You may use this software for a trial period of 30 days. If, after this   *
  10. * you decide you would like to continue using it then you are required to   *
  11. * Register. See the ReadMe1st file for details of registering               *
  12. *                                                                           *
  13. * This version maybe freely copied and distributed, provided that it is     *
  14. * complete with all original files, and that you do not sell it.            *
  15. * PD libraries may charge a nominal fee for the cost of duplication,        *
  16. * postage etc.                                                              *
  17. *                                                                           *
  18. * In no circumstances shall the author be liable for any damage, loss of    *
  19. * profits, time or data or any indirect or consequential loss rising out of *
  20. * the use of this software or inability to use this software.               *
  21. *****************************************************************************
  22.  
  23. Contents:
  24. ---------
  25.  
  26. Features
  27. OverView
  28. Patching the WindowManager
  29. Installing the new WindowManager
  30. Configuring the new WindowManager
  31. Justification
  32. OS_Write replacement SWIs
  33. Text and sprite indirected icons with right justified text
  34. Technical information
  35. Contacting the author
  36.  
  37. ********************************************************************************
  38.  
  39. Features
  40. --------
  41.  
  42. !WimpPatch (new WindowManager)
  43. ------------------------------
  44.  
  45. Uses outline fonts instead of the system font in all icons (both single and
  46. multiple line varieties).
  47. Note: Some text may still appear in the system font. This is due to the fact
  48. that it is the application concerned is plotting the text and not the WIMP.
  49. Particular offenders are BASIC programs which use PRINT to display text on
  50. the WIMP.
  51.  
  52. Right justifies key short-cut text in menus. (configurable)
  53.  
  54. Replaces the up arrow with a specified character as most outline fonts do not
  55. have an up arrow character. (configurable)
  56.  
  57. Uses font 'WimpMisc' (supplied) for the characters that are undefined in normal
  58. outline fonts such as the arrow characters. (configurable)
  59.  
  60. Caret positioning takes account of proportional spaced letters.
  61.  
  62. Does not intercept SWI vector and so does not slow SWI system down.
  63.  
  64. OutlineWimp (support module)
  65. ----------------------------
  66.  
  67. Handles outline font on mode changes to make sure the correct font aspect ratio
  68. is used at all times.
  69.  
  70. Provides * commands to set all the options mentioned above.
  71.  
  72. Saves current settings in the "DeskBoot" file.
  73.  
  74. Provides SWIs as replacements for OS_WriteC, OS_Write0 and OS_WriteN which plot 
  75. outline fonts rather than the system font to allow other programs that write 
  76. directly to the screen to be patched easily (like the filer, see !OutFiler)
  77.  
  78. Installs font 'WimpMisc' into ResourceFS with the other ROM Fonts to allow
  79. its use without having to install it into a !Font directory on a disc.
  80.  
  81. ********************************************************************************
  82.  
  83. OverView
  84. --------
  85.  
  86. !WimpPatch patches the original WindowManager module so that it uses outline
  87. fonts instead of the system font.
  88.  
  89. OutlineWimp (the file outlnwimp) must be run at the same time as the patched
  90. WindowManager module and allows the font name, size, justification of key
  91. short-cuts, replacement of the up arrow character and the use of the symbol
  92. font 'WimpMisc' to be configured.
  93. Failure to run this module will result in no text appearing.
  94.  
  95. ********************************************************************************
  96.  
  97. Patching the WindowManager
  98. --------------------------
  99.  
  100. Note: This patch only works with WindowManager version 3.16 (the one in
  101.       RISC OS 3.1x)
  102.  
  103. Simply double click on the !WimpPatch application. This should create a new
  104. file called "NewWimp" in the same directory. This is the patched WindowManager
  105. module.
  106.  
  107. When run, the version number of the WindowManager is checked, and if it is not
  108. 3.16 then an error is reported.
  109.  
  110. ********************************************************************************
  111.  
  112. Installing the new WindowManager
  113. --------------------------------
  114.  
  115. The new WindowManager module created by !WimpPatch and outlnwimp must be loaded
  116. before the desktop is started. This is easily done as part of your boot sequence
  117. by, for example, adding the following lines
  118. *RMLoad SCSI::SCSI_4.$.!Boot.NewWimp
  119. *RMLoad SCSI::SCSI_4.$.!Boot.outlnwimp
  120. (Note: replace the path to the !Boot application with that for your own system
  121.        or your preferred location of the files)
  122.  
  123. You may also want to save the fontcache after all the letters have been cached
  124. and load it up in your boot sequence so that the text appears instantly the
  125. first time it is printed. (If you are not already doing this then it will make
  126. the desktop startup box appear instantly as well.)
  127.  
  128. It is also advisable to setup a fontcache large enough to hold the fonts used by
  129. the WindowManager and to set it using !Configure so that the memory is allocated
  130. every time the computer is Reset. As a minimum I would recommend a setting of
  131. 64K but if you intend to use other outline fonts by using programs like !Draw
  132. then a higher setting should be used.
  133.  
  134. ********************************************************************************
  135.  
  136. Configuring the new WindowManager
  137. ---------------------------------
  138.  
  139. The OutLineWimp module provides 7 * commands to allow the WindowManager to be
  140. configured.
  141.  
  142. *WimpFont <FontName>
  143.  
  144. This command set the current font to "FontName"
  145. An error is reported if you try to select a font that does not exist.
  146. Eg. *WimpFont Trinity.Medium
  147. The default is Corpus.Bold
  148.  
  149. *WimpFontSize <Xsize> <Ysize>
  150.  
  151. This command sets the fontsize in the x and y directions in units of 1/16th
  152. points.
  153. Eg. *WimpFont 192 192 
  154.    sets the fontsize to 12pts in x and y directions
  155. The default is 172 x 176 (10.75x11.0 points)
  156.  
  157. *WimpInfo
  158.  
  159. This command displays the current selections of all the configuration items.
  160.  
  161. *WimpJustify <0|1>
  162.  
  163. This command selects whether the key short-cuts are right justified.
  164. Eg. *WimpJustify 1
  165.    turns on justification
  166. The default is off.
  167.  
  168. *WimpUpArrow <0|1>
  169.  
  170. This command selects whether the up arrow character (ASCII 139) is to be
  171. replaced with a different character. Most outline fonts do no contain an
  172. up arrow character so without it being replaced, the key short-cuts are
  173. rather confusing.
  174. When this feature is selected, the use of the font 'WimpMisc' is turned
  175. off.
  176. Eg. *WimpUpArrow 0
  177.    turns off the up arrow replacement
  178. The default is on.
  179.  
  180. *WimpNewUpArrow <ASCII code>
  181.  
  182. This command sets the ASCII code of the character that the up arrow is
  183. replaced with.
  184. Eg. *WimpNewUpArrow 165 
  185.    sets the replacement character to ¥
  186. The default is ASCII 182, the ¶ character.
  187.  
  188. *WimpMiscFont <0|1>
  189.  
  190. This command selects the use of the font 'WimpMisc' for the characters that
  191. are undefined in the normal outline fonts such as the arrow characters.
  192. When this feature is selected, the up arrow replacement is turned off.
  193. Eg. *WimpMiscFont 1
  194.    turns on the use of the font 'WimpMisc'.
  195. The default is off.
  196.  
  197. The default values emulate the system font by selecting corpus.bold which is
  198. a monospaced font at the same size as the system font characters. Thus the
  199. menus look OK with justification off and programs that rely on the font used
  200. being not proportionally spaced also look OK.
  201.  
  202. The settings that I use are: 
  203.  
  204. *WimpFont Trinity.Medium
  205. *WimpFontSize 192 192
  206. *WimpJustify 1
  207. *WimpMiscFont 1
  208.  
  209. (Note the fontsize here is 12pts)
  210.  
  211. The * commands that select the current settings are saved in the "Desktop Boot
  212. File" when it is saved from the task manager.
  213.  
  214. ********************************************************************************
  215.  
  216. Justification
  217. -------------
  218.  
  219. When the justification option is turned on the windowmanager searches through
  220. all the text it prints in single line icons for those containing key short-cut
  221. text on the right hand side. As all the text printed is searched for key short-
  222. cuts, the algorithm is very selective, for example if the key short-cut sequence
  223. is detected but there is one or more space characters between it and the right
  224. hand side then the justification is not applied.
  225. In addition to detecting key short-cuts for right justification, the sequence of
  226. hard space and then left bracket with any number of spaces between them and the
  227. right hand side is searched for. This is included to allow the mode menu on the
  228. palette utility to have the mode description text right justified if the
  229. messages file is altered to include hard spaces between the mode numbers and the
  230. descriptions.
  231. Eg.
  232.  
  233.   ----------------------
  234.   |       Mode         |
  235.   ----------------------
  236.   | 20    (16 colours) |
  237.   | 21   (256 colours) |
  238.   |€31  (SVGA 16 cols) |
  239.   |                    |
  240.   ----------------------
  241.  
  242. Note: a hard space is obtained by pressing the alt and space keys at the same
  243. time.
  244.  
  245. ********************************************************************************
  246.  
  247. OS_Write replacement SWIs
  248. -------------------------
  249.  
  250. The module OutlineWimp provides 6 SWIs to replace the main text printing calls
  251. with ones that use the same outline font as the rest of the desktop.
  252. They have the same entry and exit conditions and so can directly replace the
  253. OS_Write calls.
  254.  
  255.    OutlineWimp_WriteC  &496C3      replaces     OS_WriteC
  256.    OutlineWimp_Write0  &496C4      replaces     OS_Write0
  257.    OutlineWimp_WriteN  &496C5      replaces     OS_WriteN
  258.  
  259. With these three routines the graphics cursor is advanced to the position it
  260. would have been if the OS_Write calls were used after the text is printed. (ie.
  261. the width of the system font is used to move the graphics cursor)
  262.  
  263.  
  264.    OutlineWimp_PWriteC  &496C6     replaces     OS_WriteC
  265.    OutlineWimp_PWrite0  &496C7     replaces     OS_Write0
  266.    OutlineWimp_PWriteN  &496C8     replaces     OS_WriteN
  267.  
  268. With these three routines the graphics cursor is advanced to the end of the
  269. actual text on the screen.
  270.  
  271. In both cases, only the X position of the graphics cursor is altered, the Y
  272. position remains the same.
  273.  
  274. NOTE: The text always has a foreground colour of 7 and a background colour of 1.
  275.       (In this version anyway)
  276.  
  277. ********************************************************************************
  278.  
  279. Text and sprite indirected icons with right justified text
  280. ----------------------------------------------------------
  281.  
  282. Normally when calculating the length of the text in an icon the WindowManager
  283. uses the actual length of the outline font characters.
  284. In certain circumstances, however this does not achieve the correct results. An
  285. example of this is the "Full info" display by the filer. The filename icons are
  286. of the type described by the title of this section. As the text is right
  287. justified the Filer pads the filename out with spaces at the end so that all
  288. the filenames are ten characters long. With the system font this causes the
  289. start of the text to line up with each other, however, as the outline font is
  290. proportionally spaced the starts of the text would no not line up with each 
  291. other. To remedy this problem, the patched WindowManager detects that type of
  292. icon when calculating the length of the text and uses the length the system 
  293. font would have if it is longer then the actual length of the outline font.
  294. Thus the starts of the text now line up.
  295.  
  296. Another program that uses spaces of positioning is !StrongHlp v1.x by Guttorm 
  297. Vik. This formats the text lines by using centred text with spaces added on the
  298. end to make the start of the lines line up with each other when the system font.
  299. At the moment I cannot see any way to make the WindowManager format the text
  300. correctly when a proportionally spaced font is used.
  301.  
  302. ********************************************************************************
  303.  
  304. Technical information
  305. ---------------------
  306.  
  307. The module OutlineWimp provides a set of SWI calls for use of the patched 
  308. windowmanager and other programs that want to use outline fonts in the desktop.
  309.  
  310. SWI Chunk number: &496C0
  311. SWI group prefix: OutlineWimp_     (Both allocated by Acorn)
  312.  
  313. ===========
  314.  
  315. SWI &496C0 : OutlineWimp_Fonthandle
  316.  
  317. On Entry:
  318.      ---
  319.  
  320. On Exit:
  321.      R0 = fonthandle of current desktop font
  322.  
  323. Use:
  324.      This call is used by the WindowManager to get the fonthandle of the normal
  325.      desktop font.
  326.  
  327. ===========
  328.  
  329. SWI &496C1 : OutlineWimp_KeyShortCut
  330.  
  331. On Entry:
  332.      ---
  333.  
  334. On Exit:
  335.      R8 = flags
  336.              bit 0 set => right justification of key short-cuts on
  337.              bit 1 set => replacement of up arrow character on
  338.              bit 2 set => use of font 'WimpMisc' on
  339.              bits 3 - 10 => ASCII value of character used to replace up arrow by
  340.              all other bits reserved
  341.  
  342. Use:
  343.      This call is used by the WindowManager to obtain the configuration of the
  344.      various features provided.
  345.  
  346. ===========
  347.  
  348. SWI &496C2 : OutlineWimp_Configuration
  349.  
  350. On Entry:
  351.      ---
  352.  
  353. On Exit:
  354.      R0 = pointer to name of current desktop font
  355.      R1 = fontsize in X direction in units of 1/16th points.
  356.      R2 = fontsize in Y direction in units of 1/16th points.
  357.      R3 = flags
  358.              bit 0 set => right justification of key short-cuts on
  359.              bit 1 set => replacement of up arrow character on
  360.              bit 2 set => use of font 'WimpMisc' on
  361.              bits 3 - 10 => ASCII value of character used to replace up arrow by
  362.              all other bits reserved
  363.  
  364. Use:
  365.      This call provides information on the current state of the outline font
  366.      WindowManager. It is used by the program !DeskCtrl to find the current
  367.      configuration for the "Desktop Font Setup" window.
  368.  
  369. ===========
  370.  
  371. SWI &496C3 : OutlineWimp_WriteC
  372.  
  373. On Entry:
  374.      R0 = ASCII character to write
  375.  
  376. On Exit:
  377.      R0 preserved
  378.  
  379. Use:
  380.      This call writes the character whose ASCII value is in R0 at the current
  381.      graphics cursor position using the current desktop font and then moves the
  382.      cursor on the width of the letter if the system font was used. This SWI can
  383.      be used as a direct replacement to OS_WriteC.
  384.      The fontcolours are fixed at wimp colour 7 for the foreground and wimp
  385.      colour 1 for the background.
  386.      
  387. ===========
  388.  
  389. SWI &496C4 : OutlineWimp_Write0
  390.  
  391. On Entry:
  392.      R0 = pointer to null terminated string
  393.  
  394. On Exit:
  395.      R0 preserved
  396.  
  397. Use:
  398.      This call writes the string whose pointer is in R0 at the current graphics
  399.      cursor position using the current desktop font and then moves the cursor on
  400.      the width of the string if the system font was used. This SWI can be used
  401.      as a direct replacement to OS_Write0.
  402.      The fontcolours are fixed at wimp colour 7 for the foreground and wimp
  403.      colour 1 for the background.
  404.           
  405. ===========
  406.  
  407. SWI &496C5 : OutlineWimp_WriteN
  408.  
  409. On Entry:
  410.      R0 = pointer to string
  411.      R1 = number of characters to write
  412.  
  413. On Exit:
  414.      R0 - R1 preserved
  415.  
  416. Use:
  417.      This call writes the number of specified characters from the string pointed
  418.      to by R0 at the current graphics cursor position using the current desktop
  419.      font and then moves the cursor on the width of the string written if the
  420.      system font was used. This SWI can be used as a direct replacement to
  421.      OS_WriteN.
  422.      The fontcolours are fixed at wimp colour 7 for the foreground and wimp
  423.      colour 1 for the background.
  424.  
  425. ===========
  426.  
  427. SWI &496C6 : OutlineWimp_PWriteC
  428.  
  429. On Entry:
  430.      R0 = ASCII character to write
  431.  
  432. On Exit:
  433.      R0 preserved
  434.  
  435. Use:
  436.      This call writes the character whose ASCII value is in R0 at the current
  437.      graphics cursor position using the current desktop font and then moves the
  438.      cursor on the actual width of the letter. This SWI can be used as a direct
  439.      replacement to OS_WriteC.
  440.      The fontcolours are fixed at wimp colour 7 for the foreground and wimp
  441.      colour 1 for the background.
  442.  
  443. ===========
  444.  
  445. SWI &496C7 : OutlineWimp_PWrite0
  446.  
  447. On Entry:
  448.      R0 = pointer to null terminated string
  449.  
  450. On Exit:
  451.      R0 preserved
  452.  
  453. Use:
  454.      This call writes the string whose pointer is in R0 at the current graphics
  455.      cursor position using the current desktop font and then moves the cursor
  456.      on the actual width of the string. This SWI can be used as a direct
  457.      replacement to OS_Write0.
  458.      The fontcolours are fixed at wimp colour 7 for the foreground and wimp
  459.      colour 1 for the background.
  460.  
  461. ===========
  462.  
  463. SWI &496C8 : OutlineWimp_PWriteN
  464.  
  465. On Entry:
  466.      R0 = pointer to string
  467.      R1 = number of characters to write
  468.  
  469. On Exit:
  470.      R0 - R1 preserved
  471.  
  472. Use:
  473.      This call writes the number of specified characters from the string pointed
  474.      to by R0 at the current graphics cursor position using the current desktop
  475.      font and then moves the cursor on the actual width of the string written.
  476.      SWI can be used as a direct replacement to OS_WriteN.
  477.      The fontcolours are fixed at wimp colour 7 for the foreground and wimp
  478.      colour 1 for the background.
  479.  
  480. ===========
  481.  
  482. SWI &496C9 : OutlineWimp_MiscFontHandle
  483.  
  484. On Entry:
  485.      ---
  486.  
  487. On Exit:
  488.      R0 = fonthandle of font 'WimpMisc' or 0 if font not used
  489.  
  490. Use:
  491.      This call is used by the WindowManager to get the fonthandle of the font
  492.      'WimpMisc' that is used to plot the arrow characters etc. 
  493.  
  494. ********************************************************************************
  495.  
  496. Contacting the author
  497. --------------------
  498.  
  499. I, Andrew Sellors, can be contacted either at
  500.    57 Boundaries Road
  501.    Feltham
  502.    Middlesex
  503.    TW13 5DR
  504.    England
  505.  
  506. Or via Internet email at
  507.    asellors@orac2.demon.co.uk
  508.    
  509. Any feedback from users (bugs reports, requests for new features etc.) is
  510. gladly received.
  511.