
About DeskFonts
---------------

Deskfonts is a utility which replaces the default system font with an outline
font of your choice in the desktop and wherever else VDU5 type text is used.

Technical details about how Deskfonts works and some of the un-avoidable
problems involved are given at the end of this document. What follows is a
description of the DeskFonts multi-tasking frontend which is all that most
people will see.

Load !DeskFonts in the usual way, by double clicking on it's icon. The
program will install on the icon bar and clicking on this icon opens the
main window. From top down, the functions which are then available are as
follows:

Click on the option switch at the extreme top-left to toggle between the
normal system font and the anti-aliased font. When this switch is on, the
anti-aliased font will be used. Choose a anti-aliased font from the menu of
available fonts. This menu may be opened by clicking on the icon called
'Fonts...' or by clicking MENU anywhere within the window. When choosing a
font, it is important to note that proportional fonts (which make up the vast
majority of outline fonts available) can cause problems. See below for
details.

The Size X and Size Y options allow you to change the size of the text in
(surprise surprise !) the horizontal and vertical directions. Some restraint
is necessary when altering the sizes. To change a size, either use the left
and right arrow icons (1/4 point change or 1 point with SHIFT held down),
or, enter a value into the writable size icon and press RETURN.

In Corpus, the maximum sizes that can reasonably be used are - XSize 10.75,
Ysize 16.5

The Offset X size should normally be zero. Small values (eg 1 or 2) can be
useful sometimes, but larger values almost always cause a mess. The value
is os-units extra before each string.

The Offset Y size should normally be about 24. You may have to alter this if
using a unusual text size, either increasing or decreasing it for larger and
smaller y text sizes.

The colour checking radio options. These control the amount of
'intelligence' the program displays when printing text.

'None' results in black text anti-aliasing to white everywhere. Shaded menu
items have never been so hard to spot!

'Partial' changes the text foreground to the colour the normal system font
would be printed in at the same place but leaves the anti-aliasing at white.
Can look strange in title bars etc.

'Complete' tries to guess the colour the text will be anti-aliased to. The
method used is slightly suspect (see the technical section for details).

The operating system radio options are necessary because RISC-OS 2 uses some
redefinable system characters for the tool icons around window borders
(close icon etc.). Since the corrosponding characters are not present in an
outline font, running Deskfonts on a risc-os 2 machine was slightly strange,
as these icons immediately disappeared! See the technical notes for details of
other problems that these missing characters cause and a possible solution.

The Settings box allows you to save, re-load and reset all of the above
settings. Saved settings are automatically re-loaded with the program so you
can 'tune' deskfonts to suit your preference and then save these settings.

The Reset box (made large deliberately) is used in a 'panic' situation. Eg.
you've chosen a font width of 0.001 points and you can't read anything! It
resets all of the values to defaults and also resets the display to the
system font.

The Icon bar menu
-----------------

Fairly standard except that 'Quit' has a sub-menu. Choosing 'Quit>Complete'
or just 'Quit' removes DeskFonts entirely and resets to the system font.
Choosing 'Quit>Partial' leaves the DeskFonts module active, displaying the
last settings you chose.


Technical notes
---------------

Problems
--------

Proportionally spaced fonts cause problems when used in place of the system
font. In particular -

Text which is normally centred (eg in an icon) almost never is. The caret
does not appear in the correct place within writable icons. Text which
contains a great number of wide characters (eg uppercase W in most fonts)
can overlap the edges of the icon it's supposed to be within.

The colour of the text can sometimes be a little strange in 256-colour
modes. This is because of several problems with Risc-Os (specifically - SWI
OS_ReadPalette doesn't seem to work correctly - or I don't understand it!).

There is a known problem with the window manager call which produces the
standard 'Wimp-Report' error box. Sometimes, for no apparent reason the text
is printed in vdu 4 mode at the top of the screen rather than in the error
window. To follow Acorn guidelines correctly, DeskFonts should remove itself
(ie restore the system font) before an error window opens and relink after
the window closes. However this would make all of the text in such a window
appear in the system font. As many programmers (myself included) use
Wimp_ReportError for message dialogs and queries, this would make DeskFonts
substantially useless. I will continue to work on this problem and may
produce an update in the future.

UPDATE: Option added to allow Error trapping. When on, the default system
font is used within Wimp_Error dialogs, outline font restored afterwards.

