Day 21

Preparing Online Help for Your Database Application

Today you will learn how to build help applications for your Visual Basic database application. You will create help files in a standard word processor and attach them to your application. You will then see an application that can facilitate much of the work encountered in the creation of a help file.

To perform the exercises in this chapter, you need a word processor that can save your data files in rich text format (RTF). You also need the help compiler HC.EXE. This file installs with Visual Basic 4 and can be found in the VB4 HC subdirectory. This file can also be downloaded from the Microsoft FTP site or from Microsoft forums on Compuserve, or America Online

An Overview of Developing a Help System for Your Application

Including online help with your Visual Basic database application is important for several reasons. First, online help makes your application look "finished." The user will gain greater confidence in your application if there is an online resource that he or she can turn to for assistance.

Second, online help makes a system easier to use. Users don't have to search for printed manuals for answers to their questions. Researching information online is faster and easier than leafing through printed manuals. The user doesn't have to leaf through a table of contents or an index to get the appropriate answer. Instead, the user can use the search feature of the online help.

Third, online help can be customized. For instance, users can enter their own comments using the Annotation function. This helps to inform others of policy decisions and system uses. It also helps in the use of the system across different functional areas.

You should also understand the drawbacks of using online help. Many users have not accepted the paradigm of searching for information online. Some users like to take manuals home with them on the weekend. Others like to write important notes in the margins of their manuals. Others find it a strain on their eyes to read long descriptions of information on-screen. Also, if the online help is poorly designed, users can get trapped in endless loops and not find the information they expect.

Overall, the benefits of attaching an online help file to your application far outweigh the drawbacks. Help of any sort, even if it is the name and phone number of the program developer, should be included with any application you develop.

Steps in Creating a Help File

You should follow these steps in order to build a help file for your application. (This chapter will focus on each step in detail.)

  1. Write a topic file. This is the word processing document that contains the text and codes of the help file.
  2. Save the topic file in rich text format.
  3. Create a project file to tell the help compiler how to build the help file.
  4. Compile your project using HC.EXE
  5. Attach help to your Visual Basic application.
  6. Test and revise as needed.

Creating Topic Files

The first step in creating your online documentation is to create a topic file. The topic file contains the text that the user sees when he or she presses F1 in your application. This file also contains codes in the form of footnotes that the WinHelp program uses to determine how the system is to function.

Word 6.0 is used in this chapter's examples to create the topic file. If you are not using Word, make sure your word processor supports the following:

Before starting, make sure that your default system options are set so that you can view hidden text. In Word, select Options from the Tools menu. Next, select the View tab. Then, under Non-Printing Characters, check the Hidden Text checkbox.

You might also want to select the Print Tab and then check the Hidden Text checkbox in the Include with Document section. This will allow you to print any hidden text codes entered into your document.

As with good programming, it is important that you design your help file before you build it. The following exercises will cover the design of the help file at the end. You will be much better at designing the help file after you have learned how it is built. Now let's build the topic file.

Writing the Text

To start the project today, begin by building a text file that contains the information the user will read when help is requested. You will build a file to attach to the Company Master application you started in Day 6.

Let's keep the text file short and enter only information for the three sections of the application: Company Information, Contact Information, and Other Information. Although you will enter a small amount of information, it will provide you with the skills you need to build help files of any size.

You should now enter the text shown in Figure 21.1 in your word processor. You can find this text in the TOPICS.DOC file found in the \TYSDBVB\CHAP21 directory on the CD that ships with this book. You could also import the TOPICS.RTF file if you are using a wordprocessor other than Word.

Figure 21.1

The text for your sample help file.

Separate Topics with Hard Page Breaks

Each topic in your text file must be separated with a hard page break. In Word, you enter hard page breaks by pressing Ctrl+Enter. Now do this between each topic. Your file should look like the one shown in Figure 21.2.

Figure 21.2

The text file with page breaks between the topics.

Now that the text entry is complete, you can start entering the format codes. These codes will inform the help compiler what to do with this text.

Entering the Context String

The context string is the unique identifier for a topic and serves as the unique key for the help system. Users will not see this code; it is only used by the WinHelp program for ordering the topics.

