Advanced Visual Basic Techniques
(Publisher: John Wiley & Sons, Inc.)
Author(s): Rod Stephens
ISBN: 0471188816
Publication Date: 06/01/97

Browse Sequences A browse sequence defines a series of help topics that the user may want to view in order. For example, the topics in a browse sequence might define the steps needed to perform some complicated procedure.

The user can press the help system’s >> and << buttons to move forward and backward through a browse sequence. The format of a browse sequence’s identifier is group:number, as in “menus:20.” Topics within a browse sequence group are presented in numerical order. The topic with sequence number menus:20 comes before menus:21 and after menus:19.

Sequence numbers need not be consecutive. In fact, it is generally best to skip numbers between each topic so that other topics can be added to the sequence later if necessary. For example, the topics in a browse sequence might initially be numbered menus:10, menus:20, menus:30, and so forth.

Nonscrolling Regions Some help topics are quite long. In those cases, it may make sense to place some text in a nonscrolling region at the top of the help screen. Nonscrolling regions can appear only at the top of help screens. Many help files place a title for each topic in a large font within a nonscrolling region.

In the help context file, text to be placed in nonscrolling regions is marked with the “keep with next” attribute. In Microsoft Word, text is given this attribute by selecting the text, invoking the Paragraph command in the Format menu, selecting the Text Flow tab, and checking the Keep with Next box.

Creating the Help Project File The help project file gives the help compiler more information about how to build the help system. The project file is a plain ASCII file. If the project file is accidentally saved in Microsoft Word format or Rich Text Format, the help compiler will be unable to read the file. By custom, help project files are usually given a .HPJ extension.

The project file contains several sections, each beginning with the section title in square brackets. Table 2.2 lists the most important sections.

To make building and reading project files easier, one file can be included within another using the #include directive, as in the following code:

#include <file_name>

The number sign must be the first character on the line, and the angle brackets are required.

The [OPTIONS] Section Some of the more useful commands that can be specified in the [OPTIONS] section are listed in Table 2.3.

The [FILES] Section The FILES section lists the help project’s topic files. This section is required and should contain at least one file. Otherwise, the help file will be empty.

The [MAP] Section If a Visual Basic application will invoke a particular help topic from the help system, the topic must be given a numeric context value. The MAP section assigns numeric values to help topics. This section contains a list of context strings followed by their numeric values. For example, the following code assigned the value 100 to the topic with context string CONTENTS.

[MAP]
CONTENTS        100

The same context numbers can also be defined in a .BAS module. Then a Visual Basic application can include the module and use meaningful values to refer to topic numbers in the help file.

Public Const HLP_CONTENTS 100

The example below shows the complete ExpenseReporter help project file Expense.HPJ.

[OPTIONS]
COPYRIGHT = Copyright 1997, John Wiley & Sons, Inc. All rights reserved.
TITLE = ExpenseReporter

[FILES]
EXPENSE.RTF

CONTENTS       1
OVERVIEW       2
PRINT_PREVIEW  3
CTX_NAME       101
CTX_ID         102
CTX_DEPT       103
CTX_PROJ       104
CTX_FROM_DATE  105
CTX_TO_DATE    106
CTX_DATE       107
CTX_LOCATION   108
CTX_CATEGORY   109
CTX_DESCR      110
CTX_AMOUNT     111
CTX_NOTES      112
CTX_TOTAL      113
CTX_PREPAID    114
CTX_ADVANCE    115
CTX_DUE_EMP    116
CTX_DUE_COMP   117

Compiling the Help Project Once the help topic and help project files are complete, compiling them is relatively simple.

Visual Basic 5’s Help Workshop is a Windows program that includes a help compiler. By default, it is not installed when you install Visual Basic. To install Help Workshop, run the Setup.EXE program in the Tools\Hwc directory on the Visual Basic 5 compact disk. Once the program is installed, it can load and compile help projects.

The help compiler provided with Visual Basic 4 is located in Visual Basic’s Hc subdirectory and is called Hc.EXE. This compiler has a command-line interface so it should be run from an MS-DOS window. For example, the following command shows how to compile the help project Expense.HPJ located in the current directory.

C:\Projects> C:\Vb4\Hc\HC Expense.HPJ