Specification for a Proportional System Font under the Window Manager
=====================================================================

History
-------
0.01 WS 29-Oct-92 - started - just wimp font work provided.
0.02 WS 30-Oct-92 - feedback from JCoxhead, IJohnson, MChallis
0.03 WS 03-Nov-92 - more issues added.

Issues
------

MChallis says, a long way from being a spec - very true! Long journey
starts with first step...
A fn spec for changes to an existing thing should be expressed
as changes to the existing functional spec.
The actual functional spec should be identified as such, and separated
from planning/resourcing info, implementation hints, etc.

Do we allow the term 'the system font' in the context of the Window Manager
to be used to describe either the built-in system font, or the wimp font,
whichever currently applies? This keeps user-level terminology consistent
with the present. At the moment I'm not sure I'm totally consistant on
this.

Underlining taken out this time round - not really needed.
DDV:
How about the underline character aswell, we may should reserve two
characters:
 & <char>       causes the next character to be underlined ( Initialise version > 316 )
 > <char>       causes following text to be right aligned  ( Initialise version > 316 )
 &&             inserts &
 >>             inserts >
(WS): If we did escapes I'd far rather reserve \, and use it for other things
too. But, I think we should avoid anything like this this time round.

Should we separate wimp font width from height? It would be a little bit
nicer to weird users, particularly if some odd-ball wants to use Corpus
in some form.
(DDV):This is a good point, the user should be given some control over the aspect
ratio, Wimp$XYRatio.
This should all be hidden from the user by an application that allows them
to manipulate the size, width, font and other characteristics.
(WS): should this application be added to this package? Or perhaps this should
be added to !3DIcons?

