Visual Basic 6 Black Book
(Publisher: The Coriolis Group)
Author(s): Steven Holzner
ISBN: 1576102831
Publication Date: 08/01/98

Adding Help Topics To The Help Index

You can add a Help topic to the Help index by inserting a footnote with the custom mark “K”, giving that footnote the text you want to appear in the index. For example, we add the item File Menu Items to the Help index in Figure 30.12, by adding a footnote, “K”, to the appropriate Help page in helper.rtf. Now when the user uses the Help file’s index, the items we’ve added, such as File Menu Items and Help Menu Items, appear in that index, as shown in Figure 30.14. When the user clicks them, the Help system jumps to the matching page.

Figure 30.14  Adding items to the Help system’s index.

Creating Help Pop-Up Links

You can create Help pop-ups, which work much like tool tips in a Visual Basic program. As an example, we’ve added the pop-up you see in Figure 30.15, which explains the term “file” with a pop-up. Pop-ups appear in Help files with a dotted underline; when the user clicks that pop-up, the associated text is displayed in a tool-tip-like window.

Figure 30.15  Adding a Help pop-up.

Adding a pop-up is just like adding a Help hotspot, but instead of double-underlining the hotspot, you just use a single underline. Let’s see an example. Here, we’ll create the pop-up you see at work in Figure 30.15. To do that, just underline the term you want to create a pop-up for, using the Visual Basic Format menu, and add the hidden text jump tag. We’ll use FILE_POPUP for the jump tag here, like this:

Open
        Opens a fileFILE_POPUP.
                ----..........

Because we’ve used a single underline instead of a double one, the Help system will display the text that has the tag FILE_POPUP instead of actually jumping to that page. We’ll see how to create that page in the next topic.

Creating Help “Tool Tips” Targets

To create a target page for a Help pop-up, you use footnotes with the custom mark “#”, just as you would for any Help hotspot. To complete the example we started in the previous topic, we add a new page to our helper example’s RTF file with the footnote “#” and the footnote text FILE_POPUP, as shown in Figure 30.16.

Figure 30.16  Adding a Help pop-up to an RTF file.

Finally, we place the text we want to display when the pop-up appears into the new page, as also shown in Figure 30.16. Now when the user clicks the underlined item in the Help system, the pop-up will appear, as shown in Figure 30.15.

Compiling Help Files With The Help Workshop

Now that you’ve created your RTF file with the Help text and hotspots you want to use, along with your Help project in the Help Workshop, how do you create the actual HLP file? You use the Help Workshop’s Compile item in the File menu. That menu item brings up the Compile A Help File dialog box you see in Figure 30.17; click Compile to create the Help file, which in the case of the example we’ve developed over the previous few topics is helper.hlp.

Figure 30.17  The Compile A Help File dialog box in the Help Workshop.

Congratulations—you’ve created a new Help file. But how do you launch it from Visual Basic? We’ll look at that next.

Displaying A Help File From Visual Basic

The Testing Department is calling. Your new Help file is very helpful, but now you’ve got to display it from your Visual Basic application. Makes sense, you think, but how do you do that?

To display a Help file from a Visual Basic program, you can use the Windows API function WinHelp:

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

Here’s what the arguments to this function mean:

•  hwnd—Handle of the window opening the Help file

•  lpHelpFile—Name of the Help file to open

•  wCommand—Open command; see the list that follows

•  dwData—Additional data as required for the Help file opening operation

Here are the possible values you can use for the wCommand argument:

•  HELP_CONTEXT = &H1

•  HELP_QUIT = &H2

•  HELP_INDEX = &H3

•  HELP_CONTENTS = &H3&

•  HELP_HELPONHELP = &H4

•  HELP_SETINDEX = &H5

•  HELP_SETCONTENTS = &H5&

•  HELP_CONTEXTPOPUP = &H8&

•  HELP_FORCEFILE = &H9&

•  HELP_KEY = &H101

•  HELP_COMMAND = &H102&

•  HELP_PARTIALKEY = &H105&

•  HELP_MULTIKEY = &H201&

•  HELP_SETWINPOS = &H203&

Let’s see an example. Here, we’ll open the helper.hlp Help file in an application named “helper” when the user selects the Help item in the application’s Help menu. To start, we declare WinHelp and the constants it can use:

Const HELP_CONTEXT = &H1
Const HELP_QUIT = &H2
Const HELP_INDEX = &H3
Const HELP_CONTENTS = &H3&
Const HELP_HELPONHELP = &H4
Const HELP_SETINDEX = &H5
Const HELP_SETCONTENTS = &H5&
Const HELP_CONTEXTPOPUP = &H8&
Const HELP_FORCEFILE = &H9&
Const HELP_KEY = &H101
Const HELP_COMMAND = &H102&
Const HELP_PARTIALKEY = &H105&
Const HELP_MULTIKEY = &H201&
Const HELP_SETWINPOS = &H203&

Private 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

Then, when the user selects the appropriate menu item, we display the helper.hlp file with WinHelp this way:

Private Sub mnuHelp_Click()
    retVal = WinHelp(Form1.hwnd, "c:\vbbb\helper\helper.hlp",_
        HELP_INDEX, CLng(0))
End Sub

And that’s it—now the user can open the helper.hlp file from the Visual Basic helper application, as shown in Figure 30.18.

Figure 30.18  Opening a customized Windows Help file from a Visual Basic program.

Now we’re supporting Help files in our Visual Basic applications. The code for this example is located in the helper folder on this book’s accompanying CD-ROM.