 |
» |
|
|
|
When a help request is made, the application determines what
help topic to display. It then creates (if necessary) and manages
a help dialog, and sets the appropriate resources to display a help
topic. Most requests display help topics that are part of the application's
help volume, but the Help System's help dialogs are also capable
of displaying man pages, text files, and simple text strings. The Help System's help dialogs are
based exclusively on Xt Intrinsics and Motif programming, so you
change the values within a help dialog just like any other widget:
by setting resources. The DtNhelpType
resource determines what type of information is displayed. It can
be set to any of these values: DtHELP_TYPE_TOPIC
for displaying normal help topics that are part of a help volume.
The volume is specified by setting the DtNhelpVolume resource; the topic
is specified by setting DtNLocationId
resource. DtHELP_TYPE_STRING
for displaying a string supplied by the application. Automatic word
wrap is disabled, so line breaks are observed as specified in the
string. The string is specified by setting the DtNstringData
resource. DtHELP_TYPE_DYNAMIC_STRING
for displaying a string supplied by the application, using word
wrap to format the text. Line breaks within the string are used
to separate paragraphs. The string is specified by setting the DtNstringData
resource. DtHELP_TYPE_FILE
for displaying a text file. The name of the file to be displayed
is specified by setting the DtNhelpFile resource. DtHELP_TYPE_MAN_PAGE
for displaying a manual reference page (man page) in a help dialog.
The man page to be displayed is specified by setting the DtNmanPage
resource.
These values are defined in the Help.h
file. See Also | |
To Display a Help Topic | |
Create a help dialog. Set the following resources for the help dialog: You can also set other values for the dialog, such as its
size and title. Manage the dialog using XtManageChild()().
This program segment displays a topic with the ID getting-started
in the volume MyVolume. ac = 0;
XtSetArg (al[ac], DtNhelpType, DtHELP_TYPE_TOPIC); ac++;
XtSetArg (al[ac], DtNhelpVolume, "MyVolume"); ac++;
XtSetArg (al[ac], DtNlocationId, "getting-started"); ac++;
XtSetArg (al[ac], DtNcolumns, 40); ac++;
XtSetArg (al[ac], DtNrows, 12); ac++;
XtSetValues (helpDialog, al, ac);
XtManageChild (helpDialog); |
If the help volume MyVolume
is not registered, then a complete path to the MyVolume.sdl
file is required for the value of DtNhelpVolume. To Display a String of Text | |
Create a quick help dialog. You can use a general help dialog to display string data,
but this isn't recommended because most of its features do not apply
to string data. Set the following resources for the help dialog: You can also set other values for the dialog, such as its
size and title. Manage the dialog using XtManageChild()().
This program segment displays a string stored in the variable
descriptionString. ac = 0;
XtSetArg (al[ac], DtNhelpType, DtHELP_TYPE_DYNAMIC_STRING); ac++;
XtSetArg (al[ac], DtNstringData, (char *)descriptionString); ac++;
XtSetValues (quickHelpDialog, al, ac);
XtManageChild (quickHelpDialog); |
If the string is no longer needed within the application,
the memory can be freed, because the help dialog makes its own copy
of the data. XtFree (descriptionString); |
To Display a Text File | |
Create a quick help dialog or retrieve one from your dialog
cache. You can use a general help dialog to display a text file,
but this isn't recommended because most of its features are useful
only for standard help topics. Set the following resources for the help dialog: You can also set other values for the dialog, such as its
size and title. In particular, you might want to set the width to
80 columns, which is the standard width for text files. Manage the dialog using XtManageChild()().
The following program segment displays a file named /tmp/printer.list.
It also sets the size of the dialog to better suit a text file. ac = 0;
XtSetArg (al[ac], DtNhelpType, DtHELP_TYPE_FILE); ac++;
XtSetArg (al[ac], DtNhelpFile, "/tmp/printer.list"); ac++;
XtSetArg (al[ac], DtNcolumns, 80); ac++;
XtSetArg (al[ac], DtNrows, 20); ac++;
XtSetValues (quickHelpDialog, al, ac);
XtManageChild (quickHelpDialog); |
To Display a Man Page | |
Create a quick help dialog. You can use a general help dialog to display a man page, but
this isn't recommended because most of its features are useful only
with standard help topics. Set the following resources for the help dialog: You can also set other values for the dialog, such as its
size and title. Manage the dialog using XtManageChild()().
The following program segment displays the man page for the
grep command. It also sets
the size of the dialog to better suit a man page. ac = 0;
XtSetArg (al[ac], DtNhelpType, DtHELP_TYPE_MAN_PAGE); ac++;
XtSetArg (al[ac], DtNmanPage, "grep"); ac++;
XtSetArg (al[ac], DtNcolumns, 80); ac++;
XtSetArg (al[ac], DtNrows, 20); ac++;
XtSetValues (quickHelpDialog, al, ac);
XtManageChild (quickHelpDialog); |
|
Printable version
