Name

C Prototype

/*** Standard widget functions ***/

int dw_help_create (Frame parent);
void dw_help_destroy (int id);
void dw_help_hide (int id);
void dw_help_redraw (int id);
void dw_help_reset (int id);
void dw_help_setlabel(int id, char *label);
void dw_help_show (int id);

/*** Functions specific to the Help widget ***/

int dw_help_exists();
void dw_help_invoke(int id, char *topic, char *key);

Description

The Help widget is invoked with a topic and a key. It looks for a file named topic.hw in directories specified in the HELP_PATH option and, if found, attempts to position the file at the first line containing the specified key.

Although any number of Help widgets can exist concurrently, only one is used in typical application programs. The first message widget to be created is treated specially - it can be referred to with widget id 0 (so functions can invoke it without knowing its id). The Help widget should be the second widget created so other widgets can use it (the Message Widget should be the first).

dw_help_create(Frame parent) => int

Create a Help widget as a child of XView Frame parent. The widget is initially empty and is not visible. A positive widget id is returned on success; 0 is returned on error. This is typically done only once and by the main program; everyone else uses Help Widget 0 (zero).

dw_help_destroy(int id) => void

Destroy the given Help widget.

dw_help_exists(int id) => int exists

Return TRUE (1) if any Help Widget already exists, FALSE (0) otherwise.

dw_help_hide(int id) => void

Unconditionally hide the given Help widget.

void dw_help_invoke(int id, char *topic, char *key) => void

Invoke Help widget id with file as per topic, positioned as per key. For instance the Help widget provides help about itself by calling dy_help_invoke(0, "widgets", "HELP WIDGET"); which looks for the file "widgets.hw" in the directories specified by option HELP_PATH and then positions the first line containing the string "HELP WIDGET" to be visible.

dw_help_redraw(int id) => void

Refresh the given widget.

dw_help_reset(int id) => void

Clear the given Help widget.

dw_help_setlabel(int id, char *label) => void

Set the label on the given Help widget. A value of NULL sets the default label.

dw_help_show(int id) => void

Make the given Help widget visible. This is not typically needed, since dw_help_invoke() automatically makes the widget visible.

OPTIONS:

HELP_FONT

Specify the font to be used in the Help text subwindow. It should be a fixed-width font which allows 80 characters to fit in the window, e.g. 10 or 12 pixel Courier.

HELP_PATH

Specify directories to be searched for .hw files as space-delimited fields in a string. The names can contain environment variables.

Return Value

Release 4.3 is the first release of this widget. The 4.3 Help widget is functionally identical to the 4.3 version.

Related Topics