Progress
Help Development
Guide


Help Topics and the Help Topics Dialog Box

The basic building block of a help system is the help topic, which is a concise, modular piece of information about a single subject. A help window displays one help topic at a time. Examples of help topics include: a description of a dialog box in your application, a definition of a term, a set of instructions to complete a task, and a description of a 4GL language element.

The Help Topics dialog box helps users to navigate in a help system. It appears when a user chooses Help Help Topics. The Help Topics dialog box appears in the form of a tab folder with three tabs: Contents, Index, and Find. The next three sections discuss the functions of these three tabs. Also, by convention, each help viewer window contains a Help Topics button, allowing the user to return directly to the Help Topics dialog box from any help topic.

The Contents Tab

Figure 2–1 shows the Help Topics dialog box for the Procedure Editor help system with the Contents tab on top. This is how it appears the first time it is called from the Help Help Topics menu item.

Figure 2–1: Help Topics Dialog Box with Contents Tab on Top

The Contents tab is populated by two types of icons: topic icons and book icons. Each topic icon represents a jump to a specific help topic in the help file. This means that when you double-click a topic icon, the help engine launches a help viewer window and displays the specified topic in it. Alternatively, topic icons can be used to jump to a help topic or the Help Topics dialog box in another help file.

Book icons are used to organize the Contents tab. Book icons do not cause you to jump anywhere outside the Contents tab of the Help Topics dialog box. They can contain only other topic or book icons. When you double-click a book icon, the display on the Contents tab expands to show the icons that book contains.

The appearance of the Contents tab is determined by a file known as the contents file. A contents file has the same name as the help file with which it is associated, except that the contents file has a .cnt extension. Unlike other help source files that are compiled into a single binary help file (.hlp), the contents file remains separate from the compiled help file, and must be present in the same directory as the compiled help file. If the help engine does not find a contents file, it displays the Help Topics dialog box with only the Index and Find tabs. For detailed instructions on creating contents files, see Completing Help Systems."

The Index Tab

Figure 2–2 shows the Index tab of the Help Topics dialog box for the Procedure Editor help system. Certain SYSTEM-HELP calls cause the Help Topics dialog box to appear with the Index tab on top. (See Providing Help for Progress Applications.")

Figure 2–2: Help Topics Dialog Box with Index Tab on Top

The Index tab in a help system is similar to an index at the back of a book. The Index tab displays an alphabetized list of all the index keywords in the help file. When you double-click on an entry in the Index tab, you jump to the help topic associated with that keyword or to the Topics Found dialog box with a list of topics associated with that keyword As the help author, you associate index keywords with help topics. See "Creating Help Topic Files," for detailed information on creating index keywords.

The Find Tab

Figure 2–3 shows the Find tab of the Help Topics dialog box for the Procedure Editor help system. The Find tab comes to the top only when you click on it.

Figure 2–3: Help Topics Dialog Box with Find Tab on Top

The Find tab provides full-text search capability. When a help file is accessed for the first time, the help engine reads through the file and creates an alphabetized list of every word in the file. This list is stored in a file with an .fts extension in the same directory as the .hlp file and the .cnt file. You do not need to do anything as the help author to create the .fts file.


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095