The keyword help system uses the memory file facility of Vermont Views to display text from an ASCII text file in a window. You do not need to know the details of memory files to create text for the help system. Enough information is provided here to get you started.
The steps for creating and using an ASCII text file as the help file are outlined below. If you want to use dynamic loading of only the help file section that is being used, see Chapter 45, "Creating and Viewing Memory Files."
Designer: You can attach help to your forms and menus using the Designer. See the Designer User's Guide for more information. You can also attach help to forms and fields in your code, by following the procedure outlined below, at any point after you have read the form or menu from the Designer library.
If you use the Main Generator to generate your main() program, it will create the skeleton text for the help file, help.txt, and the code to read and process the help file. You will only need to edit the text file to include your specific information; you will not need to do any of the eight steps outlined below.
If you attach help to your forms and menus using the Designer but do not use the Main Generator, you will need to read and follow Steps 1-4 and Step 8.
Code: These are the steps necessary to add help to your application.
Step 1: Write an ASCII text file containing the help information.
Use any editor to create an ASCII text file. This file should contain all of the help information you need for your application. Generally, you will want to format the text to the width of the window you plan to use for the help system, but this is not a requirement. Give the file the name you will use in the program.
Step 2: Mark each section of the file with a keyword.
The keyword marks the part of the file that you want displayed for any particular field, choice list, form, menu, or menu item.
A keyword must start in the first column (column 0), have the system keyword character as the first character (an asterisk by default), and be the only text on the line. The keyword can be more than one word in length.
Only lines containing keywords can have the keyword character in the first column. If you need to change the default keyword character ('*'), you can use the set environment keyword character function, se_kwdch().
The system help function is passed the keyword and displays only the section of the file marked by the keyword. The keyword itself is not displayed.
You can append a comma and the character 'A' to the end of a keyword to indicate that this keyword section is to be loaded into memory only when that section is needed by the application. Dynamic loading is not discussed in this chapter. See Chapter 45, "Creating and Viewing Memory Files," for more information.
The help keywords for second-level help for data forms, scrollable regions, and menu forms are set by default to the following:
| *DATA HELP | Data form help keyword |
| *SCROLL HELP | Scrollable region help keyword |
| *MENU HELP | Menu form help keyword |
These correspond to the help keywords marked in the default help file, help.txt. You can use your own keywords if you plan to have help text that is different for each form or scrollable region.
The following is an example of how the text should appear in the help file. "*PART CODES" and "*SHIPPING CODES" are keywords for two sections of the help file. "*DATA HELP" marks the default help for form-level help (which is not reproduced here in its entirety).
|
Warning: The keyword character that marks the keyword must appear in the first column of the line.
Step 3: Include the help header file vv_help.h.
To use the help system, you must #include the vv_help.h header file in all modules that reference the help functions and in your main program before vv_main.h.
Step 4: Install the help file with help_mf().
Once you have constructed the help file, you can read it into memory and install it as the system help file with the following function:
|
||
|
|
|
|
|
|
|
|
|
A pointer to the help memory file is returned. Function help_mf() returns a NULLP on error.
Once the help file is installed, the user will be able to get help for any field, menu item, choice list, or form for which help text is available.
Step 5: Specify help for individual data or menu forms.
Designer: Skip this step if you have already specified help for your forms and menus within the Designer.
Code: Default form-specific help keywords for data forms and menu forms are set to "*DATA HELP" and "*MENU HELP", respectively. For any individual form, you can specify help information different than the default by calling the set form help function, sfm_help():
|
||
|
|
|
|
|
|
Specify the help keyword or help string message for help_stp_or_kwdp. Specify a pointer to the form for fmp.
For example, if your application has a top-level menu with sub-menu forms and you want to provide help information specific to the top-level menu, you could call:
|
If the user calls for help when in a sub-menu, the section of the help file marked by the keyword "*MENU HELP" would appear. If the user calls for help when in the top-level menu, the section of the help file marked "*TOP LEVEL MENU" would appear.
Step 6: Specify help for individual scrollable regions.
Designer: Skip this step if you have already specified help for each scrollable region within the Designer.
Code: The default help keyword for scrollable regions is set to "*SCROLL HELP". For any individual scrollable region, you can specify help information different than the default by calling the set scrollable region help function, ssr_help():
|
||
|
|
|
|
|
|
Specify the help keyword or help string message for help_stp_or_kwdp. Specify a pointer to the scrollable region for srp.
Step 7: Specify help for each field, choice list, or menu item.
Designer: Skip this step if you have already specified help for each field, choice list, or menu item within the Designer.
Code: Use the following functions to specify the keyword that marks the help text for a specific field, choice list, or menu item. You can specify either a string or a section of the help memory file marked by a keyword. When specifying a keyword, you must include the keyword character in the string.
To specify help for a field on a data form, a field in a scrollable region, or a field in a menu, use the set field help function, sf_help():
|
||
|
|
|
|
|
|
Specify the help keyword or help string message for help_stp_or_kwdp. Specify a pointer to the field for fldp.
To specify help for a choice list attached to a data field or a stand-alone choice list, use the set choice list help function, scl_help():
|
||
|
|
|
|
|
|
Specify the help keyword or help string message for help_stp_or_kwdp. Specify a pointer to the choice list for clistp.
For example, to add help to the part code data field (code_fldp), call:
|
Step 8: Free the memory for the help memory file.
If you no longer need the help file, or you wish to replace the current help file with another one, you can free the memory allocated by the system for the file with the memory file free function, mf_free():
|
