This program demonstrates an approach to context sensitive help in CLIPPER programs. The demo is written in native Summer '87 code. HELP.PRG is designed so that all help text may be placed in a single text file. Help blocks in the file are delimited with a character of your choice. The file is automatically indexed to a character string when HELP_INIT() is first called (or else the index is read from an optional index file). HELP_INIT() maintains a public array of help parameters for use by HELP.PRG. The text you are reading now is displayed with default settings by an explicit call to HELP.PRG.

Keeping help in a single text file has several advantages:

o File proliferation headaches are avoided
o Memory is used only as needed
o The help file may be edited easily without Clipper
o Editing does not require recompiling/relinking

For context sensitive help, your main programming responsibility is to supply a UDF that returns as output the number of the desired help block in the text file. The UDF input is the same program name/line number/variable parameters that are passed to HELP.PRG when the user presses F1. You may use READVAR() or other global parameters to assist in pinpointing the help text. Note that the UDF need not be supplied if you choose to use only explicit help calls.

You may, of course, also tweak HELP.PRG. You might, for example, wish to make the color scheme more flexible or allow different window borders. I've tried to separate what will be stable from application to application and stick this in HELP.PRG. I've left what varies to parameters you pass to HELP_INIT() and to the application-specific UDF you supply elsewhere.

Browse through the rest of this demo and use the F1 key liberally to see the effect of program options. Refer to the source code for more information. In particular, refer to the opening comments in HELP.PRG for descriptions of the global help parameters.

Note that help calls are forced by HELPDEMO.PRG on GET errors (menu options 7 and 8).
EOB 1 EXPLICIT CALL

This option displays HELP.PRG with an explicit call. This type of display (a full file display--up to 63K) is a memory hog and is not likely to be useful in general. In the demo, however, this lets you check the source code to see what is going on.
EOB 2 CHOICE=1

This option displays the HELPDEMO.PRG source code. Press F1 at the previous option for related information.
EOB 3 CHOICE=2

This option swaps the color settings for the help window border and the help window interior. HELPDEMO.PRG sets the two foreground colors differently, but keeps the background colors the same. This would be a typical approach.
EOB 4 CHOICE=3

This option toggles a variable that determines whether help text is displayed or whether current parameter information is displayed instead. This is principally a debugging tool included in HELP.PRG.

You could, for example, allow your programs to be passed an optional command-line parameter to turn on this feature.
EOB 5 CHOICE=4


This option toggles the F1 help key state, i.e., turns context sensitive help on and off. With F1 help off, you may still call options 1 and 2 to get explicit help calls, but F1 key help is disabled.
EOB 6 CHOICE=5

This option cycles the border type through the four allowed values. The border may be single or double bar, either with or without shadow.
EOB 7 CHOICE=6

This option lets you resize the help window. Note that this help text will appear when you press F1 at the menu or at any one of the GETs. It will also appear automatically should you try entering invalid coordinates. The minimum window size is 3 lines by 9 columns (including border).

If the window size is too small for the text window parameters (e.g., title or footer), these will be truncated on display by HELP.PRG. HELP.PRG and HELP_INIT() make reasonable adjustments and validity checks to keep your application running even with bad parameters.

It is important to note, however, that available memory is NOT checked. On each help call, the full help text block is read to a single string, then displayed in the window with MEMOEDIT(). The memory required is more than twice the size of the text block (and the memory for the string and its temporary copy must be contiguous). This should not be a problem as long as individual help blocks are kept small.

This is also why full file displays should be used with caution.
EOB 8 CHOICE=7, T/L/R/B

This option lets you change some text strings used by HELP.PRG. If you try to null out the error message string, this help text appears automatically.

HELP.PRG allows a null error message (although it is not recomended), but HELPDEMO.PRG does not, just to demonstrate trapping invalid string entry.
EOB 9 CHOICE=8, TITLE/FOOTER/ERRMSG/EOTMARK

EOB 10 CHOICE=9 No help--demos "Unavailable" or error message display