Volume 7A: XView Programming Manual

An event handler for a canvas would have to track help-key events, display the help frame,

and provide the text to display in the frame. The following code fragments show how this

might be done.

...

canvas = xv_create(frame, CANVAS,

...

WIN_CONSUME_EVENTS, ..., ACTION_HELP, ..., NULL,

WIN_EVENT_PROC, my_event_handler,

NULL);

...

my_event_handler(window, event)

Xv_Window window;

Event *event;

{

if (event_action(event) == ACTION_HELP) {

xv_help_show(window, "canvas:help_info", event);

return;

}

...

}

The meaning of “canvas:help_info” is the same as the help data described earlier.

23.2.5 Help File Installation

Once the help file has been written, you should install it in /usr/lib/help on your system. If

you don’t, then the user must set the $HELPPATH environment variable correctly to point to

the path where the file actually resides. Otherwise, the user’s request for help will result in a

notice that help being posted cannot be found. Further, the file and the path to the file

(including directories and links) must be readable and searchable.

If circumstances prevent you from installing the help file in the designated area, it is not rea-

sonable to expect the user to know where the help file is. That is, do not expect that the user

has set the $HELPPATH variable correctly. You should set the environment for the user. The

path must be set to include at least two pathnames: /usr/lib/help and the path to your help file.

Both are needed because the user might request help from XView objects that provide their

own help; these help files reside in the default directory and may be needed.

The following code fragment shows how $HELPPATH should be initialized to locate help

files that do not reside in /usr/lib/help.

#include <stdio.h> /* for BUFSIZ */

#define HELPPATHNAME "/help/directory" /* set this yourself */

main(argc, argv)

int argc;

char *argv[ ];

{

extern char *getenv();

char *helppath, buf[BUFSIZ];

562 XView Programming Manual

xv_init(XV_INIT_ARGC_PTR_ARGV, &argc, argv, NULL);

/* ... */

sprintf(buf, "HELPPATH=/usr/lib/help:%s:", HELPPATHNAME);

if (helppath = getenv("HELPPATH"))

strcat(buf, helppath);

putenv(buf);

/* ... */

xv_main_loop(...);

}

Notice that we are setting the value of $HELPPATH regardless of its previous value. We

don’t know if the previous value of $HELPPATH existed; if it did, we don’t know if the nec-

essary pathnames were already in it. It is not worth the effort writing code to parse the string

to see if the path exists. Even if it does, we want to be sure it is at the beginning of the vari-

able. This ensures that the path is searched first. Since the same path can be set more than

once, no harm is done by prefixing the variable with the desired pathnames.

Further, the use of putenv() requires that the char * buffer passed be valid throughout

the life of the variable (e.g., until it is unset or reset later). In most cases, we would have to

use malloc() and pass in new memory or use a static variable. However, since this

putenv() is called from main, the variable space used by buf will not be corrupted until

main() exits. So we don’t bother with allocating memory.

Lastly, it should be mentioned that the effects of putenv() are temporary; the new path set-

ting affects this process and application only. Each process has its own version of

HELPPATH,

so setting it explicitly for our application does not affect other programs.

23.2.5.1 HELPPATH usage with internationalization

The help mechanism checks the value of the attribute

XV_USE_LOCALE

. If this attribute is set

to

TRUE, the help files are searched for in locale specific directories, according to the setting

of the attribute XV_LC_DISPLAY_LANG. If XV_USE_LOCALE is TRUE, XV_LC_DISPLAY_LANG

is "C," and HELPATH is set to $APPHOME, then the application searches in the specified

directory, as well as in the language specific directory for its .info files. In this case, the

search path includes two directories:

$APPHOME/C/help

$APPHOME

23.2.5.2 Setting the application name

The attribute XV_APP_NAME sets the string to be used by XView as the application’s name.

(Currently this is only for the help package). The application name can be localized using

gettext around the string that is set with XV_APP_NAME. XView will use the localized

string set with XV_APP_NAME in the header of spot help windows to indicate which applica-

tion generated the help window.

Help Facilities

Help Facilities 563

This attribute allows for more than one help file while still displaying the same name in the

spot help header window.

23.3 Help Package Summary

Table 23-2 lists the attributes and procedures for the HELP package. This information is

described fully in the XView Reference Manual.

Table 23-2. Help Attributes and Procedures

Attributes Procedures

XV_HELP_DATA xv_help_show()

HELP_STRING_FILENAME

XV_APP_NAME

564 XView Programming Manual

This page intentionally left blank

to preserve original page counts.

This page intentionally left blank

to preserve original page counts.