Back to Contents Previous Next
10. Interactive help **
There are two ‘Help’ syatems available to Wimp applications. One is via the Filer menu and one is via the RISCOS !Help application. They are independent of each other and hence either or both can be provided by any application.
The first system does not need any special facilities: all it needs is a file called !Help to be placed in your application directory - and many applications make their !Help file their main Manual. (Don’t confuse a !Help file with the !Help application!) If such a file exists then it will be detected by the Filer when the application is first ‘seen’ and the corresponding ‘Help’ item in the Filer menu tree will be enabled for selection. (This basic system can be very usefully enhanced by using a special set of system variables suggested by RISCOS/Castle. The latest version of Dr Wimp’s !Fabricate utility incorporates these features automatically.)
The second system provides interactive help. When activated, small windows containing focussed help text appear temporarily as the pointer is moved over the windows/icons/menus of an application. An application needs to take special steps to use this method. If it does then the help becomes active as soon as you start-up the RISCOS !Help application which comes with all RISCOS systems. (There are also enhancements available which make the appearing text windows more attractive e.g. like cartoon speech bubbles.)
DrWimp provides facilities to enable this second method to be used very simply. There are two facilities: one for windows and icons, and the other for menu items.
For windows/icons, all you have to do is return your own choice of help text for a given window handle and icon number in FNuser_help
.
In the tutorial !RunImage listing, enter the following lines into FNuser_help
:
DEF FNuser_help(window%,icon%)
h$=“”
CASE window% OF
WHEN info% :
CASE icon% OF
WHEN 0 : h$=“This application is called ‘MyApp’”
WHEN 1 : h$=“It tests the DrWimp library”
WHEN 2 : h$=“MyApp was written by Joe Bloggs”
WHEN 4 : h$=“This is the version number and date”
OTHERWISE : h$=“This is the MyApp info window.”
ENDCASE
WHEN iconbar% : h$=“This is the MyApp icon”
ENDCASE
=h$
Then save and reload !MyApp - and then load the RISCOS !Help application, If you now move the pointer over the info window or the iconbar icon you will see the short help text appear.
Similarly, for menu items, use FNuser_menuhelp
, eg:
DEF FNuser_menuhelp(menu%,item%)
h$=“”
CASE menu% OF
WHEN iconbarmenu%
CASE item% OF
WHEN 2 : h$=“Click <select> to quit"
ENDCASE
ENDCASE
=h$
Save the !RunImage again and re-run !MyApp to try things out. (After doing this you may find it best to quit - or just ‘Suspend’ - the !Help application, to stop the interactive help messages continuing to appear.)
[Your !RunImage listing should now look like listing RI_07 in Tutor1 (apart from the REM
lines, perhaps). Do not destroy it as the tutorial picks up again in Section 2.14 where it continues from this stage.]
The only important further points to note are that:
a) the string “|M” (that is, ASCII character 124 followed by “M”) can be inserted at any point(s) in your text to force a new line in the displayed text - but it takes up 2 characters each time you use it;
b) the maximum allowed length of a returned help string (including any occurrences of “|M”) is 235 characters.
No further explanation is necessary: it really is very simple.
You will appreciate that for many applications the above lists of help text items might be very long.
Also, help text in this form lends itself very well to using Message files to hold the text and using appropriate calls to FNwimp_messlookup
in FNuser_help
and FNuser_menuhelp
. (See Section 2.9 for details on using Message files.) In this way, for instance, help text in a choice of languages can be provided.
Top of page Back to Contents Previous Next