Help with Help -- part 2

Helen Bradley shows you how to connect the Help file to the VB Daily Quotes program.

If you haven't completed the project from November 1998's issue, you'll still be able to follow the process of adding a help file to a VB project (from May and June 1998's issues) by following the instructions here and adapting them to your own program. You'll also find some tips for adding extra functionality to your Help files.

Test the connection by running your project from within Visual Basic using Run, Start (or press F5). When the application is running, press the F1 key and you'll be taken to the Help index for your help file (see Figure 2e).

Figure 1e: Using the Project Properties dialogue box you can connect your help file to your project.

Figure 2e: You can test the link between your application and your help file by running the application and pressing F1.

Step 1: Open your VB project and select View, Project Explorer to see the contents of your project. Double-click on the module file called modQuote.bas to open it.

Step 2: You'll need to add the API function declaration for WinHelp to your module to allow you to access the Windows help engine from within your project. The function declaration you need is in the box 'The API function declaration' and you'll need to type this in at the top of the module. Type it exactly as it is as one long statement -- don't break it across lines (see Figure 3e).

Alternatively, like all API function declarations, you can use your API Text Viewer to locate the function declaration so you can copy and paste it into your application -- see the instructions in the box 'Copying API function'.

Step 3: Open your help project file (quotes.hpj) and add these lines of text to the foot of the file and then save it again as a text file called quotes.hpj (see Figure 4e). You should ignore any lines which the compiler may have added to it.

[MAP]
IDH_MAIN 1
QuoteDef 2
AddQuotes 3
EditQuotes 4
NavigateQuotes 5
MainScreen 6
ManageQuotes 7

Step 4: Use Help Workshop to recompile your help file. What you have done in these last steps is to give all the Topic IDs in your help topic file a numeric reference in a process called 'mapping'. As long as each numeric reference is unique, you can use any numbers, sequential or not.

Step 5: Switch back to your VB Project and display the form called frmDisplayQuotes. In the form's properties list set the HelpContextID to 1. Repeat this for the form frmManageQuotes and set its HelpContextID to 7.

Step 6: Save your VB project and then run it so you can test the context sensitivity. From the Daily Quotes screen press F1 and notice how the main help screen appears this time instead of the Help Index. Close your help file, select the Quotes button and when you have the Manage quotes screen visible, press F1 again and notice that a different help topic is displayed.

You can link different help topics to different objects in your project -- not just to form objects. Simply set the HelpContextID property of any object to the number of the Topic ID that you want to display whenever that object has the focus and the user selects the F1 key.

Figure 3e: To make the Windows help engine accessible from your project you need to add the WinHelp API function declaration to your module.

Figure 4e: Adding a [MAP] option to your project file allows you to associate help topic IDs with numbers you can later use as Visual Basic property values.

To add 'What's This Help' to the Quotes project, you'll use some of the Topic IDs that were set up for use as pop-up windows.

Step 7: Select the form frmManageQuotes and in the form's properties list set these properties:

Property	Value
WhatsThisButton	True
WhatsThisHelp	True
BorderStyle	Fixed Dialog

Step 8: Select these buttons on the form called frmManageQuotes and set the WhatsThisHelpID property of each as detailed:

Button	WhatsThisHelpID property value
cmdBack	5
cmdNext	5
cmdNew	3
cmdEdit	4
cmdAdd (this button is under the cmdNew button)	3
txtQuote	3
txtAuthor	3

Step 9: Save and test the changes by running the program and selecting the Quotes button to display the Manage Quotes screen. Notice that there is a button with a question mark on it in the top-right of this form. Test the 'What's This Help' by selecting the question mark button and then click the mouse over one of the form elements to see more information about it.

The changes you made to the BorderStyle property of the form are required by Visual Basic for What's This Help to function. Either you must set the BorderStyle to Fixed Dialogue or you'll need to set the form's BorderStyle to Fixed Single or Sizeable, the MinButton and MaxButton properties to false and the ControlBox property to True.

Figure 5e: The API Text Viewer allows you to easily select API functions and copy their declarations to the Windows clipboard.

Figure 6e: By making some changes in the Compiler window before compiling your help file you can achieve a more 'Windows'-like look to your help screens.