A purchaser of a commercial Windows application would undoubtedly return the product for a refund if a comprehensive online help system were not included. Users have come to expect context-sensitive help systems in all Windows applications, including
shareware products. Context sensitivity means that the help system displays a window containing the topic that closely corresponds to what the user presently is attempting to accomplish with the application.
The help systems of mainstream Windows 95 applications use most, if not all, of the new features of Windows 95's 32-bit Winhlp32.exe; Winhlp32.exe eliminates the necessity of help authors being programmers too. (You can, however, write macros and
Windows DLLs to create programmable help systems.) The version of Winhlp32.exe that accompanies Windows 95 and Windows NT 3.51+ provides a number of features that weren't available in the Windows 3.1+ version, such as Contents, Index, and Find tabs. This
book covers only the Windows 95 and Windows NT 3.51+ versions of Winhlp32.exe and refers to Windows 95 and Windows NT .hlp files as WinHlp32 files that are used by the WinHlp32 engine.
Window's WinHlp32 engine enables you to create a single .hlp file that provides built-in instructions that Winhlp32.exe uses to display the appropriate topic information in a window with a predefined appearance and set of controls. One of the principal
advantages of the WinHlp32 system is that the usage of Windows help features is quite inconsistent across the broad spectrum of Windows 3.1+ applications. If you follow the few simple help-file design guidelines presented in this chapter, the help files
you create for your Visual Basic 4.0 database applications will perform identically to their larger kin, such as Winword.hlp (956KB for Word 7.0), Mainxl.hlp (1.3MB for Excel 7.0), and the other mega-.hlp files for mainstream 32-bit Windows applications.
This chapter briefly describes the new capabilities of the 32-bit Windows help system and how your Visual Basic 4.0 database applications can take advantage of the WinHlp32 system. Next, the chapter discusses how to organize your WinHlp32 system with
context strings, context IDs, hypertext mapping, and other features that provide context-sensitivity, hypertext links, and browse mode sequences. The chapter concludes with a discussion of a commercial help-authoring tool that can aid you in creating
WinHlp32 files and a discussion of how you can call the 32-bit WinHelp API function of User32.exe from Visual Basic code.
WinHlp32 is backwardly-compatible with existing 16-bit WinHelp .hlp files, but does not extend the new features of WinHlp32 to Windows 3.1+ help files. Following is a list of the principal differences between Windows 3.1+'s WinHelp engine and WinHlp32:
Figure 26.1. The Contents page of the Visual Basic 4.0 help file, Vb.hlp.
Figure 26.2. A typical two-level index entry with the Topics Found dialog open.
Figure 26.3. The result of a full-text search on "ole server."
Figure 26.4. The Windows 95 Help Workshop displaying a help project file (Nwind.hpj).
32-bit Hcw.exe and its associated help files and DLL are included with the Professional and Enterprise editions of Visual Basic 4.0. These files are not installed in your \Vb4\hc folder by the Setup application. Setup only installs HC.EXE and related 16-bit WinHelp files. To install Hcw.exe, copy all of the files in the \Tools\Hcw folder of the CD-ROM to your \VB4\hc or a folder of your choice, then create a desktop shortcut or StartMenu choice that points to Hcw.exe.
Visual Basic 4.0 has features that enable you to assign individual help windows to forms and controls to create context-sensitive help. The interface between your Visual Basic application and your WinHlp32 .hlp file(s) comprises the following two basic
elements:
The sections that follow describe how you create WinHlp32 files and how you assign context IDs to topics to create context-sensitive help.
A WinHlp32 .hlp file is a compiled version of a word processing document file saved in Microsoft rich text format (.rtf). Rich text format is a page description language used to exchange formatted text between document processing applications. You use
.rtf files, as an example, to transfer Microsoft Word from the Windows version to the Macintosh version. Most Windows word processing applications are capable of saving documents as .rtf files. Rich text format is similar in concept to Adobe's PostScript
page description language, but .rtf is not used to print documents. Figure 26.5 shows part of the .rtf version of this paragraph, created by Word 7.0, displayed in Notepad's window.
The .rtf files that you create include a header that describes the page format, fonts, and styles in use. PostScript files contain a header that serves a similar purpose. An escape character (\) precedes page- and character-formatting data in .rtf
files, and French braces (a.k.a. curly braces, {}) enclose groups of formatting data and text to which the formatting applies. Most of the header information in Word .rtf files is derived from the template (.dot file) in use when you write the document.
Only a small part of the .rtf file header appears in Figure 26.5; the first sentence of the preceding paragraph is highlighted to identify the point where the paragraph starts.
Figure 26.5. Part of the .rtf version of a Word 7.0 document.
Instructions to the WinHlp32 engine are embedded in the .rtf file in the form of footnotes designated by footnote symbols, such as $ and #, rather than by conventional footnote numbers. Topic titles are designated by $ footnotes, and the context
strings that uniquely identify a topic to the WinHlp32 engine use the # symbol. A topic is a help window that is devoted to a single subject; topics are separated from one another in your word processing document by hard page breaks (usually created with
the Ctrl+Enter key combination). Figure 26.6 shows part of a simple help topic from the Nwind sample help file included on the accompanying CD-ROM.
All of the files required to create the Nwind.hlp Windows 95 help file with Hcw.exe are located in the \Ddg_vb4\32_bit\Chaptr26 folder of the accompanying CD-ROM.
Figure 26.6. The Contents topic of the Word 7.0 Nwind.doc file for the sample Nwind help project.
In Figure 26.6, Contents is the topic title and IDH_CONTENTS is the help context string for the topic. Hot spots are individual words, blocks of text, or images (.bmp or .wmf files) that are formatted with the double-underline or strikethrough
attribute and are followed by a help context string formatted as hidden text. When you click a hot spot, WinHlp32 jumps to the topic identified by the context string that follows the hot spot text. Figure 26.7 shows the Help Topics Contents page of
Nwind.hlp.
Figure 26.7. The Contents page of the Nwind.hlp sample help file.
You can embed or link graphic objects contained in bitmap (.bmp) or vector image (.wmf) files in your WinHlp32 files. The easiest method of adding bitmapped images to your help files is to embed the image in .bmp format in your .doc or .rtf file using
Word. However, large bitmap files usually are handled more efficiently by linking the graphic file to the WinHlp32 file by reference to its filename. Figure 26.8 shows the Nwind.rtf file help topic for the File | Printmenu choice. The icon (a
bitmap image captured from Word 7.0's toolbar) is embedded in the .rtf document by choosing Picture from Word 7.0's Insert menu to display the Insert Picture dialog and then double-clicking Undo.bmp in the Name list. The {bmc Printcdl.bmp}
entry below the line of text causes the Printcdl.bmp bitmap file to be inserted at the position of the { character.
Figure 26.8. A help topic with an embedded bitmap icon.
The term link is used in this chapter to differentiate between embedding a graphics file in the .rtf file and creating a reference to a separate graphics file with {bm? filename.ext} entries in your .rtf file. The ? placeholder determines whether the graphic is placed as a character , at the left margin (l), or at the right margin (r). When you compile the help file with the WinHlp32 compiler, the graphic that you link is embedded in the .hlp file you create, unless you specify otherwise. (You do not need to supply the .bmp file along with your .hlp file.)
Figure 26.9 shows the Print topic with the embedded print icon bitmap and the bitmapped image of the Print dialog that is linked with the {bmc printcdl.bmp} reference.
You can create hot spots in graphic images you link to your WinHlp32 file using the 16-bit Hotspot editor, SHED.EXE, which is included with the Professional and Enterprise editions of Visual Basic 4.0 and is installed in your \Vb4\hc folder. The
Hotspot editor creates an .shg (system hypergraphic) file from .bmp, .dib (device-independent bitmap), or .wmf files. To add hot spots to a .bmp, a .dib, or a .wmf file, follow these steps:
Figure 26.12. The pop-up window that is displayed when you click the lighthouse hot spot.
One of the advantages of using SHED.EXE is that the Hotspot editor compresses the .bmp files. As an example, Nwind.bmp requires 24KB of storage, while Nwind.shg occupies only 11KB. Note also that you cannot add hot spots to bitmaps you embed in WinHlp32 .rtf files.
Creating the final WinHlp32 .hlp file from your .rtf file and any graphics that are referenced in the .rtf file is a three-step process:
The three sections that follow describe the preceding steps.
Help project files, which usually are named AppName.hpj, are similar in concept to Visual Basic 4.0 project files and to C and C++ make files. The content of the project file for the Nwind.hlp sample help file, Nwind.hpj, appears in Listing
26.1.
Listing 26.1. Sections and entries in the Nwind.hpj help project file.
[OPTIONS]
HCW=0
ERRORLOG=.\NWIND.ERR
LCID=0x409 0x0 0x0 ;English (United States)
REPORT=No
CONTENTS=IDH_CONTENTS
TITLE=Northwind Traders Example Help File
BUILD=WINDOWS
HLP=.\Nwind.hlp
[FILES]
NWIND.RTF
[BUILDTAGS]
WINDOWS
[MAP]
IDH_Contents=10
IDH_Customers=230
IDH_Edit_Menu=120
IDH_Entering_Invoices=221
IDH_Entering_Orders=211
IDH_File_Menu=110
IDH_Invoices=220
IDH_Logging_Off=302
IDH_Logging_On=301
IDH_Menu_Commands=100
IDH_Networking=300
IDH_Orders=210
IDH_Print=117
IDH_Procedures=200
IDH_Undo=121
IDH_View_Menu=130
IDH_Workgroups=303
[CONFIG]
BrowseButtons()
CreateButton("Glossary_Btn","&Glossary",
"JI(qchPath,`IDH_Glossary')")
Help project files are text files that are organized into sections and are similar in structure to Windows 3.1+ .INI files. Table 26.1 lists the most commonly used sections of a help project file, whether the section is required in the file, and a
brief description of the purpose of the section. Keywords for entries in the options section also are described in Table 26.1.
| Section of .HPJ File | Section Required? | Description |
| [OPTIONS] | No (but usually present) | Defines the options that control the WinHlp32 compilation process. Some of the more common option entries include the following: |
| [OPTIONS] Keywords | ||
| ROOT=d:\path | Defines the path to your help source files. | |
| CONTENTS=ContextString | Sets the context string for the index topic with the Windows 3.1 Help compiler, HC31.EXE. | |
| TITLE=AppName Help | Sets the title for the WinHlp32 file, which appears in the help window's title bar. | |
| ICON=IconFile.ico | Sets the icon that is displayed when the help window is minimized. | |
| COMPRESS=0|False | Controls file compression. 0, or False, means do not compress files. 1, or True, compresses the file. Compressing .hlp files saves disk space at the expense of speed in displaying help windows (due to the time required to decompress the file). | |
| WARNING=3 | Determines what errors are reported. 0 through 3 control the level of error reporting: 0 = no error reports; 1 = most severe warnings; 2 = intermediate warning level; and 3 = report all warnings. | |
| REPORT=1|ON | Determines whether progress reports of the compilation are provided. 1, or ON, = report progress of compile; 0, or OFF, = no report. | |
| [FILES] | Yes | Specifies the help source files included in the compilation. |
| [BUILD] | No | Specifies topics to include in or exclude from the compiled file. |
| [BUILDTAGS] | No (Yes if [BUILD] specified) | Names valid build tags, enabling the selection of topics to be compiled within a file. |
| [CONFIG] | Only if DLL functions are called or buttons added | Registers custom DLLs whose functions are called by WinHlp32 macros, including macros for adding buttons to help topic pages. |
| [BITMAPS] | No | Specifies bitmap or .wmf files used in the compilation and not embedded in your WinHlp32 document. This section is not required if you used the ROOT= entry in the section to specify the path to the referenced bitmap files. |
| [MAP] | No (but usually present) | Associates context strings with context ID numbers. You need a map section to use the ContextID property of Visual Basic forms and control objects. |
| [ALIAS] | No | Enables you to assign more than one context string to a subject. |
| [WINDOWS] | No | Describes the main WinHlp32 window and any secondary window types in the help file. |
| [BAGGAGE] | No | Names any additional data files that are to be incorporated within the WinHlp32 file. |
You can write a simple help project file in NotePad, WordPad, or any other word processing application that outputs conventional ASCII test files. Commercial help-authoring tools, such as RoboHELP 95, automatically create the AppName.hpj project file for you. Using a help-authoring tool saves a substantial amount of time, especially when creating help files with a large number of help topics. Using RoboHELP 95 is described later in this chapter.
Once you've written the AppName.rtf and AppName.hpj files for your Visual Basic 4.0 application, you use Hcw.exe (Help Workshop) to compile your help file and its associated graphic elements, if any, into AppName.hlp (the primary
help file) and AppName.cnt (the contents file that creates the entries for the Contents page). The following steps describe the use of Hcw.exe to compile a WinHlp32 help file:
To create help files for 16-bit Windows 3.1+ applications, you use HC.EXE with the name of the project file as its command line argument, as in HC [PATH\]APPNAME.HPJ, from the DOS prompt. Operation of HC.EXE during the compilation process is similar to that of Hcw.exe. Warning or error messages are written to the DOS window.
Chapter 3, "Creating the Topic Files," in the Help Compiler Guide refers to various versions of Microsoft Word and other word processing applications that support .RTF as help "authoring tools." This is a questionable definition,
because help-authoring tools usually are defined as commercial (including shareware) applications or Word for Windows templates that provide at least the features in the following list:
At the time this book was written, there was no Windows word processing application available that provided any of the features in the preceding list. No Visual Basic database application developer should be without a commercial help-authoring tool
that includes at least the preceding features. The section that follows describes Blue Sky Software's RoboHELP 95, a retail help-authoring systems with a sophisticated feature set.
It's an uncommon practice to create Windows help files without the aid of a commercial or shareware help-authoring tool. There are a variety of help-authoring tools available for 16-bit Windows 3.1+ help, but relatively few applications for creating
full-scale WinHlp32 help files. This section briefly describes one of the most popular professional help file authoring tools for Windows 95 and Windows NT 3.51+ applications—RoboHELP 95.
Blue Sky Software Corporation's RoboHELP 95 consists of several custom DLLs and help templates for Microsoft Word 7.0. Blue Sky Software includes Hcw.exe and SHED.EXE with RoboHELP, as well as an icon and bitmap editing application, PaintIt, a screen
capture utility, and a 32-bit OLE control, Smthlp32.ocx, that you can use to add a stylized help button to 32-bit Visual Basic toolbars and forms. RoboHELP 95 also provides a set of tutorial files and a help file that explains how to create secondary help
windows. RoboHELP comes with a well-written and thoroughly indexed 450-page manual.
RoboHELP 95 is designed primarily for authoring help files from scratch in Word 7.0, rather than from a pre-existing manual in the form of a .doc file. RoboHELP 95 includes a utility for importing an existing .doc file into a new RoboHELP .doc file,
then changing the existing styles to conform to RoboHELP 95 style. When you launch RoboHELP 95 from the Start menu, you have the choice of creating a new project or opening an existing project. Figure 26.18 shows the Create New Help Project dialog with
entries to create a test help project.
Figure 26.18. Entering the help project title and filename for a new WinHlp32 help file.
RoboHELP 95 provides a floating toolbox, similar in concept to Visual Basic's toolbox, that enables you to choose from one of 14 different actions. Figure 26.19 shows RoboHELP 95 displaying part of the Nwind.doc help source file inserted into the new
help project document. RoboHELP's default font size is 8 points for Windows 95 help files.
Figure 26.19. RoboHELP 95's toolbox for choosing help-authoring functions.
When you click the Topic button of the toolbox to add a new topic to your help document, RoboHELP displays the Insert New Help Topic dialog shown in Figure 26.20. (Click the Advanced button to display the Context String, Browse Sequence, Build Tag, and
Macro text boxes.) You enter the help topic title and the search keywords for the topic, if any. With the advanced options selected, you can choose your own context string to identify the topic.
Figure 26.20. RoboHELP's dialog for adding a topic to a help document.
To create a hot spot with a jump to another topic, you click the Jump button of the toolbox to display the Create New Jump Hotspot dialog shown in Figure 26.21. You can add a bitmapped graphic as the hot spot by clicking the Graphic button to display a
choice of compatible graphics files (.bmp, .dib, and .wmf). Figure 26.22 shows the Shortcut.bmp file included with RoboHELP 95 in the Insert Graphics Object in Hotspot Text dialog. Figure 26.23 shows the new topic added to the Robo95.doc source file.
Figure 26.21. RoboHELP 95's Create Hypertext to Help Topic dialog.
Figure 26.23. The new help topic added to the end of the inserted help document.
You need to create a contents file (AppName.cnt) before compiling your WinHlp32 project. Clicking the Add Contents toolbox button (the book icon with a ?) opens the Contents Tab Composer dialog. If you haven't previously created a contents file,
click the Add All button to add all of the help topics shown in the Topics pane to the Content Tab Composer pane. Right-click topics that have subtopics to display the pop-up menu and choose Convert to Book to change the page icon to a book icon. Use the
left and right arrow buttons to determine the level of the books in the hierarchy of the Contents page of the Help Topics dialog. (See Figure 26.24.)
Figure 26.24. Creating the help topic hierarchy for the Contents page of the Help Topics dialog.
To create the .hlp file from your help document, you choose Project | Make or click the Make Project button and then click OK to save changes to your .doc and .rtf files to display the Make Project tabbed dialog shown in Figure 26.25. Clicking the
Check tab lets you run a diagnostic test on the .rtf file that RoboHELP creates from your .doc file. Click the Make button of the Make Project page to start the compilation process. If no errors are detected, RoboHELP displays the dialog shown in Figure
26.26 while Hcw.exe compiles your .hlp file. Click the Run button of the Make Help Project into Help File dialog to display the Help Topics dialog for the WinHlp32 help file. Figure 26.27 shows the window for the New Test Help Topic shown in preceding
Figure 26.23.
Figure 26.25. RoboHELP 95's Make Project dialog.
Figure 26.27. The new topic window with a hot spot and jump button.
The project file, Robo95.hpj, created by RoboHELP for the Robo95.hlp file appears in Listing 26.2. (Most of the comments included by RoboHELP in the Robo95.hpj file have been deleted from Listing 26.2.) The [MAP] section of Robo95.hpj is empty because
no help context ID values are assigned to the context strings.
Listing 26.2. The help project file created by RoboHELP for the Robo95.hlp file, less comments.
; Help Project File for ROBO95 [OPTIONS] ;BMROOT=C:\DDG_VB4\32_BIT\CHAPTR26 TITLE=RoboHELP 95 Test Project BUILD=WINDOWS NOTES=1 OLDKEYPHRASE=NO OPTCDROM=0 REPORT=YES COMPRESS=12 ERRORLOG=C:\DDG_VB4\32_BIT\CHAPTR26\ROBO95.ERR [BUILDTAGS] WINDOWS CONFIG] [FILES] ROBO95.RTF [ALIAS] [MAP] [BITMAPS] [WINDOWS] ;Gloss="Glossary",(100,100,350,350),0,(255,255,255), (255,255,255)main=,,29188,, (w95sec)=,,20740,(r14745599),(r14745599),f2 [BAGGAGE]
Designating the master help file for your project and assigning property values to form and control objects provides all the WinHlp32 capabilities you need for most Visual Basic applications. However, if you use Visual Basic procedures that change how
control objects behave, you may need to set the HelpContextID values in Visual Basic procedures.
To control the action of the WinHlp32 engine with Visual Basic code, you call the WinHelpA (ANSI) function when you need to change a help filename or context ID value. WinHelpA is aliased to WinHelp in the function declaration, discussed in the next
section. The syntax of the 32-bit WinHelp function call, which is the sole help function contained in the User32.exe DLL, is as follows:
lngHelpOK = WinHelp(hWnd, szHelpFile, wCommand, dwData)
In the preceding syntax, lngHelpOK is an Long variable used to receive the return value of the WinHelp function. The arguments of the WinHelp function are explained in the following sections.
You declare the WinHelp function in the Declarations section of a module with the following statement:
Declare Function WinHelp Lib "user32" Alias "WinHelpA" _ (ByVal hWnd As Long, _ ByVal lpHelpFile As String, _ ByVal wCommand As Long, _ ByVal dwData As Long) As Long
As with other 32-bit Windows API function calls that have arguments of the String data type, you call the ANSI version (WinHelpA) rather than the Unicode version (WinHelp) of the function. Aliasing WinHelpA to WinHelp, although designed for backward compatibility with 16-bit Windows API calls, is a common practice when writing 32-bit code. The 32-bit version of WinHelpA uses the Long data type for Windows handles (hWnd), the help command (wCommand), and the return value. For backward compatibility, Windows 95 and Windows NT also provide 16-bit USER.EXE DLL, which includes the 16-bit WinHelp function.
The following list explains the statement's components for 32-bit Visual Basic 4.0 applications:
| wCommand Constant | Value | Description |
| HELP_CONTEXT | 1 | Causes a specific help topic, identified by a Long integer specified as the dwData argument, to be displayed. |
| HELP_QUIT | 2 | Notifies WinHlp32 that the specified help file is no longer in use and can be closed. The dwData argument is ignored. |
| HELP_INDEX | 3 | Displays the index of the specified WinHlp32 file, as designated by the author. The dwData argument is ignored. |
| HELP_HELPONHELP | 4 | Displays help for using the WinHlp32 application itself. The dwData argument is ignored. |
| HELP_SETINDEX | 5 | Sets the context number specified by the dwData argument, a Long integer, as the current index for the specified WinHlp32 file. |
| HELP_KEY | 257 | Displays the first corresponding topic found in a search for the keyword specified by the dwData argument—in this case, as a String variable. |
| HELP_MULTIKEY | 513 | Displays help for a keyword found in an alternate keyword table. The dwData argument is a data structure (user-defined data type) containing the size of the string, the letter of the alternate table, and the keyword string. |
32-bit WinHelp adds HELP_CONTEXTMENU, HELP_FINDER, HELP_SET_POPUT_POSITION, HELP_TCARD, and HELP_WM_HELP constants to the preceding list. As is the case with HELP_KEY and HELP_MULTIKEY, it's seldom necessary to use these new constant values.
Table 26.2 describes how the data type of the argument changes with the value of dwData. The dwData argument may be a Long integer (the most common data type), a String variable, or a user-defined data type. If you need to use the
HELP_KEY or HELP_MULTIKEY values, dwData is declared As Any and is passed by reference, not by value. When you want dwData to be ignored by WinHelp, you should set dwData to &H0 (null, rather than decimal 0) in your Visual Basic WinHelp
function call.
You don't need to add the constants listed in Table 26.2 to the Declarations section of your module if you want to substitute the Long integer values shown in Table 26.2 as the dwData argument when you use the WinHelp function. You must,
however, declare the MKH (multikey help) structure in your global module, declare a record variable, and assign values to its fields in your code if you plan to use more than one help key in your application. It's a good programming practice to make the
name of your help file a Public variable.
Assign the name of your help file to a Public variable, such as strHelpFile, and default wCommand and dwData values to lngCommand and lngHelpCtx in your Main subprocedure or in the Form_Load event-handler of the start-up form. These variables
are made Public so that they retain the last value set to all modules contained in your application. You set lngHelpCtx to the value of the help context ID of the topic you want to display when the user requests help at a particular point in your
code. The following is the code that appears in Sub Main or in the Form_Load event-handler:
'Assign initial values to help variables strHelpFile = "FileName.hlp" lngCommand = [HELP_CONTEXT|&H1] lngHelpCtx = &H1
To display a help window with a minimum of typing, add two subprocedures, FormHelp and ControlHelp, to a module. The code for the two subprocedures is as follows:
Sub FormHelp
'Purpose: Display a help window for a form
lngHelpOK = WinHelp(Screen.ActiveForm.hWnd, _
strHelpFile, lngCommand, lngHelpCtx)
End Sub
Sub ControlHelp
'Purpose: Display a help window for a control
lngHelpOK = WinHelp(Screen.ActiveControl.hWnd, _
strHelpFile, lngCommand, lngHelpCtx)
End Sub
If you specify dwData As Any, lngHelpCtx must be passed by value to dwData; but in this case the function prototype declaration does not include ByVal, so you must include the ByVal prefix with the argument when you call the function. lngHelpCtx is set to &H0 when dwData is ignored by WinHelp.
Online help is a critical component of all but the most rudimentary database applications. This statement applies not only to Visual Basic 4.0 Windows database applications, but also to database front-ends you create in any language. This chapter was
not meant to be a substitute for the Help Compiler Guide, nor did it provide the scope of books that are devoted to authoring WinHlp32 files. If the examples of using the RoboHELP 95 commercial help-authoring tool that was described in this chapter
accomplished their purpose, you'll acquire such a help authoring tool to accelerate the development of online WinHlp32 for your Visual Basic 4.0 database applications.
The next chapter, the last in this book, describes how you organize the Setup application for your Visual Basic 4.0 database front-ends and how to manage the distribution of your applications on diskettes.
