How to give Interactive Help

Aficionados of my reviews for the magazine will have noticed that I frequently complain that such-and-such a program 'does not support interactive help.' Interactive help - for those of you who haven't yet encountered this strange bee in my bonnet - is a system of WIMP message-passing where any application can send meaninful messages explaining its function to any other application that asks.

Applications that make it their business to ask include Help - which comes with RISC OS - StrongHlp from Stallion Software and BubbleHlp from David Pilling. The help messages produced by applications are usually context sensitive, and alter depending on the window and icon that the pointer is over at the time. You can get an idea of this by loading up Help and moving the pointer around the screen.

In order to make any applications that you are writing generate interactive help messages, you need to respond to the WIMP message number &502 (Message_HelpRequest). Your application should already be responding to number zero (Message_Quit), so this should not be a problem. The block passed in R1 in this case contains the following:

The standard behaviour for most applications is to use the window and icon handles to work out what help text to send, and then send it by doing the following:

The only complication in all this is working out the appropriate help text to send. In RISC OS 2 this is easier, as the WIMP will only ever request help when the pointer is over either one of your application's windows or the icon bar, in which case the window handle will be -2.

In RISC OS 3, you will also receive help requests when the pointer is over a menu owned by you, in which case the window handle will be generated pretty much at random. The easiest thing to do is to check the window handle given against all your application's windows - including -2 for the iconbar - and assume that the pointer is over a menu if it doesn't match. At this point you should call the SWI Wimp_GetMenuState wotj r0 set to one, r1 pointing to a (second) block of memory, r2 containing the window handle and r3 the icon handle. This will copy into the block of memory a list of menu selections identical to that which would be returned by Wimp_Poll with the Menu_Select reason code (9). From this, and knowledge which you should have anyway of which menu is currently open, you will be able to determine the appropriate help text.

The help text can contain any printable characters, including top-bit-set ones. In addition, it can contain the sequence |M which is translated by Help as a forced line break. Forced line breaks aside, Help and similar applications will try to split the text at a white space. The text must also be shorter than 240 bytes to be sent as a WIMP message.

You don't actually have to provide interactive help for every single icon in every single window; in fact, this can even confuse the user. It is worth spending a reasonable amount of time thinking what to put in the help text; given that a user needs help, what aspects of an icon's function is most likely to need explaining?

Source: Acorn User - 150 - Christmas 1994 - "Problems Solved"
Publication: Acorn User
Contributor: David Matthewman