|  | Click Here!

Search the site:
EXPERT SEARCH

| Programming Languages
| Databases
| Security
| Web Services
| Network Services
| Middleware
| Components
| Operating Systems
| User Interfaces
| Groupware & Collaboration
| Content Management
| Productivity Applications
| Hardware
| Fun & Games

EarthWeb sites
Crossnodes
Datamation
Developer.com
DICE
EarthWeb.com
EarthWeb Direct
ERP Hub
Gamelan
GoCertify.com
HTMLGoodies
Intranet Journal
IT Knowledge
IT Library
JavaGoodies
JARS
JavaScripts.com
open source IT
RoadCoders
Y2K Info

#

- Appendix B
  - Preparing Online Help for Your Database Application
    - An Overview of Developing a Help System for Your Application
    - Steps in Creating a Help File
    - Creating Topic Files
      - Writing the Text
        - Figure B.1.
      - Separate Topics with Hard Page Breaks
        - Figure B.2.
      - Entering the Context String
        - Figure B.3.
        - Figure B.4.
      - Entering the Title
        - Figure B.5.
      - Entering Keywords
      - Entering the Browse Sequence
        - Figure B.6.
      - Saving the File
    - Tracking the Topic Files
    - Creating the Project File
      - Components of the Project File
    - Compiling Your Help Project
      - Figure B.7.
    - Linking Help to Your Visual Basic Database Application
    - Using Properties to Attach Help Information
    - Building the Contents Page, Adding Jumps, and Modifying the Project File
      - Adding Pop-Ups
        - Figure B.8.
        - Figure B.9.
    - Changing the Project File
      - Figure B.10.
      - Figure B.11.
    - Using Code to Set the Help File Project Option and the HelpContextID Property
    - Adding Help Functions to Menus
      - Adding the About Box to Your Application
      - Entering Code in the Menu Events
        - Figure B.12.
        - Figure B.13.
      - How This Program Works
    - Using Help Authoring Tools to Create Your Help File
      - Designing Your Help System
    - Summary
    - Quiz
    - Exercises

## Appendix B

## Preparing Online Help for Your Database Application

Today you will learn how to build help applications for your Visual Basic 5 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 will need a word processor that can save your data files in rich text format (RTF). Microsoft Word is an example of such a program. You will also need the help compiler `HCW.EXE`. This file ships on the Visual Basic 5 CD. The setup file for this program can be found in the `\\TOOLS\HCW` directory on the CD. If you haven't done so, go to the `TOOLS\HCW` directory and install this application.

### 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 gains 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. Users don't have to leaf through a table of contents or an index to get the appropriate answer. Instead, users 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 lesson focuses 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 `HCW.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.

We used Microsoft Word 7 in the development of this lesson's examples to create the topic file. If you are not using Word, make sure your word processor supports the following capabilities:

- Saving text in rich text format

- Adding custom footnote markings

- Working with hidden text

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 allows 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 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 reads when help is requested. You will build a file to attach to the Company Master application you started in Week One.

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 enter a small amount of information, it provides you with the skills you need to build help files of any size.