You need to insert a footnote to designate a context string for a topic. The footnote is marked with a pound sign (#). To insert a footnote, follow these steps:

  1. Move the cursor in front of the title for the topic but after the page break for the previous topic. For the first topic in the exercise, place the cursor to the left of the C in the first topic heading, Company Information.
  2. Select Footnote from the Insert menu. The Footnote/Endnote dialog box will appear. (See Figure 21.3.)

    Figure 21.3

    The Footnote/Endnote dialog box, used for entering a custom footnote mark for a context string.

  3. Select the Footnote checkbox (if not already checked) in the dialog that appears.
  4. In the Numbering section of the Footnote dialog box, click the Custom Mark button and enter #.
  5. Select OK.

The footnote section of Word now appears. Type the context string CompanyInformation. Make sure not to have more than one space between the # and the context string. Your screen should now look like the one shown in Figure 21.4.

Figure 21.4

Entering the context string.

When building the context string, it is important not to leave any spaces in your text. Entering Company Information (with a space) results in a compile error. It is also good practice to match the context string as closely as possible to the heading you place on each topic. This will prevent confusion when dealing with a large number of context strings.

The context string is the only required footnote for each topic. The following sections discuss optional help file footnotes that you should also include with each topic.

Entering the Title

Now that you have entered the context string for the first topic, it is time to enter the title footnote. The title is displayed as the topic in the Help Topics dialog Find tabbed dialog box of the help system. (See Figure 21.5.) It's a good practice to use the topic heading from the topics file as the title of the text for this footnote.

Figure 21.5

The Windows 95 Help Topics Find tabbed dialog box.

Entering the title is similar to entering the context string. However, the title footnote can include spaces between the words and is designated by the dollar sign ($) custom footnote mark rather than the pound sign (#).

Follow these steps in order to insert a title for the Company Information topic:

  1. Move your cursor to the left of the letter C in Company Information. Footnotes can appear in any order, just as long as they are located before the topic heading and after the page break for the previous topic.
  2. Select Insert | Footnote.
  3. Click the Footnote button.
  4. Click the Custom Mark button and then enter the dollar sign ($) as the custom mark. Click OK.
  5. Type the title Company Information.

You can find help topics in the Help Topics dialog box by typing a keyword for a topic and then clicking the Display button. Determining which keywords apply to a specific topic is the focus of the next lesson.

Entering Keywords

Keywords are used in the WinHelp Help Topics Find tab to find topics. You use the same techniques for entering keyword footnotes as you did for entering context strings and titles. However, there are two differences: You can have multiple keywords for each topic (each keyword separated by a semicolons), and you use the uppercase letter K as the custom footnote mark for the topic.

Follow these steps in order to define a keyword for the first topic:

  1. Insert the cursor before the letter C in Company Information and after the $ title footnote marker.
  2. Select Footnote from the Insert menu
  3. Select the Footnote option.
  4. Select Custom Mark and enter an uppercase K.
  5. Select OK and then enter the keyword Company in the footnote.

NOTE:

It is possible to enter keywords for a topic and not a title. This will result in an >>Untitled Topic<< message appearing in the Topics section of the Help Topics Find tab. To avoid this, always include a title if you use a keyword.


Entering the Browse Sequence

The last code to enter is the browse sequence. The browse sequence defines the order in which you can move through help screens by pressing the forward (>>) and reverse (<<) buttons at the top of your help screen. This footnote is defined by the plus sign (+), and it uses the following syntax:





           group name:sequence

In this line, the group name is followed by a colon and then by the order in which the topic appears in the group. The group allows you to connect all related topics in the help file so that users can move forward and backward in order to review any related information. The sequence is the position of the topic within the group.

For this exercise, let's add a browse sequence for CompanyInformation.

  1. Insert the cursor before the C in Company Information and after the K footnote mark.
  2. Select Footnote from the Insert menu.
  3. Check the Footnote option.
  4. Select the Custom Mark option and enter a plus sign (+). Press OK.
  5. Enter Company:1 as the footnote. Make sure not to leave more than one space between the footnote mark and the C.

You have entered all the necessary footnotes for the first topic. Your screen should now look like the one shown in Figure 21.6.

Figure 21.6

All the footnotes for the Company Information topic.

Continue this exercise by entering the footnotes for the other two topics in your file. Use Table 21.1 as a guide.

Table 21.1. Footnote information for The Contact Information and Other Information topics.

Topic Footnote Type Code
Contact Information Context string
Title
Keyword
Browse sequence
#
$
K
ContactInformation
Contact Information
Contact+ Company:2
Other Information Context string
Title
Keyword
Browse Sequence
#
$
K
+
OtherInformation
Other Information
Other
Other:1

Saving the File

You should now save all of the information that you have entered into your topic file. First, save the information as a Word 6 document. To do this, simply select Save from the File menu. Save your information as TOPICS.DOC.

Now save the file as an RTF file. Do this by selecting Save As from the File menu. Open the Save File As Type combo box and select Rich Text Format. Enter TOPICS.RTF in the File Name box. Then, execute the save by selecting OK.

Tracking the Topic Files

When creating large help files, keeping track of the different footnotes can become quite cumbersome. For instance, all the context strings must be unique and the browse sequence must follow an order within each group. For just three topics, this is not a hard task. But for 50, 100, or 1000 topics, this task becomes much more difficult.

Therefore, it's recommended that you keep track of all the footnotes you enter for each topic in a spreadsheet. This will help you in establishing the browse sequence and will ensure that each context string is unique. For each topic, keep the heading from the topics file as well as details on each footnote that you enter.

A sample tracking file is shipped with Visual Basic. The file is in Word 6.0 format and is named ..\VB4\HC\TRACK.DOC. (Refer to Figure 21.7.)

Figure 21.7

TRACK.DOC, a sample help tracking tool.

A tracking file will also help you build the project file, which is the subject of the next lesson.

Creating the Project File

When you have entered your help text in a document, inserted the appropriate footnotes, and saved the document as an RTF file, you are ready to build the project file. The project file tells the help compiler how to create a help file (.HLP) from the topic file (the RTF).

The project file is very similar to an INI file. Enter information in sections which each have a heading enclosed in square brackets ([ ]). These files can be created in a text editor and must be saved as unformatted ASCII text. Now open the Notepad accessory in Windows to create the project file.

Enter the following text to create the project file. Save your file into the same directory as your TOPICS.RTF file and name it 21ABC.HPJ.





; Project file for the Company Master Help



;



[Options]



Title=My Help File  ;Title to Appear on the Help Title Bar



ErrorLog = Error.TXT  ;File to store compile errors



[Files]



Topics.RTF  ;Name of the file containing the topics



[Config]



BrowseButtons()  ;Macro to place browse buttons on the help screens



[Map]; section to define context string parameters



CompanyInformation                            1



ContactInformation                            2



OtherInformation                              3

Components of the Project File

The first section of the project file is the Options section. This section, if used, should always be the first section of the topic file. Although it is not required that you use this section, it is highly recommended. This is where you identify the title that appears on your help title bar as well as the name of the file that will be used to collect compilation errors.

Here is the syntax to follow when entering an [Options] section:





[Options]



Title=My Help File  ;Title to Appear on the Help Title Bar



ErrorLog = Error.TXT  ;File to store compile errors

The second section is the Titles section. This section is required in all project files. It contains the name of the topic file (the TOPICS.RTF file in our exercise) from which the help file will be created. You entered only one line in this section:





[Files]



Topics.RTF  ;Name of the file containing the topics

The third section is the [Config] section. This section lets you declare macros to be executed when your finished help file is compiled. In the [Config] section you have entered a macro name that will place browse buttons at the top of the help screen to aid us in moving through the defined browse sequences. For this section, enter the following:





[Config]



BrowseButtons()  ;Macro to place browse buttons on the help screens

The final section you we'll include in the exercise is the [Map] section. In this section, you enter numeric references to the context strings that you entered into the RTF file. Be very careful when building this section. Your context strings must be identical to the context strings entered in the RTF file. Enter the followig:





[Map]; section to define context string parameters



CompanyInformation                           1



ContactInformation                           2



OtherInformation                             3

There are several other sections you can place in your project file. The [Buildtags] section, for instance, allows you to designate the topics in the RTF file that are to be compiled. There is also a [Windows] section where you can set parameters for the sizing, background colors, and locations of your help file.

You can also place an [Alias] section in your project file. Aliases allow you to assign multiple context strings to the same topic. This is useful when you delete topics in your RTF file. See the VB 4 Books Online, The Microsoft Help Compiler Guide, for a complete discussion on each of these sections.

Now that you have created your project file, it is time to compile your help application.

Compiling Your Help Project

Compiling your help file can't be done from within the Windows environment. Shell out to the DOS prompt or close Windows and return to DOS to begin this lesson. Go to the directory in which you saved the files TOPICS.RTF and 21ABC.HPJ. You should copy the help compiler, HC.EXE, to this directory. A copy of this file can be obtained from CompuServe or the Microsoft FTP if you do not have it.

At the DOS prompt, type the following command line to compile your help file:





HCP 21ABC.HPJ.

The program will compile and create a file with the same name as your project file, with an .HLP extension.

You will be prompted for any compilation errors that are written to the error file ERROR.LOG. Review any error messages you receive and then edit the project and topic file as needed. Then you can recompile your project.

Linking Help to Your Visual Basic Database Application

When the 21ABC.HLP file is created, it is ready to be attached to your Visual Basic database application. Before attaching it, however, let's first review the file. To do this, select Help from any Windows application by pressing F1. From the File menu, select Open, and then select the file 21ABC.HLP. The first topic, Company Information, should now appear.

You will now attach the help file to the Company Master application. First, you attach help information by setting properties. After that, you use code to assign help definitions. When you have completed that, you add menu applications to the application that automatically bring up the Contents, Search, Help on Help, and About Help information.

Using Properties to Attach Help Information

  1. Follow these steps to attach a help file to your project:
  2. Select Project from the Visual Basic 4 Tools menu. Then select the Project tab.
  3. Select Help File and then enter the name of the help file (21ABC.HLP), including its path. You can also click on the ... box at the right of the field to Search for the file.
  4. Select OK.

This assigns the help file to the project. You now need to assign the help context ID to the controls on the Company Master form. Follow these steps to make the attachments:

  1. Open the CompanyMaster project
  2. Select and open the CompanyMaster form.
  3. Select the txtCompanyName control.
  4. Press F4 and move to the HelpContextID property.
  5. Enter 1.

The entry in the HelpContextID property refers to the value you set in the project file (21ABC.HPJ) for the context string.

Save your form and run the project. Click in the Company Name field and press F1. You should now see the help you wrote for the Company Information topic.

Now exit help and return back to form design mode. Assign the remaining input fields within the Company Information frame to HelpContextID 1. Assign 2 to the HelpContextID property for all the fields in the Contact Information frame, and assign 3 to all the input fields in the Other Information frame.

Run the project and select any field on the form. Press F1 to bring up help. Select the Search box and then the Find tab.. Notice that the keywords appear in the middle box and the titles appear in the lower box.

You can use the >> button in the Company Information topic to move to the Contact Information topic. This happens as a result of setting the browse sequence for both topics to the same group. Notice that Company Information comes first within this browse sequence. This is due to the browse sequence of Company:1 for the Company Information topic and Company:2 for the Contact Information topic.

While in help, select the Contents button. Company information should now be displayed. The Contents button will display the first topic in your help file if you do not declare a contents topic in your project file. Declaring this topic and building a contents page is the subject of the next lesson.

Building the Contents Page, Adding Jumps, and Modifying the Project File

To build the contents page, you will need to build a topic, assign footnotes, create jumps to the underlying topics, and modify the project file. When you have done this, you will then need to recompile the project.

Reopen your topics file (21ABC.DOC) and enter the following information for the contents page. Make sure that you insert a page break between the Other Information topic and your new topic.





Table of Contents



This is the page we will use for our Table of Contents. 



Select the topic you would like to view.



Company Information



Contact Information



Other Information

You will now add a jump to each of the three sections in the contents page. To do this, follow these steps:

  1. Use your mouse to select Company Information in the Table of Contents topic.
  2. Double underline this text. In Word, this can be done by selecting Format | Font and then selecting Double from the Underline combo box.
  3. Add the context string of the topic to which you would like to jump immediately after the double-underlined text (the context string itself should not be double underlined). For example, your first jump should appear as this:

    
    
    
    
           Company InformationCompanyInformation
  4. Assign the hidden text attribute to the context string you just added. This can be done by selecting CompanyInformation. Next, select Format | Fonts, and then check the Hidden Effect checkbox.
  5. Now double underline the other two jumps, and insert the context strings of the desired topics. For Contact Information, the context string is ContactInformation. For Other Information, the context string is OtherInformation. Make sure these context strings have the hidden text effect.

Use the following list to insert the footnotes for the Table of Contents topic:

Footnote Type Code Footnote Text
Context string # TableofContents
Title $ Table of Contents
Keyword K Contents;Table of Contents

Adding Pop-Ups

Let's add one more feature to your topic file—a pop-up. A pop-up is a box of text that displays on top of the active help topic. It is commonly used to provide term definitions without requiring the user to select a jump to a different topic. A jump should therefore be used to elaborate on the current topic, not to serve as a topic itself.

Figure 21.8

A pop-up.

Adding a pop-up to your help topic is the same as adding a jump, except that you use a single underline for the pop-up text rather than the double underline used for the jump text. Follow these steps to add a jump:

  1. Create a new topic for your pop-up text. In this exercise, you will enter the definition of "Contact Person" in the Contact Information topic. Enter the following text and footnotes for this topic:

    
    
    
    
    Contact Person
    
    
    
    The person to whom we send monthly statements.

    Footnote Type Code Footnote Text
    Context string # ContactPerson
    Title $ Contact Person
    Keyword K Contact

  2. Single underline Contact Person in the Contact Information topic.
  3. Insert the context string ContactPerson immediately after the single-underlined text Contact Person.

    
    
    
    
            Contact PersonContactPerson
  4. Assign the hidden text effect to the ContactPerson context string added in the previous step.

Figure 21.9

Adding a pop-up.

You have now completed the revisions to the topic document. Save this document in RTF format. Also, save the document a second time in your word processor's normal format.

Changing the Project File

You now need to make some changes to the project file. Remember that you created this file earlier in the NotePad application and gave it the name 21ABC.HPJ. Bring up Notepad and open this file. This file should look like the one shown in Figure 21.10.

Figure 21.10

21ABC.HPJ, the Project file.

You first need to edit the [Options] section to identify the topic you want to use as your contents topic. Modify this section so that it looks like this:





[Options]



Title=My Help File  ;Title to Appear on the Help Title Bar



ErrorLog = Error.TXT  ;File to store compile errors



Contents = TableofContents

TableofContents is the context string you assigned in the earlier exercise.

You also need to modify the [Map] section for the new topics you added. Change this section of 21ABC.HPJ so that it looks like the following:





[Map]; section to define context string parameters



CompanyInformation                           1



ContactInformation                           2



OtherInformation                             3



TableofContents                              4



ContactPerson                                5

You will not add a context string for the pop-up because you will not reference it from a Visual Basic control.

Save your changes to this file, exit to the DOS prompt, and then compile your help file (command line of HC 21ABC.HPJ).

When the file is successfully compiled, return to Visual Basic and run the Company Master application. Select a control in the Contact Information frame and press F1. Select the underlined phrase Contact Person. Your definition now appears (see Figure 21.11.)

Figure 21.11

A pop-up definition.

Next, select the Contents button to display the Table of Contents topic. Select any of the underlined items to jump to their topic. When you're in the topic, select the Back, History, or Contents button and return to the original screen.

Using Code to Set the Help File Project Option and the HelpContextID Property

In the previous exercise, you attached the help file name by entering it in the Project Options section and setting the HelpContextID in each control's properties. You can also set these values at runtime. Just enter the following code in the Form_Load procedure to open the help file and set help context IDs:





Sub Form_Load ()



   App.HelpFile = "C:\TYSDBVB\CHAP21\21ABC.HLP"



   txtName.HelpContextID = 1



End

You need to set a HelpContextID for each control to which you want to add help. This can be a very time-consuming chore if you have a large number of controls or a large number of forms in your Visual Basic database application.

Adding Help Functions to Menus

You will see Contents, Search, Help on Help, and About menu items on the Help menu of most Windows applications. The purpose of this exercise is to show you how to add these items to your Visual Basic database application.

Start by opening a new project and building the following menu by choosing Menu Designer from Visual Basic's Windows menu:

Menu Item Name
&File mnuFile
—E&xit mnuExit
&Help mnuHelp
—&Contents mnuContents
—&Search mnuSearch
—Help&onHelp mnuHelponHelp
—— mnuSep1
—&About mnuAbout

Save this form as HELPMENU.FRM and the project as HELPMENU.VBP.


NOTE:

The code in this example can either be entered manually or taken from the CD that ships with this book.


Now enter the following code in the Form_Load procedure of your HELPMENU.FRM file:





Sub Form_Load ()



   App.HelpFile = "C:\TYSDBVB\CHAP21\21ABC.HLP" 'Define the Help File to Use



End Sub

The line App.HelpFile = "C:\TYSDBVB\CHAP21\21abc.hlp defines the help file for the project.

Next, create a new module by selecting Module from the Insert menu, name it PRCHELP.BAS, and insert the following code inside the general declaration section:





Option Explicit



#If Win16 Then



    Declare Function WinHelp Lib "User" (ByVal hwnd As Integer,



 ByVal lpHelpFile As String, ByVal wCommand As Integer,



 ByVal dwData As Any) As Integer



    Declare Sub ShellAbout Lib "shell.dll" (ByVal hWindOwner As Integer,



 ByVal lpszAppName As String, ByVal lpszMoreInfo As String,



 ByVal hIcon As Integer)



 



#Else



   Declare Function WinHelp Lib "user32" Alias "WinHelpA" (ByVal hwnd As Long,



 ByVal lpHelpFile As String, ByVal wCommand As Long,



 ByVal dwData As Any) As Long



   Declare Function ShellAbout Lib "shell32.dll" Alias "ShellAboutA"



 (ByVal hwnd As Long,



 ByVal szApp As String, ByVal szOtherStuff As String,



 ByVal hIcon As Long) As Long



    



#End If



Global Const HELP_QUIT = 2



Global Const HELP_INDEX = 3



Global Const HELP_HELPONHELP = 4



Global Const HELP_PARTIALKEY = &H105

Insert a new procedure by selecting Procedure from the Insert menu, name it HelpFile and insert the following code:





Sub HelpFile (frmForm As Form, nHelpCmd As Integer)



   Dim i As Integer



   Dim nFlag As Integer



   Dim aData As Variant



   '



'Test for the naming of a help file



   If Len(LTrim(RTrim(App.HelpFile))) = 0 Then



      MsgBox "No Help File Available"



      GoTo HelpFile_Exit



   End If



'Set a text flag



   Select Case nHelpCmd



      Case Is = HELP_QUIT



         nFlag = True



      Case Is = HELP_INDEX



         nFlag = True



      Case Is = HELP_HELPONHELP



         nFlag = True



      Case Is = HELP_PARTIALKEY



         nFlag = True



      Case Else



         nFlag = False 'invalid command!



   End Select



'Pass parameters to the DLL call



   If nFlag = True Then



      If nHelpCmd = HELP_PARTIALKEY Then



         i = WinHelp(frmForm.hWnd, App.HelpFile, nHelpCmd, "")



      Else



         i = WinHelp(frmForm.hWnd, App.HelpFile, nHelpCmd, 0&)



      End If



   Else



      MsgBox "Invalid Help Command Value"



   End If



   '



HelpFile_Exit:



End Sub

Adding the About Box to Your Application

Create a new procedure by selecting Insert | Procedure entering the following code:





Sub WinAboutPage (frm As Form)



   Dim MoreInfo$



   '



   MoreInfo$ = "Copyright " + Chr$(169) + " 1994 Software Company, Inc."



   MoreInfo$ = MoreInfo$ + Chr$(13) + "Technical Support: 800-555-7777"



   '



   Call ShellAbout(frm.hWnd, app.Title, MoreInfo$, frm.Icon)



End Sub

Entering Code in the Menu Events

First, enter the following code in the mnuContents_Click event:





Sub mnuContents_Click ()



   Helpfile Me, Help_index



End Sub

Second, enter the following code in the mnuSearch_Click event:





Sub mnuSearch_Click ()



   HelpFile Me, Help_PartialKey



End Sub

Third, enter the following code in the mnuHelponHelp_Click event:





Sub mnuHelponHelp_Click ()



HelpFile Me, Help_HelponHelp



End Sub

Fourth, enter the following code in the mnuAbout_Click event:





Sub mnuAbout_Click ()



    WinAboutPage Me



End Sub

Fifth, enter the following code inside the mnuExit_Click event:





Sub mnuExit_Click()



   Unload Me



End Sub

And finally, enter the following code inside the Unload event for your form:





Sub Form_Unload (Cancel As Integer)



   HelpFile Me, Help_Quit



End Sub

Save your form and your project. Run the project and select each of the menu items. Notice that Help | Contents displays the Contents page of the help file you created earlier today and declared in the Form_Load event. Selecting Help | Search displays a listing of topics from the same help file. The menu selection Help | Help on Help displays a screen similar to Figure 21.12 which shows the Win 95 help topics. Selecting Help | About displays a dialog similar to Figure 21.13 which contains information about your program. Finally, selecting Exit from the File menu stops the execution of the program.

Figure 21.12

Help on Help.

Figure 21.13

The About box.

How This Program Works

You first began this project by entering code in the general declaration section for two API calls. The first call was made to the Windows help system to display the Help on Help, Search, and Contents information.The second call is solely for the About box:





#If Win16 Then



    Declare Function WinHelp Lib "User" (ByVal hwnd As Integer,



 ByVal lpHelpFile As String, ByVal wCommand As Integer,



 ByVal dwData As Any) As Integer



    Declare Sub ShellAbout Lib "shell.dll" (ByVal hWindOwner As Integer,



 ByVal lpszAppName As String, ByVal lpszMoreInfo As String,



 ByVal hIcon As Integer)



 



#Else



   Declare Function WinHelp Lib "user32" Alias "WinHelpA" (ByVal hwnd As Long,



 ByVal lpHelpFile As String, ByVal wCommand As Long,



 ByVal dwData As Any) As Long



   Declare Function ShellAbout Lib "shell32.dll"



 Alias "ShellAboutA" (ByVal hwnd As Long,



 ByVal szApp As String, ByVal szOtherStuff As String,



 ByVal hIcon As Long) As Long



    



#End If

Notice that you used the compilation directive (#if) to insert the code so this application will run under the 16-bit version of Visual Basic 4. You then used the #Else directive to insert the 32-bit version. By doing this, the application will run under either version of Visual Basic 4 (16- or 32-bit).

The final entries into the general declaration section are to define the constants that will be called by the Help menu items:





Global Const HELP_QUIT = 2



Global Const HELP_INDEX = 3



Global Const HELP_HELPONHELP = 4



Global Const HELP_PARTIALKEY = &H105

The HelpFile procedure performs the following tasks:

The WinAboutPage procedure makes an API call to display an About box. Parameters are passed for a company name and a technical support number:





Sub WinAboutPage (frm As Form)



   Dim MoreInfo$



   '



   MoreInfo$ = "Copyright " + Chr$(169) + " 1994 Software Company, Inc."



   MoreInfo$ = MoreInfo$ + Chr$(13) + "Technical Support: 800-555-7777"



   '



   Call ShellAbout(frm.hWnd, app.Title, MoreInfo$, frm.Icon)



End Sub

The Click events for the menu items are defined to call the HelpFile procedure and pass the appropriate parameters:





Sub mnuContents_Click ()



   Helpfile Me, Help_index



End Sub



Sub mnuSearch_Click ()



   HelpFile Me, Help_PartialKey



End Sub



Sub mnuHelponHelp_Click ()



HelpFile Me, Help_HelponHelp



End Sub



Sub mnuAbout_Click ()



    WinAboutPage Me



End Sub



Sub mnuExit.Click()



   Unload Me



End Sub

Finally, when the form unloads, housekeeping should be performed and any help screens that have been left open should be closed. This is the role of the Form Unload event.





Sub Form_Unload (Cancel As Integer)



   HelpFile Me, Help_Quit



End Sub

Please note that Unload Me was used in the Exit menu item rather than End. Using the End command would stop execution of the program without triggering the Unload event.

Using Help Authoring Tools to Create Your Help File

There are commercial products available that will greatly reduce the time required for developing a help file. These products automate the process by which footnotes are entered, context strings are mapped, project files are built, and the help file is compiled. In addition, these programs can "strip" footnotes from your topic file so that you can use it for your printed documentation.

There is a tradeoff that you should be aware of when using an authoring tool. Any tool will undoubtedly make you more efficient in the creation of topic files; but if it takes you more time to install and learn the product than you save by using it, you are better off producing the file manually.

The ultimate determinant in whether or not to purchase a help authoring tool will be based upon the size of your projects. Simple one- or two-screen applications are probably best documented manually. More complex, multiscreen applications will best be documented with the assistance of a help authoring tool.

There are numerous authoring tools available. They range in price from approximately $100 to $500. Many of these products must be purchased directly from their authors. It is hard for us to recommend one specific help authoring tool over another because your own personal working habits dictate which tool is best for you and your project. Please consult the advertising found in the back of trade publications to obtain the distributors, pricing, and titles of the latest authoring tools.

In order to learn how these tools operate, you might preview an intriguing authoring tool available free of charge from Microsoft. It is called WHAT6.EXE. This file can be obtained from the Microsoft FTP, CompuServe, and America Online services. This tool is actually a Word 6.0 document template that contains a series of macros that assist in the building of topic files. It is unsupported by Microsoft, which means you have no one to turn to if you have a problem or a question. Weigh this factor very carefully before you decide to utilize this tool on a live project.

Designing Your Help System

Let's turn to the design of your help application. As demonstrated in the exercises for this chapter, your help topic file will contain the information that users will depend upon to operate your application. An effective help system must be designed properly to meet the users' needs.

Make sure you understand who will be using your system. For instance, you would design and write one type of help topic file for highly sophisticated users and another for novice users. Different levels of users have different technical needs and viewpoints concerning the use computers as productivity tools. Meet the expectations of your users, both technically and emotionally.

Always plan what you will include in your help system. Don't begin writing until you have given consideration to the detail you want to provide and the browse sequences you want the user to see. Plan your topics to be no more than a few pages long. The topics should also be more than a sentence or two in length. You will find it better to use one topic that is two pages long in order to describe every field on a report, rather writing many short topics in order to explain each control.

Keep the design of your help system simple. Also, be sure to use jumps judiciously: You don't want your users jumping through page after page of information. It is better to duplicate help information rather than have the user continually jumping from screen to screen in order to find the answer to a simple question.

Don't try to model your users' business practices when building the topic file. Your system should be designed to be versatile, allowing for changing environments. Your help system should follow the same thought processes. Don't dictate how the system should be used optimally, but rather show the users how to do what they need to do. You will be surprised by the clever ways in which a well-designed system can be used.

Don't burden the users of your system with the obvious. For example, don't tell the users to enter a phone number in a field with a label Phone Number and an input mask of (###) ###-####. Everyone knows that this means to enter a phone number. Not everyone will know, however, where this number is used throughout the system or on what reports it appears. Be informative and follow through to the end. Don't stop your explanation when only 75 percent of the process has been defined.

It is best to write your online documentation as you build your system. Help files should be read and reviewed for suitability as part of the testing cycle. Writing the topic file as you code will keep you from forgetting key features of your design. Functionality is best documented when it is fresh in your mind.

Remember to budget time in your system design plan to write your online documentation. Writing is hard work and requires patience, perseverance, and attention to detail. Allow time for numerous rewrites and edits. Many experienced technical writers estimate that it takes approximately one hour to type a page of text. Make estimates based upon this rate and then adjust it according to the speed at which you work. Double the result that you get to allow sufficient time if you run into any problems.

Do not release a programming project that has not been properly documented. It is a mistake to think that you can provide quality documentation at a future date if you can't provide it at the ship date. A help system will be needed most when users are new to the system and just beginning to learn it. Every day work demands can distract you from the "less important" and routine responsibilities of your job. Always remember that creating a new project is exciting, but writing about a new project is often quite tedious. Discipline on your part will be required in order to get the job done.

If you are managing a team of developers, allow them the time needed in order to develop documentation. There are no shortcuts in system development or documentation. Items that are not finished when they should have been always come back to haunt you to an even greater extent some time in the future.

Know your writing abilities and seek assistance when needed. Many system programmers find it difficult to write. Their expertise lies with system design and coding, not with writing. This is not a bad thing in itself, as long as you are honest with yourself and are not ashamed to seek out technical writers for assistance.

Determine whether you will have both written and online documentation. You should provide both forms of documentation. It is easier to write the online documentation first and then use it as the starting point for your printed documentation. The online documentation will follow the natural flow of the system.

Remember that users depend on your documentation to enable them to understand how to operate the systems that help them perform their jobs. You have a great responsibility to properly document your system and to make it easy to use and quick to learn.

Summary

Every application should have a Help file attached. A Help file ensures that the system is used as it was intended. It also gives the application a more "finished" look and feel.

The following key points were covered in this chapter:

  1. You need to create a topic file and a project file in order to build a help file.
  2. The topic file you create includes all the text and footnotes for the help system. It is written in rich text format (RTF).
  3. You insert footnotes to define each topic. Insert a # footnote to declare a context string, a $ footnote to denote a title, an uppercase K to denote a keyword, and a plus sign (+) to denote the browse sequence.
  4. The project file contains the codes that inform the compiler how to build the help file from the topics file. It is saved as ASCII text and must have an .HPJ extension.
  5. You declare your project's help file by setting its path and name in the Project Options section. You declare your topic for a control by setting its HelpContextID property.
  6. Jumps can be added to your help file by double underlining your jump text and immediately inserting the context string of the topic to which the user will jump. This context string is then formatted as hidden text.
  7. You can create a pop-up window the same way you create a jump; but you use single-underlined text rather than double-underlined text.
  8. You can add help menu items to your application by making an API call to WinHelp.
  9. There are several programs, known as authoring tools, that are available commercially. These programs can assist you in creating help files. The size of your application will dictate whether an authoring tool is worth the time and financial investment.
  10. Plan your help file before writing it. Remember to write your online help first. Also, prepare your documentation as you develop your application rather than after the project is completely coded. Always keep your system simple, while making sure that all the information the user expects to find in your documentation is indeed there.

Quiz

  1. What custom footnote mark do you insert for a context string? Can you put spaces in the text of this footnote?
  2. What custom footnote mark do you insert for a title? Can you use spaces in this footnote?
  3. Where will keywords be used in your help application? What separator do you use if you want to insert multiple keywords for a topic?
  4. In what format(s) should you save your topics file? In what format(s) should you save your project file?
  5. How do you declare a contents page in your help file?
  6. What control property do you set in order to identify the help topic to display when the control has focus and F1 is pressed? Where does this value come from?
  7. How much time should you budget to produce one typed page of documentation?

Exercises

  1. Build a browse sequence that makes a topic the third topic to appear in a group called Processing.
  2. Build a jump for the text Creating a New Project that opens a topic titled Creating a New Project with the context string NewProject.
  3. Build a pop-up rather than a jump for the topic discussed in Question 2.
  4. Add a topic to the help file created in this chapter to describe the Company Master form. Recompile your project and attach help to the form. (Hint: Make sure to modify the [Map] section of your project file for the context string.)