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.
0.04 WS 05-Nov-92 - review by WS,JC,DDV,IJ:
                    wimp font v system font terminology sorted out
                      ('system font' still used to denote the built-in thing,
                       eg. on menu entries where there is a font choice)
                    control over aspect ratio added
                    various issues resolved
                    Wimp$SymbolFont added
                    auto-tabbing taken out
                    spec of distribution front end taken out

Issues
------

MChallis says, a long way from being a spec - very true! Long journey
starts with first step...

Baselines of font text may still be a problem?
WS will re-tweak the mode 12 font to have only one pixel of descender:
then review again.
WS 6th Nov - editing templates example - you have a label and a display
field lined up horizontally, but they are different vertical sizes. Their
baselines are lined up. Now change to the outline font and presto: their
baselines are no longer lined up! Aaagh! Or, they can be OK at lo res but
not at hi res! I think the baseline will have to stay PRECISELY where it was
for the wimp font, not at all nice.

Spec of call to Wimp_ReadSysInfo not precise.

In RO3 why did we do keyboard shortcuts capitalised when it isn't like that on
the keyboard? The current Style Guide mentions "Esc Print Insert Delete Copy Home
PageUp PageDown" (page 51-52) - presumably Tab Enter Return also allowed?
Surely a menu entry "Print Print" looks rather silly - if the shortcut is the
same as the menu entry proper, is it acceptable to omit the shortcut? Asking
Style Guide folks.

Ws and Ys for Welsh are in the range 80-8b, surely they should be taken from
the normal font rather than the symbol font? This is what I have assumed in
the text. Reviewers please confirm!

JC: The rule for menu shortcuts fails to internationalise: we believe that
German machines do not use ^, but rather an abbreviation, to mean 'control.'
It also fails to catch ^F1, shift-PRINT etc etc.
(WS): It does catch them! Don't understand.

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.

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 necessary
files will be shipped as part of !3DIcons. The complete specification for
this can be found elsewhere.

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 exclude 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.

The following system variables are used:
  wimp$font           name of the font to use
  wimp$fontsize       heigth and width of the font, in 16ths of a point
  wimp$fontwidth      width of the font, if different from height, in 16ths
                      of a point
  wimp$symbolfont     name of the font for symbol characters
If the variable <wimp$font> exists then these indicate the font and size
which is used as 'the wimp font'. This font is used by the Window Manager to
plot icon, menu and window title text that has until now been plotted in the
system font. The existence and values of these variables is checked at
desktop startup, and at a mode change, and when the broadcast
Message_WimpFontChanged (&400XX) is sent by any application.

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).

The font named in wimp$symbolfont is used, at the same specified point size,
for the rendition of character codes &80, &84, and &88 to &8B. This
mechanism is required because there are some symbols and characters in that
range which are known to be used, and which are not provided in standard
Acorn fonts.

An application can get hold of the wimp font handle or the wimp symbol font
handle using the following call:

SWI Wimp_ReadSysInfo
on entry:
  r0 = XXX (read wimp font handle)
on exit:
  r0 = 0 (and other registers undefined) if there is currently no wimp font handle
  r0 = wimp font handle otherwise
  r1 = wimp symbol font handle

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 non-writable menu entry contains at least one space, and the character
  after the last space is one of the characters in a string found in the
  Wimp's Messages file, then then right-align everything after the last space.
  In the UK this string will consist of "^\x8b" (hex 8B is the shift key in
  the symbol font).

  If a non-writable 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
    "ESC PRINT INSERT DELETE COPY HOME PAGEUP PAGEDOWN TAB ENTER RETURN
     Esc Print Insert Delete Copy Home PageUp PageDown Tab Enter Return
     F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12".

A new font Wimp.Symbol should be created.

This only has only the following characters defined:
  80 - a tick                (take from Selwyn &33)
  84 - a cross               (take from Selwyn &63)
  88 - a left arrow          (take from Sydney &DC)
  89 - a right arrow         (take from Sydney &DE)
  8a - a down arrow          (take from Sydney &DF)
  8b - an up arrow           (take from Sydney &DD)
These should exist as outlines, and as a tuned bitmap suitable for 12 point
in mode 12.

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 and to NetFiler to make them 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
  the new call to Wimp_ReadSysInfo described
Any screenshot that shows a window will also have to be changed. This need
only occur next time the User Guide is updated for some other reason.

Changes are required to the User Guide, mainly in the screenshots but some
small descriptive changes may also be required. This need only occur next time
the User Guide is updated for some other reason.

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

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

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.

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.
