Help Function
Volume Number: 3
Issue Number: 4
Column Tag: C Workshop
List Manager Inspires Help Function Solution 
By William Rausch, Battele Pacific Northwest Labs, Richland, WA
I’ve always liked the method of presenting “on-line help” information used by
the Excel™ program. When I received the LightSpeed C™ V2.01 upgrade for the 128K
ROMS, I created a similar kind of help function while learning how to use some of the
List Manager routines. This article presents my “help” function, and explains how to
implement it in C, using the List Manager.
The help dialog box is shown in Figure 1. It contains an OK button and two boxes,
one for the list of topics and one to show the help information for the currently
selected topic. The help function builds the list of topics dynamically, using an STR#
resource number passed to it by the calling routine. Each string in the STR# resouce
contains a topic and a reference number. The reference number is the ID of a HELP
resource. Whenever the user selects a topic, the ASCII text from the corresponding
HELP resource is displayed in a scrollable TextEdit record.
The code shown in Listing 1 consists of a very simple main() and an equally
simple do_about() function, and the routines that make up the help function:
do_help(), read_help(), show_help(), help_filter(), and help_action().
do_help() is called to start things off. It takes a single parameter, the ID of the
STR# resource that contains the help topics to be displayed. By using a parameter in
this way, it should be easy to introduce some context sensitivity into the help that gets
displayed. do_help() reads in the STR# resource and gets the number of topics in the
list. It reads the dialog resource for the help dialog window. The help_list user item is
then read in to get its dimensions. This information (dimensions and number of topics)
is used to create the empty list structure with a call to the List Manager routine
LNew(). Note that the List Manager requires that the dimensions include room for the
scroll bar (if one is present).
The read_help() function gets the individual strings from the STR# resource and
parses each one for a topic and an ID number. A backslash is used as the delimeter
marking the end of the topic and the start of the ID number. As each topic is read in, it
is added to the topic list by calling the List Manager routine LSetCell(). Its
corresponding HELP ID number is stored in the array help_id[]. Finally, the List
Manager routine LSetSelect() is called to select the first cell as the starting point and
LDoDraw() is called to make the list visible.
The show_help() function sets up the help text box by getting its dimensions
from the second user item in the dialog resource. (As with the topic list box, the user
item is large enough to include the scroll bar as well.) The font and size are then
specified. After some experimenting, I settled on 10-pt Geneva font. There is no reason
you couldn’t select some other font for your application though.
Once the help box is prepared, we load it with the HELP resource that
corresponds to the first topic in the list (since that topic is selected when the help
dialog first appears on the screen). This is done by merely reading in the HELP
resource designated by help_id[0]. A HELP resource is merely composed of ASCII text,
and it is copied directly into the TextEdit record using the TEInsert() routine. Finally,
the need for a vertical scroll bar is checked, and if it is, then it is activated and the
proper maximum value is set using SetCtlMax(). Then, we repeatedly call
ModalDialog() until the user clicks OK (or hits Return). At that time we dispose of the
various data structures and return.
Fig. 1 Our help function demo in action!
The interaction with the user is controlled by the help_filter() function passed
to ModalDialog() as a filterProc. (Note that help_filter() is declared as ’Boolean
Pascal‘. This is because it will be called by the ROM routines and needs to conform to
the expected way of passing parameters.) Since it gets to examine every single event
that occurs while the modal dialog is running, it is very easy to respond to user
actions. Basically, the routine is nothing but a switch statement on the type of event.
On an updateEvt it redraws the user items (our two boxes). On a keyDown it checks to
see if it was a Return and, if so, tells the calling routine that the OK button was
selected. On a mouseDown, it may perform a number of activities as we will see. For
any other event, it does nothing.
To handle a mouseDown event, the function first checks to see if the mouse was
clicked in a scroll bar. If it was clicked in our help box scroll bar, TrackControl() is
called. TrackControl() is called with or without an actionProc depending on whether