Specification for updates to Window Manager and related modules
===============================================================

History
-------
0.01 WS 29-Oct-92 - started - just wimp font work provided.
0.02 WS 30-Oct-92 - feedback from JCoxhead, IJohnson, MChallis

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. Or, leave this decision to documentation people.

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.

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.

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

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?

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 should be used as the surrogate system font
('the wimp font'). This font should be used by the Window Manager to plot
icon text that would otherwise be plotted in the system font. Window titles
and menu text should also be treated in this way. The existence and values
of these variables should be checked at startup, and at a mode change.

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.

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.

    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.
