Adding Online Help

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.

Start of instruction setTo create a help topic

  1. Invoke the help organizer's main dialog.

  2. Select a particular dialog element.

  3. Generate a new help topic ID.

  4. Return to the help organizer main dialog.

  5. Assign the generated help topic ID.

  6. Enter the external definitions for the help topic ID, such as the help topic text and the topic name.

  7. Return to the help organizer main dialog.

  8. Go to the topic list and see whether this new help topic fits your general organization of the help file to be created.

  9. Return to the help organizer main dialog.

  10. Save everything.

A dialog or dialog element can also be assigned a HELP-ID number independently of the help organizer.

Start of instruction setTo 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 explicitely 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.

Start of instruction setTo build a help file

  1. Go to your command promt.

  2. Change to the directory referred to by the environment variable $NATGUI_BMP.

  3. Issue the command HCRTF -X helpfilename.

    Note:
    This assures that the directory containing HCRTF.EXE is specified in the PATH environment variable.

Start of instruction set To test a help file

  1. Invoke a dialog in your application.

  2. 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).

Start of instruction setTo display help in a popup window

  1. Check the Popup Help option in the dialog attributes window.

  2. Run the dialog.

  3. 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.