From an application written with the dialog editor, you can invoke help for a specified help topic ID. Please bear in mind that you will have to create parts of the help associated with these help topic IDs outside the Natural development environment. You will also have to compile the help with the platform-specific help compiler.
To keep an overview of all the different help sections in an application, Natural provides you with the help organizer. With this organizer,
you assign a help ID (HELP-ID
attribute
value) to a specific dialog element;
you write the help text for the associated help topic; this text is converted to a .rtf file to be processed by the help compiler;
you optionally define the help topic's keywords;
you optionally assign a help compiler macro to the help topic;
and optionally you add a comment for your internal documentation purposes.
To create a help topic
Invoke the help organizer's main dialog.
Select a particular dialog element.
Generate a new help topic ID.
Return to the help organizer main dialog.
Assign the generated help topic ID.
Enter the external definitions for the help topic ID, such as the help topic text and the topic name.
Return to the help organizer main dialog.
Go to the topic list and see whether this new help topic fits your general organization of the help file to be created.
Return to the help organizer main dialog.
Save everything.
A dialog or dialog element can also be assigned a
HELP-ID
number independently of the help
organizer.
To do so
Open the corresponding attributes window. Enter a numeric value in the Help ID entry.
You must use the help topic's .h file to map the numerical ID that you enter here to the corresponding help topic ID (created by a markup in the .hlp file).
Natural expects the help file to be located in the resource (RES)
subdirectory of the current library or one of the STEPLIBs, or in the directory
referred to by the environment variable
NATGUI_BMP
. By default, Natural searches for a
help file with the same name as the current library, but you can explicitly set
the name of the help file via the
HELP-FILENAME
attribute. If no file extension is specified, Natural searches for a compiled
HTML help file with the extension ".chm" first, then
(if not found) for a WinHelp help file with the extension
".hlp". Thus, if no file extension is specified, it
is possible to upgrade from using WinHelp to using HTML help without changing
the Natural program. Note, however, that the Help Organizer only supports
WinHelp. If you wish to create HTML help content, you must use an external help
authoring tool to do so.
Whenever an end user presses F1 in an active dialog, Natural
first queries for a file with the value of the
HELP-FILENAME
attribute
plus the extension ".hnn"
where nn is the Natural language code. If it does
not find such a file, it queries for a file with the value of
HELP-FILENAME
plus the extension
".hlp"
Whenever the dialog element has the focus and the end user presses F1, Natural jumps to this help ID.
Note:
When adding online help to an application, it is recommended to
assign a HELP-ID
number to each dialog and to
write help texts for the dialogs. If the end user selects a dialog element to
which no HELP-ID
was assigned and presses
F1 to request help, help on the current dialog will come up. If no
HELP-ID
was assigned to a dialog element,
Natural will check whether the dialog element's parent - the dialog - has a
HELP-ID
. If not, Natural will check whether the
dialog's parent - the dialog one level higher - has a
HELP-ID
, and so on, until the top-level dialog
is reached.
To build a help file
Go to your command prompt.
Change to the directory referred to by the environment variable
$NATGUI_BMP
.
Issue the command HCRTF -X
helpfilename
.
Note:
This assures that the directory containing
HCRTF.EXE is specified in the
PATH
environment variable.
To test a help file
Invoke a dialog in your application.
Press F1.
The help topic for the dialog should appear.
Alternatively, the help file can be conveniently built and tested interactively by opening the .hpj file in the Help Compiler Workshop (HCW.EXE).
To display help in a popup window
Check the Popup Help option in the dialog attributes window.
Run the dialog.
Press F1 with the focus on a control which has a help ID associated with it.
The help topic associated with the focus control should appear in a popup window.