You should now enter into your word processor the text shown in Figure B.1. You can find this text in the `TOPICS.DOC` file found in `the \TYSDBVB5\SOURCE\APPXB\HELP` directory on the CD that ships with this book. You could also import `TOPICS.RTF` into your word processing package if you are using a word processor other than Word.
Figure B.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 B.2.
Figure B.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 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 do 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 and Endnote dialog box appears. (See Figure B.3.)
  3. Select the Footnote radio button (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.

Figure B.3. The Microsoft Word Footnote and Endnote dialog box, used for entering a custom footnote mark for a context string.
The footnote section of Word now appears. Type the context string `CompanyInformation`. Be sure you have no more than one space between the # and the context string. Your screen should now look like the one shown in Figure B.4.
Figure B.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 a good practice to match the context string as closely as possible to the heading you place on each topic. This prevents 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 Find tabbed dialog box of the help system. (See Figure B.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 B.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 section.

#### 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 semicolon), 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 results 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 Company Information.

  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 to leave no 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 B.6.
Figure B.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 B.1 as a guide.
Table B.1. Footnote information for the contact information
and other information topics.

Topic | Footnote Type | Code | Footnote Text
Contact Information | Context string | # | ContactInformation
| Title | $ | Contact Information
| Keyword | K | Contact
| Browse sequence | + | Company:2
Other Information | Context string | # | OtherInformation
| Title | $ | Other Information
| Keyword | K | Other
| Browse Sequence | + | 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, 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 Save.

### 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 helps you in establishing the browse sequence and ensures 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 tracking file also helps you build the project file, which is the subject of the next section.

### 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 `PROJECT.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 is 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 this exercise) from which the help file is 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 places browse buttons at the top of the help screen to aid you 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 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 following:

    [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 5 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

You should now start the Microsoft Help Workshop application to compile your project. Please note that you have to install this application from the Visual Basic 5 CD if you have not already done so. The `SETUP.EXE` file for the Help Workshop can be found in the `\\TOOLS\HCW` directory of the Visual Basic 5 CD.

Once you start the Help Workshop, select File | Open... and find the `PROJECT.HPJ` file you created in the preceding exercise. Enter the name of `PROJECT.HLP` in the Help File box at the top of the screen. Your screen should look similar to Figure B.7.

Now select File | Compile. This brings up the Compile a Help File dialog box. Select the Browse... button and find the `PROJECT.HPJ` file you created previously. Select the Compile button to begin the compilation of your help file. The result is a `PROJECT.HLP` file that can be accessed directly from the Windows Explorer, or by selecting File | Run Winhelp... in Help Workshop.

You are prompted for any compilation errors that are written to the error file `ERROR.TXT`. Review any error messages you receive and then edit the project and topic file as needed. Then you can recompile your project.
Figure B.7. The Help Workshop application.

###
Linking Help to Your Visual Basic Database Application

When the `PROJECT.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, open the Windows Explorer, and then double-click the file `PROJECT.HLP`. The first topic, Company Information, should now appear.

You now attach the help file to the Company Master application that you've been working on in this book. To do this, you first attach help information by setting Visual Basic 5 control 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

Follow these steps to attach a help file to your project:

  1. Select Project | Properties... from the Visual Basic 5 Projects menu. Then select the General tab.
  2. Select Help File and then enter the name of the help file (`PROJECT.HLP`), including its path. You can also click the _ box at the right of the field to Search for the file.
  3. 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 Company Master project.
  2. Select and open the Company Master form.
  3. Select the txtCompanyName control.
  4. Press F4 and move to the HelpContextID property in the Properties window.
  5. Enter 1.

The entry in the HelpContextID property refers to the value you set in the project file (`PROJECT.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 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 Index button 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 displays 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 need to build a topic, assign footnotes, create jumps to the underlying topics, and modify the project file. When you have done this, you then need to recompile the project.

Reopen your topics file (`TOPICS.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 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 information 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. See Figure B.8 for an example.
Figure B.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. 1. Create a new topic for your pop-up text. In this exercise, you 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.
  5. The text added to call the pop-up should be similar to the text displayed in Figure B.9.

Figure B.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 `PROJECT.HPJ`. Bring up Notepad and open this file. This file should look like the one shown in Figure B.10.
Figure B.10. `PROJECT.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 `PROJECT.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 do 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, and exit to the Microsoft Help Workshop, and then compile your help file.

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 B.11).
Figure B.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 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 filename 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 ()
    `assign the help file
       App.HelpFile = "C:\TYSDBVB5\SOURCE\APPXB\HELP\PROJECT.HLP"
    `set the help context id for a control
       txtName.HelpContextID = 1
    End

You need to set a HelpContextID for each control to which you want to add help. Be forewarned that 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 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 Editor... from Visual Basic's Tools 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:

    Private Sub Form_Load ()
    `assign the help file to use (insert your path)
       App.HelpFile = "C:\TYSDBVB5\SOURCE\APPXB\HELP\PROJECT.HLP"
    End Sub

The line `App.HelpFile = "C:\TYSDBVB5\SOURCE\APPXB\HELP\PROJECT.HLP` defines the help file for the project.

Next, create a new module by selecting Add Module from the Project 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,
       _ By Val 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 and 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:

    Private Sub mnuContents_Click ()
       Helpfile Me, Help_index
    End Sub

Second, enter the following code in the `mnuSearch_Click` event:

    Private Sub mnuSearch_Click ()
       HelpFile Me, Help_PartialKey
    End Sub

Third, enter the following code in the `mnuHelponHelp_Click` event:

    Private Sub mnuHelponHelp_Click ()
    HelpFile Me, Help_HelponHelp
    End Sub

Fourth, enter the following code in the `mnuAbout_Click` event:

    Private Sub mnuAbout_Click ()
        WinAboutPage Me
    End Sub

Fifth, enter the following code inside the `mnuExit_Click` event:

    Private Sub mnuExit_Click()
       Unload Me
    End Sub

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

    Private Sub Form_Unload (Cancel As Integer)
       HelpFile Me, Help_Quit
    End Sub

Save your form and 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 B.12, which shows the Win 95 help topics. Selecting Help | About displays a dialog similar to Figure B.13, which contains information about your program. Finally, selecting Exit from the File menu stops the execution of the program.
Figure B.12. Help on Help.

######

Figure B.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 that this application runs 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 runs under either version of Visual Basic (16- or 32-bit), or Visual Basic 5.

The final entries into the general declaration section are to define the constants that are 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:

- It declares variables:

>     Sub HelpFile (frmForm As Form, nHelpCmd As Integer)
>        Dim i As Integer
>        Dim nFlag As Integer
>        Dim aData As Variant

- It tests for the declaration of a help file and returns a message if none is declared:

>        If Len(LTrim(RTrim(App.HelpFile))) = 0 Then
>           MsgBox "No Help File Available"
>           GoTo HelpFile_Exit
>        End If

- It flips a switch depending upon which value has been selected. This switch is set to True if a valid case is passed:

>        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

- It makes the API call depending upon the value passed:

>     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

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 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 undoubtedly makes 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 is 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 Web site, CompuServe, and America Online services. This tool is actually a Word 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 lesson, your help topic file contains the information that users 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 of 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 than 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 keeps 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 is needed most when users are new to the system and just beginning to learn it. Everyday 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 is required in order to get the job done.

If you are managing a team of developers, allow them the time needed to develop docu-mentation. 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 follows 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 lesson:

  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 dictates 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 topic 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 Exercise 2.
  4. Add a topic to the help file created in this lesson to describe the Company Master form. Recompile your project and attach help to the form. (Hint: Be sure to modify the `[Map]` section of your project file for the context string.)

| Use of this site is subject certain Terms & Conditions. Copyright (c) 1996-1999 EarthWeb, Inc.. All rights reserved. Reproduction in whole or in part in any form or medium without express written permission of EarthWeb is prohibited. Please read our privacy policy for details.