Interactive help system as supported by !Help (0.29)

By default, when Help is started, the interative help session is active, as shown by the interactive help window being open in the bottom left hand corner of the screen. To stop Help doing this, use *Set Help$Options ~I. If this is done, interactive help may be started by clicking on the help icon.

Using interactive help requires no intervention on the user's part. The window can be resized as desired and the text will be reformatted to fit the new size.

For an application to use interactive help, two WIMP messages are employed, one is used by Help to request the help text and the other is used by the application to return the text message.

To request help, the Help application sends a message of the following form:

block+16 &502 indicates request for help

     +20   mouse x co-ordinate
     +24   mouse y co-ordinate
     +28   mouse button state
     +32   window handle (-1 if not over a window)
     +36   icon handle (-1 if not over an icon)

The more astute of you will have realised that locations 20 onwards are the results of using Wimp_GetPointerInfo!

The WIMP system will pass this message automatically to the task in charge of the appropriate window/icon combination. If the application receiving the message wishes to produce some interactive help, it should respond with the following message structure:

block+16 &503

     +20   help message, terminated by 0

The help message may contain any legal printable characters. If the sequence |M is encountered, this will be treated as a line break and subsequent text
will be printed on the next line in the window.

The help application will issue message type &502 every 1/10th of a second to allow applications such as ArcEdit & ArcDraw to change the help text according to the current edit mode. To avoid flicker, the display will only be updated when the returned help string changes.

With certain applications, such as the Filer, no interactive help is supplied and the Help application supplies some default messages in instances like this.

What help should be provided?

The help text may contain printing character codes (including top-bit-set ones) and also NewLine charactes. It is terminated by a zero character. The display will split displays at a word boundary (space character) and force a newline for NewLines. The text should consist of simple complete English sentences, each starting on a new line and ending with a full stop. The sentences should usually be simple imperatives or information: Click SELECT to set the alarm.
The pointer is at pixel (47, 215) within the sprite. You are in Select mode.
Click ADJUST to change to Path-edit mode. This is the icon for ArcEdit.
In general menu entries need not be mentioned, except when specific menu entries interact with pointer operations. As a general rule present information of interest to the beginner near the top, and expert tips/information lower down.

The terms Click, Drag, Choose, Type, Press and Release should be used consistently. (Click = Press and Release). The menu buttons (SELECT, MENU, ADJUST) are in capitals, as are key names (e.g. ESC, RETURN, SHIFT, CONTROL, A, B, F1, COPY). Miss out speedups and shortcuts, just provide enough help to help the beginner without drowning him/her in information.

If you provide interactive help, do so thoroughly. Provide it on the icon bar, and on the work area of all your windows. If no actions are possible in a window, just
This window shows ...
is better than nothing.
You should assume the following abilities of the user: He knows what the MENU key is, can navigate menu trees and choose entries He knows what the icon bar is
He knows how to move/size/toggle/close windows, etc. He knows what "dragging an icon" means He knows what "filling in a field" (writable icon) means