How-To... - Add a Help system to your program - Part 1

Imagine a program without any help file or any documentation to show you how to use the program. Think how much you use the VB help file when you are programming. A help system is an excellent addition to any program, making it more user-friendly. It shows how to use the program and gives help on any part of the program.

This part of the How-To will show you how to make a Windows Help file and implement it into your program.

Requirements

Visual Basic(version 3 updwards)
A text editor which can save as RTF and can handle Double-Underlines, hidden text, and footnotes. MS Word and Lotus Word Pro can handle it. Sadly, WordPad can't
A help compiler - VB 4 has a Dos Compiler in the HC folder. I think the VB5 and VB6 has a 32-bit compiler in a folder(Tools I think)

Creating the RTF file

Ok, load up your RTF editor. First show all non-printing characters(looks like a backwards P in MSWord). The first page is going to be the main page of the Help File, where you can select which section you wish to go. Add some text for a title and some text to describe the help file(like below)

Now comes the tricky part - making the clickable links. In a new line under the text you just typed, type in About This Program. Select the whole sentence and change it to double-underline - in Word it should be in Format/Font. Now, click at the end of this line and type in About. This time make it hidden, which can be achieved through the Font box. It should now look something like this -

Make sure you do not make the character(backwards P) hidden or you will get an error when compiling. Also, when you go onto a new line after the Hidden or Double-Underline text, make sure that these are turned off.

Next, insert a page break - on a new line, press CTRL+ENTER to create a 'hard' page break. Now before you type anything in, you have to tell the compiler that you want this page to be shown when the user clicks on the link. This requires the use of Footnotes.

On the first line of this new page, click the Insert menu and click Footnote... A window similar to this will be shown. Make sure Footnote is checked, and in the box that says Custom Mark, type # and click OK. When you are back at the RTF file, you will be at the bottom of the page next to the symbol you entered. This is the Footnote section.(See table below for details on each symbol)

Here you will type the same as the Hidden text - so that will be About - make sure it doesn't have any formatting on it. Scroll back up to the top and at the end of the first line, insert another

footnote, this time with a symbol of $ - at the bottom of the page, type in About this program. Finally, back to the first line of the page and insert one last symbol - K - at the bottom of the page, type in About. Here is a description of each symbol :-

Symbol	Description
#	Connects a link to a page determing on the tag(in the example, the tag is About)
$	The tag given appears in the Helps Search box.
K	The tag is used for keywords which the user uses to search for a topic

Now, once all footnotes have been entered, scroll up to the top of the page and select the end of the first line. Press Enter and start editing this page by giving it a title and some text to describe the program. Finally save the file as an RTF file, giving it a filename less than 8 characters. Your finished RTF file should look something like this:-

Compiling the help file

To compile the help file, you need to create a Help Project file(HPJ). To make one of these, open up notepad and enter the details opposite, and change each line to suit your needs. Below is a table which describes each line.

Line	Description
errorlog	This is created incase an error or warning occurs when compiling the help file.
title	The title of the Help File
compress	How much compression you want for the Help file - 3 is about average.
Line underneath [FILES]	The location of the RTF file to compile.

Save this as a .hpj file and save it into the directory of the help compiler. For the Dos version:-

Click Run on the start menu and type command followed by ENTER. Make sure that the directory is the Help compiler directory. Type HC nameofhpjfile where nameofhpjfile is the name of the HPJ file you made. I would type HC vbhowto.hpj followed by ENTER. Any warnings or errors that are given will be saved to the error log. Not all warnings need to be fixed, but all errors do. Once it has compiled, a help file will be created. Double click it to open it. It should look something like this:-

Click on the link and it should take you to the second page. Well done you have just created a help file.

Compiling with the 32-bit version

Double-click the HPJ file or open it through the 32-bit compiler and click Save and Compile. Well done, you have created a help file. NOTE - the 32-bit version has much more options for making your help files look and act better. Experiment with it to see what you can do.

Adding it to your program

Finally, you can now add it to your program. Move the compiled help file into the folder with your program. Open up your program in Visual Basic. If you haven't got a module, insert one, and enter the following code into it:-

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

Public Const HELP_COMMAND = &H102&
Public Const HELP_CONTENTS = &H3&
Public Const HELP_CONTEXT = &H1 ' Display topic in ulTopic
Public Const HELP_CONTEXTPOPUP = &H8&
Public Const HELP_FORCEFILE = &H9&
Public Const HELP_HELPONHELP = &H4 ' Display help on using help
Public Const HELP_INDEX = &H3 ' Display index
Public Const HELP_KEY = &H101 ' Display topic for keyword in offabData
Public Const HELP_MULTIKEY = &H201&
Public Const HELP_PARTIALKEY = &H105&
Public Const HELP_QUIT = &H2 ' Terminate help
Public Const HELP_SETCONTENTS = &H5&
Public Const HELP_SETWINPOS = &H203&
Public Const HELP_SETINDEX = &H5 ' Set current Index for multi index help

Now insert a help menu onto your form or stick a button. In the _Click event for the object, insert the following code:-

'Change "\Cycler.hlp" to the name of your help file...
rv = WinHelp(Me.hWnd, App.Path & "\Cycler.hlp", HELP_INDEX, CLng(0))

App.path just means the same directory as the program. One more thing, add the following code to the Forms Unload procedure. This is so that the help file isn't left open when the program closes.

retval = WinHelp(hWnd, dummy$, HELP_QUIT, 0)

Run your program and click the Help button or menu, and your help file will open. There you have it, your program is now even more user-friendly.

Finishing Up

Here you have the instructions on making a help file - if I haven't explained anything enough, please e-mail me or post a message on the forum. You can download the compiled Help file, HPJ file and the RTF file by click here.

Part 2 will show you how to make a program overview which will add more user-friendliness to your program - and its a lot easier than making a Help file :-)

---