All interactive C/Base programs call the function showtext(C-3) to display
on-line help from the program's helpfile. When the operator requests help, the
program calls showtext to show the help text for each relevant help section.
The relevant help sections depends on the current task of the program. When
the operator views help sections, showtext is often called more than
once with various categories and subjects. For more information on showtext(C-3),
see Chapter 8, C/Base Functions.
The syntax for showtext is:
int showtext (
helpfile, category, subject, more)
Helpfile names the text file that contains the help information. For formfiles and menufiles, customized helpfiles can be created by the application developer. With form(C-1) and menu(C-1), the pathnames for their customized helpfiles have a .h appended to the pathname of the formfile or menufile. If no customized helpfile exists, the C/Base program calls showtext with the program's default helpfile in the C/Base administrative help subdirectory.
After opening the helpfile, showtext finds the first help section to display as follows:
1. Search for the first section whose section name matches category. If not found, showtext returns with -1.
2. If subject is not NULL and not empty, search the help sections following the category help section found in step 1 for the first help section whose section name matches subject. If no matching help section is found or if a section level number is encountered that is less than or equal to the level number of the help section found in step 1, showtext returns -1.
3. Display the help section found.
After finding the help section, showtext displays the help section's help text one screenful at a time. After each screenful, showtext displays
--More Help-- [ Press SPACE to continue or q to quit ]
at the bottom of the screen. The operator may at this time continue or stop the display of the help text.
Form feed characters (^L) may be inserted in the help text to mark the end of screen pages. All text following the form feed character is displayed on subsequent pages.
Showtext displays subsequent help sections as long as the section level numbers of the following help sections are greater than the section level of the requested (first) help section found.
Basically, subjects are sub-topics of a category as determined by the section level numbers. A help section is considered to be a sub-topic of another help section if it has a higher level number than the previous help section. This allows any help section to be organized into sub-topics. As such, the subject of one help section can be the category of another help section.
For example, a helpfile can contain help sections for a form and all its fields. The help sections for a form's fields can be defined as sub-topics of the form's help section. When showtext is called with category set to the name of the form and subject set to NULL, the form's help section is displayed first and then the help sections for all the form's fields. If showtext is called with category set to the form name and subject set to the current field name, only the help section for that field is displayed unless sub-topics for that field are also defined.
When no more help sections are available, the more parameter specifies that additional calls to showtext are pending from the calling program with other relevant section names. When more is FALSE (zero), showtext displays the following message after displaying the help text:
--End of Help-- [ Press any key to continue ]
When more is TRUE (non-zero), additional calls to showtext are pending and showtext displays the following message:
--More Help-- [ Press SPACE to continue or q to quit ]
The value returned by showtext specifies whether the operator has requested more help. If the operator pressed q to quit, the return value is 0. No additional calls should be made to showtext.
If the operator pressed SPACE for more help, the return value is greater than 0. Under these conditions, it is assumed that the program calling showtext has other relevant help sections to be displayed with different categories and/or subjects.
Showtext returns a negative number if an error occurred while opening or reading the helpfile, or if the section name could not be found in the
helpfile.