Ursula Interactive Help

Functional Specification

 COMPANY CONFIDENTIAL

Document Ref:	????,???/FS
Project:	Ursula
Revision:	C *** PROVISIONAL AND SUBJECT TO CHANGE WITHOUT NOTICE***
Date:	16th February 1998
Author(s):	Richard Leggett
Change:	Added Message_HelpEnable

Contents:

1.0	Overview.
2.0	Outstanding Issues.
3.0	Technical Background.
4.0	User Interface.
5.0	Programming Interface.
6.0	Data Interchange.
7.0	Data Formats.
8.0	External Dependencies.
9.0	Acceptance Test.
10.0	Non Compliances.
11.0	Development Test Strategy.
12.0	Product Organisation.
13.0	Future Enhancements.
14.0	Glossary.
15.0	References.
16.0	History.

1.0 Overview

This document covers the specification of a new interactive help application to be supplied with the Ursula release of RISC OS and superseding the current application !Help. It is thought that the present !Help is rather dated when compared with interactive help applications provided on other platforms, and that a re-write is a necessity. In order to provide backward compatibility, the actual format of help messages (provided by applications) will remain unchanged, but the changes will centre around the way that these messages are delivered to the user.

2.0 Outstanding Issues

None.

3.0 Technical Background

None.

4.0 User Interface

4.1 Messages

The basic idea of the Help application is to provide information about any objects (windows, icons etc.) that are underneath the pointer on the screen. If the pointer stays still for a set time, Help will provide a window offset from the pointer displaying information about the pointer's current position. A typical help box is shown below, displaying information from Filer:

The box displaying the help message will be displayed with its top left at the bottom right of the pointer icon (as in the previous image). If the pointer is too far too the right, then the box will be displayed with it's right hand edge to the left of the pointer icon's left hand edge. If the pointer is too far towards the bottom of the screen, the the box will be displayed with it's bottom edge above the pointer icon's top edge.

In order to improve appearance, Help will attempt to fit help messages into a box of aspect ratio between 2:1 and 5:1, handling word wrapping as necessary. It will also bullet point items of information - it can do this because |M is already defined as a line seperater in help messages.

As with the previous version, the Help application itself will provide a core set of messages which explain the window tool icons, for example the close icon:

Help will also provide information about icon bar icons if the application responsible for them fails to provide it's own text eg.:

4.2 Options

Help will install an icon on the icon bar and a menu will provide a number of options:

Info and Quit provide the usual expected functions of providing program information and quitting the application.

The Suspend item is a tickable option and allows help messages to be suppressed temporarily. A click on the icon bar Help icon will also have the same effect - that is, it will toggle help messages on and off. If help messages are suppressed, then the icon bar icon will be greyed.

To follow a general Ursula philosophy, a Configure plug-in will be provided to allow setting of further Help options. The plug-in will provide a window such as shown in the following picture:

The font pop-up menu allows selection of the font which the help message will be displayed in. Delay specifies how long, in centiseconds, the pointer must be held still before a help box will pop up. Finally, 'Hide common messages' allows the suppression of the more common help messages - these are those provided by Help itself (describing window furniture), plus those from Filer and Pinboard.

Upon the user clicking 'Set', the plug-in will write a text file called 'Config' to <Choices$Write>.Help, with the following format:

# Help configuration

Font:Homerton.Bold.Oblique

Size:10

Delay:20

Still distance:-1

Hide common:No

Drop shadow:Yes

Repeat message:Yes

This configuration file contains more options than can be set from within the configure plug-in. These are included for the benefit of more advanced users who may wish to change them:

Font - specifies the name of the font used to display help messages. Default font is 'Homerton.Bold.Oblique'.

Size - specifies the font size to use, in points. The default size is 10pt.

Delay - specifies the delay, in centiseconds, for which the pointer has to be still before a help box is displayed. The default delay is 20cs.

Still distance - specifies the distance, in OS units, which the pointer is allowed to move, but still be considered still. If set to -1, the distance will be read from the CMOS setting for 'Double click cancel distance'. Default value is -1.

Hide common - if Yes is specified, then common messages (those supplied by Help, Filer and Pinboard) are hidden. Default value is setting is No.

Drop shadow - if Yes, then the help box is displayed with a drop shadow. Default setting is Yes.

Repeat message - if No, then a message that has just been displayed will not be re-displayed until a different message has been displayed. This prevents the same help box keep popping up as, for example, you move the pointer across the backdrop. Default setting is Yes.

If the directory<Choices$Write>.Help is not present, the plug-in will create it. If the configuration file is not present, both the Help application and the plug-in will assume the default values are the current settings.

5.0 Programming Interface

None.

6.0 Data Interchange

A new message, Message_HelpEnable, will be provided to allow tasks to switch help on and off, if the Help application is in it's suspended state (a number of applications already have help icons which when clicked on, launch !Help). The message has a double use in that it can also be used to prompt help to re-read it's configured options. This enables the help configuration plug-in to have immediate effect if it is running at the same time as the Help application.

Message number &504 Message_HelpEnable

+20 flags word

bit 0 set - disable interactive help (put !Help into it's suspend state)

unset - enable interactive help.

bit 1 set - force Help to re-read it's configuration.

7.0 Data Formats

No new data formats are involved.

8.0 External Dependencies

None.

9.0 Acceptance Test

• Reliability - the old Help application was quite robust, and the new version should be just as reliable.
• Memory usage - the new !Help should require no more than 128k to run in.
• Responsiveness - the Help window should not get in the way of the pointer and reduce responsiveness of the desktop.
• ROM space - the Help application should occupy no more than 48k of ROM space.

10.0 Non Compliances

None.

11.0 Development Test Strategy

Initial testing will involve creating a test application which can supply a variety of messages to !Help. Areas to check in particular include messages containing long words, long lines, strange symbols, few tokens and lots of tokens.

After this initial testing, then !Help will be trialled with lots of Acorn and 3rd party applications, checking that meaningful and well presented help texts are produced.

Volunteers within Acorn will then be sought to test the application on a day-to-day basis.

12.0 Product Organisation

The application will be part of the Ursula ROM build, present in the Apps directory.

13.0 Future Enhancements

None.

14.0 Glossary

N/A

15.0 References

1309,214/FS Ursula !Configure Changes

16.0 History

 

Revision	Who	Date	Comment
A	RML	15-12-1997	Started.
B	RML	15-01-1998	Updated after review.
C	RML	16-02-1998	Added Message_HelpEnable

This document is issued under license and must not be copied, reproduced or disclosed in part or whole outside the terms of the license.

© Acorn Computers Ltd 1997. 645 Newmarket Road, Cambridge, UK