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:

• block!0 : the length of the block
• block!4 : the task handle of the help application sending the message
• block!8 : a reference number for replies
• block!12 : zero - probably - but not relevant
• block!16 : the message number (&502)
• block!20 : mouse x co-ordinate
• block!24 : mouse y co-ordinate
• block!28 : mouse button state
• block!32 : window handle
• block!36 : icon handle

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:

• copy the help text - with a zero byte at the end - to block!20
• work out the length of the help text, add one for the zero byte, round up to the nearest four, add 20 and store this - the word-aligned length of the message block - in block!0
• change the message number in block!16 to &503 (Message_HelpReply)
• execute the SWI Wimp_SendMessage, with r0 set to 17, r1 pointing to the block and r2 containing the handle of the task from block!4

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?