Text display is (naturally) quite a lot slower than with the normal system
font.

Those programs which use the up arrow symbol in menus to denote the use
of the SHIFT key will either -

Not display the arrow symbol (risc-os3 setting)
or, Display the arrow over the top of the first character in the menu item -
making a nasty mess! (risc-os2 setting)
One solution would be to define the necessary characters in a font (with
!FontEd) to be anti-aliased versions of the system font equivilant. This
would allow (on Risc-os 3 setting) the correct characters to be displayed.
The characters that would need to be defined are -

&80 tick
&81 (from large to small icon)
&82 (from small to large icon)
&83 re-size window icon
&84 close window icon (x)
&85 move to back icon
&88 right arrow
&89 left arrow
&8A down arrow
&8B up arrow (this is the only one needed for RISC-OS 3 users)

I have roughly defined a variant on Corpus.Bold to include these characters.
The font is called CorpusD and is included. Note that these definitions are
VERY crude. Someone else is sure to do something better. If they do then how
about sending me a copy? Also, if you are good at that sort of thing, how
about defining a new monospaced outline font for the desktop that looks
better than Corpus? I've got the MDA fonts that come with the PC emulator
and they look even worse than Corpus.

How DeskFonts works
-------------------

The low level Relocatable module intercepts all calls to the operating
systems' Write character routine and re-directs the character to be printed
to the fontmanager. This is complicated by the fact that many calls to
OS_WriteC are NOT printable characters but moves, draws, colour changes etc.
The inital code can often seem to be followed by a normal ASCII character
but it MUST NOT be caught. The program gets round this by counting a
specific number of characters through after the reciept of such a VDU code.

It also has to check for two special cases even when it thinks that it's
recieved a normal character.

The first is when the computer is in VDU4 mode (ie when the user's pressed
f12). Such characters must be passed along to the standard OS_WriteC

The second is to check that VDU output has not been re-directed via a
mechinism known as VDUX_V which is used by the WindowManager to provide
anti-aliased text in an icon in the desktop.

Characters which are to be printed are stored in a buffer until a control
character is found. At this point the current graphics cursor position is
found and the string printed.

The program has to determine the colour of the text according to the Colour
checking rules defined and set the anti-aliased palette.

The program also has to check for and respond to Service calls to do with
mode changes, so that the font can be recomputed correctly.
                               

Star commands
-------------

All of the features of DeskFonts are provided by the DeskFonts relocatable
module. This module interfaces to the desktop via a number of star commands.
Short notes on these are given below. Similar help can be provided by
pressing f12 after DeskFonts has loaded and typing *Help DeskFonts


==> Help on keyword DeskFonts
Module is: Desk fonts      1.05 (25 Feb 1992)  Rob Davison 1992

Commands provided:
DFontON DFontOFF        DFont   DFontX  DFontY  DfontOffset     DfontAlias     
DFontAddx DfontOS DfontReset


==> Help on keyword DFontON
*DFontON intercepts future calls to OS_WriteC and prints subsequent text in
an anti-aliased font. Syntax: *DfontON

==> Help on keyword DFontOFF
*DFontOFF restores the default system font.
Syntax: *DfontOFF

==> Help on keyword DFont
*DFont sets the font to be used in the desktop after a *DFontON.
Syntax: *DFont <FontName>

==> Help on keyword DFontX
*DFontX sets the width of anti-aliased text in the desktop.
Syntax: *DFontX <pointsize*16>

==> Help on keyword DFontY
*DFontY sets the height of anti-aliased text in the desktop.
Syntax: *DFontY <pointsize*16>

==> Help on keyword DfontOffset
*DFontOffset sets the vertical offset of the anti-aliased text from the
normal text position. Syntax: *DFontOffset <os-units>

==> Help on keyword DfontAlias
*DfontAlias controls DeskFonts colour checking.
Syntax: *DFontAlias 0|1|2

==> Help on keyword DFontAddx
*DfontAddx sets the horizontal pixel offset between each character.
Syntax: *DfontAddx <os-units>

==> Help on keyword DfontOS
*DFontOS allows DeskFonts to cater for different versions of RISC-OS.
Syntax: *DFontOS 2|3

==> Help on keyword DfontReset
*DFontReset resets all of DeskFonts internal values to sensible defaults.
Syntax: *DFontReset
