USING MICROSOFT HELP WORKSHOP

10
Using Microsoft Help Workshop 4.0

The Microsoft Help Workshop 4.0 is a set of tools, separate from Visual Basic, that you use to
create help files for applications that run under 32-bit Windows systems. The Help Workshop is
shipped on the same CD-ROM on which you received your copy of Visual Basic 6.0, in the
directory \Tools\Hcw. You invoke Setup.exe to install the Help Workshop on your computer.

You create your help data by using any word processor that supports footnotes and the Rich Text
Format (.rtf). Then you "compile" the RTF files and the help project file (.hpj) with the Help
compiler to create the help file.

You make a help file by using a special footnote markup language in Rich Text Format. The RTF
file is constructed in three sections: the jump text, the topic text, and the footnote tags.

The heart of the help document structure is the topic, a section of Rich Text bounded with a page
break. The first line of the section is footnoted with at least the special footnote character #. You
enter the topic ID of the topic section next to this character in the footnote area of the RTF file. (A
topic ID is a location address of the given topic within the RTF file.).

The sections interact by the use of strikethrough text to indicate that the characters of that text
are hypertext. You place text formatted as hidden after the strikethrough text. The text formatted
as hidden is the jump-to address that will be referenced by the strikethrough text. The contents of
the jump-to address is formally known as the Topic ID. When you run the RTF file through the
Help Workshop's Help Compiler, the strikethrough text is transformed into hypertext. When users
click the hypertext, the Help runtime engine (WinHelp.exe) looks to the text that was formatted as
Hidden and placed after the strikethrough characters for the address of where to jump. Then,
after the engine knows the address, it looks in the footnote section for the location of that address
within the help file. The engine then goes to the topic at that address and displays the
information.

Make a Simple RTF File

1. Open a New document from the File menu in Microsoft Word.

2. Enter the following:
CONTENTS

Welcome to the helper example application. This help

file gives you help on the menu items in helper.

To get help for the menu you are interested in, click a
topic:

File Menu Items

Help Menu Items
3. Enter a blank line following the last line above.
4. Enter a page break by choosing Break from Word's Insert menu and then selecting
Page Break, or by pressing Ctrl+Enter.
5. Enter the following line of text, followed by a page break:
This is the page where you will place the contents of
the Help file for the File Menu Items.
Information and Communication Technology Department 78
Palompon Institute of Technology
 USING MICROSOFT HELP WORKSHOP
10
6. Enter the following line of text, followed by a page break:
This is the page where you will place the contents of
the Help file for the Help Menu Items.
7. Go back to the first page. Enter IDH_FILE_MENU after the word File Menu Items. Be
sure to enter the text directly after the word; don't insert a space. Do the same for the
Help Menu Items and enter IDH_HELP_MENU.
9. Select the word File Menu Items and select Strikethrough in the Font dialog (choose
Font from the Format menu). Do the same for the Help Menu Items. Make sure that the
word isn't marked as Hidden.
10. Select IDH_FILE_MENU with your mouse. In the Font dialog, select Hidden. (Hidden
format doesn't hide the text onscreen.) Repeat this step for the IDH_HELP_MENU text on
the next line.
11. Place the text cursor at the beginning of the following line of text located in the next
page.
This is the page where you will place the contents of
the Help file for the File Menu Items.
Choose Footnote from the Insert menu.
15. In the Footnote and Endnote dialog, select Custom Mark and enter # in the text box.
Click OK. The footnote section of the Word document appears.
16. Enter IDH_FILE_MENU next the # character in the footnote section.
17. Do the same for the other text.
18. Save the document as an RTF file, helper.rtf (select Rich Text Format from the Save
as Type drop-down list of the Save As dialog).

Compiling an RTF file into an .hlp file

1. Launch the Help Workshop by choosing Microsoft Help Workshop from the Programs
submenu of the Start menu, or by finding and double-clicking HCW.EXE in Windows
Explorer.
2. Choose New from the File menu.
3. In the New dialog, select New Help Project. Save the new project as helper.hpj
4. Click File on the right side of the Workshop to access the Topic File dialog. Click Add to
display the Open File dialog.
5. Select the helper.rtf and click OK to add it to the Help Workshop
6. To compile the .RTF file into an .HLP file, click Save and Compile at the bottom right of
the Help Workshop.
7. You can view the finished help project file by going into the location where you save it
and double-clicking the helper.hpj

ADDING THE HELP FILE TO YOUR VISUAL BASIC APPLICATION

To display a Help File to your Visual Basic Application, 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 means:

• hwnd—Handle of the window opening the Help file

• lpHelpFile—Name of the Help file to open
Information and Communication Technology Department 79
Palompon Institute of Technology
 USING MICROSOFT HELP WORKSHOP
10
• 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.
Information and Communication Technology Department 80
Palompon Institute of Technology