USING MICROSOFT HELP WORKSHOP

10

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 ItemsHelp 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.

6. Enter the following line of text, followed by a page break: Information and Communication Technology DepartmentPalompon Institute of Technology

78

Using Microsoft Help Workshop 4.0

USING MICROSOFT HELP WORKSHOP

10This 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.hpj4. 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 Workshop6. 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• wCommand—Open command; see the list that follows

Information and Communication Technology DepartmentPalompon Institute of Technology

79

USING MICROSOFT HELP WORKSHOP

10• 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 = &H1Const HELP_QUIT = &H2Const HELP_INDEX = &H3Const HELP_CONTENTS = &H3&Const HELP_HELPONHELP = &H4Const HELP_SETINDEX = &H5Const HELP_SETCONTENTS = &H5&Const HELP_CONTEXTPOPUP = &H8&Const HELP_FORCEFILE = &H9&Const HELP_KEY = &H101Const 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 thisway:

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 DepartmentPalompon Institute of Technology

80