(JCoxhead): Font size: should not be under user control. It is totally
impractical to require every application to resize its templates to take
account of different sizes of WIMP font. The WIMP font should always be such
that the character bbox of the font is 32 by 16 O S units: i e, the size of
system font at the moment. Applications that do want to be able to resize
their templates (and there won't be many) can do this themselves, in the
usual way. This guarantees that all existing dialogue boxes will work with
any font. It results in a font slightly narrower than the one in the
prototype. There would be no WIMP$FontSize variable in this scenario. No
menu- calculation software is required in the WIMP.
(DDV):The user should have full control over the font size, users of higher
resolution displays should be able to change the size.  Applications should
not be expected to resize dialogues, dialogues are designed assuming 12
point if the user sets the font to be bigger then it will be clipped unless
the application in control is feeling daring.
(WS):I would have thought that we provide this setting in order to allow
the user to make minor changes, such as to a slightly changed custom variant
of homerton, but that we do not envisage or support major changes to this font.
Isn't this a reasonable/sensible middle path to take? I think it is what other
window systems do. Menu width calculation is quite important in order to
bridge the gap between system font and homerton.

JCoxhead: The rule for shortcut detection in menus should be 'if the entry matches
      ^. <key>
(i e, one or more of anything, a space and then a key name), then right
justify the key name.
WS: don't really understand what this is saying!

Another solution considered to the shift-character problem was: If the first
or second character of the keyboard shortcut is shift-arrow (&8B), then use
the character code &DD from the Sydney font (at the same point size)
instead, when painting. (This ugly special case is because this shift arrow
is not present in most fonts, and should not be added to them because it is
not in the PostScript fonts either.) HOWEVER, in mode 12 this leads to the
shift character not having a hand-tuned representation, and so appearing
anti-aliased next to non-anti-aliased other characters! So, we go the other
way.
  Perhaps we could combine both rules? If there is a character there then
use it, otherwise use Sydney? Yuk! This would mean that we don't have to
update the Homerton.Medium font, yet we can put it in the hand-tuned font.
No, the two share a metrics file!
  So, I currently see no better solution to what is in the text.

OR (JCoxhead):For up-arrow: how about a new font manager control code, 0x8B,
which causes an up-arrow to be painted? This would work in all cases for
everything everywhere, would still work in system font, and generally save a
lot of fuss. It could also be printed.

OR (DDV):The Font Manager should not know anything about what the Window Manager is
doing, plus there are fonts which may make use of characters in this
character range.
I suggest we have two system variables:
 Wimp$Font        used for Window Manager text rendering
 Wimp$SymbolFont  used for rendering characters in the range of &80 - &8B.
When the Window Manager is taking a soft copy of the text it simply watches
for control sequences, and pads them with a font change before and after.
(WS): so do we invent a new wimp symbol font, with an arrow in the right place
in those character codes? In Symbol it has a different character code...

Is auto-tabbing in wimp font icons really acceptable? It feels a dangerous
blot on the API. Perhaps it should require explicit enabling, rather than
disabling?
JCoxhead: Multiple-spaces => TAB should be discarded. It's too silly.
DDV: Hmmmm..

Define the validation string entry that turns off tabbing in wimp font
icons.

DDV: The described form of delivery to the user is not good enough. Got to
find a better way to help users install it.
(WS): perhaps as part of creating a desktop boot file, !3DIcons can
contribute things which load a new Wimp? But that's too late! I don't see
any way of doing it without telling him to hack his !Boot file...
Suggestions welcome.

Do we need a validation string item that forces the use of the system font?
There is currently no way for an application to do this.

Background
----------

This is a detailed specification for a package of changes current required
to the Window Manager, and some related modules, by the Libra project. Refer
to Libra market requirement, feasibility statement for further background.

Within the Victoria project I am trying (hard!) to move further towards
writing and reviewing specifications before they are implemented, to
specifications being more complete, and to sticking rigidly to those
specifications. This is a further experiment at achieving this, under
somewhat different project circumstances and for much smaller tasks. Refer
to Mike Challis' current document about what a functional specification
should contain.

All work should be done to full product quality. The enddate does not
correspond to a product release, but the result is likely to be integrated
into a product release in the future. Because of this it is vital that bugs
are not introduced in the course of this development work. Specifically it
is likely that we will release it informally to some high-end users and
developers during 1993, and that it will subsequently become part of the
Victoria RISC OS release.

Any changes to this document should be agreed in advance (extensions AND
restrictions). Jonathan Coxhead, Ian Johnson, David De Vorchik, William
Stoye are the 'review committee'.

Any updates to the SWI interface implied by these changes should be added
to this document and agreed before being implemented.

This specification is written in terms of differences from the Window
Manager in RISC OS 3.10. Use the RISC OS User Guide, the PRM, and the Window
Manager itself, as the specification for this. If these differ in some
relevant area then this document should make an explicit choice between
them.

Use of a scalable font as the system font
=========================================

The objective is to entirely replace the use of the system font with the
use of a proportional font within the desktop, in order to make the result
more visually appealing. This may lead to some incompatibilities with
existing applications, but this will be minimised wherever reasonably
possible.

We expect that this will be used most by high-end users, and by those who
possess high-resolution (square pixel) monitors (referred to as VGA
resolution from now on). However, we do not want to exclose those with low
(TV) resolution monitors, and wish to provide them with a reasonable path
forward.

The basic approach is that we will continue to have a single font which is
used for most purposes within the window system. (This contrasts with Windows,
for instance, where numerous different fonts are used for different purposes).
For the purposes of laying out dialogue boxes etc. applications developers
should assume that this font is Homerton.Medium at 12-point.

We expect VGA-resolution monitors to be used with the normal anti-aliased font
as rendered by the font manager. We expect TV-resolution monitors to be used
with a hand-tuned bitmap of this font at 12-point.

Specification
=============

The following changes are required to the Window Manager in RISC OS 3.10.

If the variables <wimp$font> and <wimp$fontsize> are set then they indicate
the font and point-size which is used as the surrogate system font ('the
wimp font'). This font is used by the Window Manager to plot icon text that
would otherwise be plotted in the system font. Window titles and menu text
are also treated in this way. The existence and values of these variables is
checked at startup, and at a mode change, and when the broadcast
Message_WimpFontChanged (&400XX) is received.

If painting generates an error for any reason, then do not report an error
but fall back to the system font. (This is particularly important when
painting the error box itself).

An application can get hold of the wimp font handle, in order to do width
calculations, by doing a Font_FindFont of <wimp$font>, <wimp$fontsize>). It
can detect whether the wimp font or the built-in system font is being used
by testing for the existence of <wimp$font>.

When using the wimp font or the built-in system font, perform
auto-computation of menu width. Simply ignore the width that the application
provides in Wimp_OpenMenu. Menus should be just wide enough to contain the
title, and all of the entries, in the menu.

In menus keyboard shortcuts must be displayed right-aligned. These
are detected using the following rule:

  If a menu entry contains at least one space, and the character after the last
  space is one of "^", shift-arrow (&8B), "F", then right align everything
  after the last space.

  If a menu entry contains at least one space, and the caracters after the
  last space exactly match one of the words specified in a list in the Wimp's
  Messages file, then right-align everything after the last space. In the
  UK this list will consist of "PRINT RETURN ESC TAB".

In the plotting of a non-writable left-aligned icon in the wimp font, the
appearance of multiple space characters should be interpreted as an attempt
to move to a tabstop. In such a case the first non-space character after the
multiple spaces should be plotted at
  <number of characters so far, including the spaces> * 16 OS-Units
from the start of the icon. This effect can be disabled using a suitable
entry in the validation string.

The following changes are required to the Homerton font:

Add a shift-arrow character (&8B) to Homerton.Medium, in order to match the
character in the built-in system font. Simply copy the character &DD from
the Sydney font. Add an equivalent to the hand-tuned copy of Sydney at
12-point. This character is only for this purpose and should not be regarded
as part of the standard character set. It does not appear in PostScript
fonts and users should not be encouraged to put it in documents.

A tuned bitmap _240x120 should be provided which makes Homerton.Medium 12
point on a TV-resolution display show using no anti-aliasing.

Changes are required to the Filer to make it work with scalable fonts.
Specifically the small and full info display modes need adjustment. No
changes are required to any program interfaces, nor to the behaviour of the
Filer to the user.

Changes are required to the PRM to reflect these facilities, next time
the PRM is updated. Such changes will be limited to the Window Manager
chapter. Changes required are:
  the section on system font handling
  the description of icons under Wimp_CreateIcon
  the description of menu width and keyboard shortcusts under Wimp_CreateMenu
  the description of Message_WimpFontChanged under Wimp_SendMessage
Any screenshot that shows a window will also have to be changed.

Changes are required to the User Guide, mainly in the screenshots but some
small descriptive changes may also be required.

The Wimp command window still uses the built-in system font.

Implementation notes
====================

A prototype Wimp already exists which provides the basic wimp font,
with some bugs - get this from David De Vorchik. Known bugs are:

    after using a font for some time, if I unset Wimp$Font,
    various things don't seem to work properly - eg. typing into a
    writable icon leads to the caret disappearing?
      not sure if this is repeatable, but it definitely happened.
    thereafter the system is unreliable, and can often crash, saying
      that the window with the caret cannot be found.

    random background colour at times - sometimes white, green, black...
      if an icon says 'don't fill background' you should use the
      window background colour.

    some menu entries just missing - white foreground colour?

    'Illegal character in font string' sometimes - e.g. when opening
    windows. Can vary for identical actions, so reading garbage values
    somewhere.
    (due to badly terminated strings)

    In some text+sprite icons, the sprite is missing - blanking the
    background on font_paint?
    Perhaps related, *sometimes* on a text+sprite the text background
    partially obscures the icon itself - most noticable on SCSIFiler icons,
      but not always there.

    default action button built using "R6,14" in validation string:
    goes black when pressed, instead of orange.

    Caret sometimes in the wrong position in writable icons, particularly
      when they are initially created.

    The l40 icon type does not work with this font.

The auto-calculation of menu width has to be fast - it is called
whenever a menu is opened or reopened.

It may be that the easiest way to right-align menu entries is to provide a
right-align control code in text icons. I cannot think of any other reason
for providing this. At the moment the we do not specify whether or not this
is the implementation mechanism.

The tuned bitmap file Homerton.Medium._240x120 already exists, obtain it
from William.

Paint and Calc both make minor use of direct painting using the built-in
system font. Neither of these uses is important or noticable enough to need
fixing for release of this code.

Beware of tricky interactions between auto-tabbing, and right alignment of
menu keyboard shortcuts. In a menu entry auto-tabbing is really not useful.

Delivery notes
==============

These new modules will be cut in to the next product release of RISC OS,
probably as part of Victoria. However, they may well get circulated before
then, particularly to high-end users who want the result and are prepared to
pay the memory cost of soft-loading a Wimp.

In such a case the result is a package consisting of
  Modules.Wimp, a new WindowManager module
  Modules.Filer, a new Filer module
  Modules.WimpFont, a WimpFont module
  ReadMe, an instruction file
The latter will place adjusted files in ResourceFS for the updates to the
Homerton.Medium font. (In the circumstances it seems slightly preferable
to adding a !Fonts application).

Users will have to RMLoad these in their machine boot file, since the
WindowManager cannot be replaced when the desktop has started.

