Advanced Visual Basic Techniques
(Publisher: John Wiley & Sons, Inc.)
Author(s): Rod Stephens
ISBN: 0471188816
Publication Date: 06/01/97

AppointmentBook’s main form uses a URLHelpForm to provide both topical and context-sensitive help. The Contents command in the Help menu uses the URLHelpForm’s PresentTopic subroutine to display the file Contents.HTM. Similarly, the Help menu’s Index command displays the HTML file Index.HTM.

Private Sub mnuHelpContents_Click()
    HelpBrowser.PresentTopic “Contents”
End Sub

Private Sub mnuHelpIndex_Click()
    HelpBrowser.PresentTopic “Index”
End Sub

To provide context-sensitive help, AppointmentBook’s main form examines KeyDown events looking for the F1 key. When the user presses F1, the program checks the Tag property of the control that currently has the input focus. If that property is nonblank, it contains the name of the help topic that should be presented. For example, the Tag property of the month area’s picture box is “MonthA.” If the user clicks on the month area and then presses F1, the program presents the help file MonthA.HTM. If no control on the form currently has the input focus, or if the control’s Tag property is blank, the program presents the help contents screen Contents.HTM.

Private Sub Form_KeyDown(KeyCode As Integer, Shift As Integer)
Dim topic As String
    If KeyCode = vbKeyF1 Then
        ‘ If there’s no topic, use Contents.
        topic = “Contents”

        If Not ActiveControl Is Nothing Then
            If ActiveControl.Tag <> “” Then
                topic = ActiveControl.Tag
            End If
        End If

        ‘ Present the help.
        HelpBrowser.PresentTopic topic
    End If
End Sub

Providing Navigation Features AppointmentBook’s URLHelpForm uses its WebBrowser control to provide several navigation commands. The Navigate menu’s Contents and Index commands use the PresentURL subroutine to display the files Contents.HTM and Index.HTM, respectively.

Private Sub mnuNavContents_Click()
    PresentTopic “Contents”
End Sub

Private Sub mnuNavIndex_Click()
    PresentTopic “Index”
End Sub

The Navigate menu’s Back command invokes the browser’s GoBack method to retrieve the previously displayed HTML file. It is important that this routine use the On Error Resume Next statement to protect itself from errors generated by the browser. If the user invokes the Back command too many times, the browser will try to move beyond the first document it loaded. In that case, the control will fail and will generate an error.

Private Sub mnuNavBack_Click()
    On Error Resume Next
    Browser.GoBack
End Sub

The Navigate menu’s Refresh command uses the browser’s Refresh method to reload the document it is currently displaying. This is useful if the document was changed after it was last loaded into the browser. This is particularly helpful in building and testing the help system.

Private Sub mnuNavRefresh_Click()
    On Error Resume Next
    Browser.Refresh
End Sub

The URLHelpForm’s Navigate menu also provides a list of the 10 documents most recently visited by the browser. If the user selects one of the entries, the help system reloads the corresponding document.

The 10 menu entries that hold the list are all named mnuNavigate, and they have Index property values 1 through 10. Initially their Caption properties are all blank, and their Visible properties are set to false.

After the browser loads a new document, it receives a NavigateComplete event. In the NavigateComplete event handler, AppointmentBook updates the navigation history menu entries. First it sets the URLHelpForm’s Caption to the name of the newly loaded document. Next the program inserts the document’s name at the top of the history list, moving the other entries down one position to make room. When it has finished, the program sets the Visible property of the menu entries with nonblank captions to true so the user can select them.

Private Sub Browser_NavigateComplete(ByVal URL As String)
Dim i As Integer
Dim j As Integer

    ‘ Set the window’s caption.
    Caption = Browser.LocationName

    ‘ See if this URL is in the History menu.
    For i = 1 To 10
        If mnuNavigate(i).Caption = URL Then Exit For
    Next i
    If i > 10 Then i = 10

    ‘ i now points to the current location of
    ‘ this URL or 10 if it is not in the list.
    ‘ Move entries above this one down one spot
    ‘ to make room for this URL at the top.
    For j = i To 2 Step -1
        mnuNavigate(j).Caption = mnuNavigate(j - 1).Caption
    Next j

    ‘ Insert this URL at the top.
    mnuNavigate(1).Caption = URL

    ‘ Make the nonblank menu entries visible.
    For i = 1 To 10
        If mnuNavigate(i).Caption <> “” Then _
           mnuNavigate(i).Visible = True
    Next i
End Sub

When the user invokes one of the menu history commands, the program presents the help file associated with the menu entry.

Private Sub mnuNavigate_Click(Index As Integer)
    On Error Resume Next
    PresentURL mnuNavigate(Index).Caption
End Sub

URLHelpForm’s last interesting menu command is the File menu’s Close command. Rather than destroying the help form, this command hides it. When the main program later presents help again, it can quickly reuse the existing form instead of creating a new one. This allows the form to retain the history list presented in its Navigate menu.

Making the Close command in the File menu hide the form does not prevent the user from destroying the form by selecting the Close command from the form’s system menu. To prevent this from occurring, the form’s QueryUnload event handler checks the method by which the user is attempting to unload the form. If the user selected the Close command from the System menu, the routine cancels the unload event and hides the form instead of unloading it.

Private Sub mnuFileClose_Click()
    On Error Resume Next
    Me.Hide
End Sub

Private Sub Form_QueryUnload(Cancel As Integer, UnloadMode As Integer)
    If UnloadMode = vbFormControlMenu Then
        Cancel = 1
        Me.Hide
    End If
End Sub

Building Help Documents

Although there is no room here to describe the entire hypertext markup language, this section explains the most important elements used to build AppointmentBook’s help documents. Some more advanced HTML commands are described in Chapters 14 through 19.

The following section describes the HTML commands used by AppointmentBook’s help documents. Almost all of these are demonstrated by the file Contents.HTM, so the next section lists that file. It also shows a picture of the help system displaying Contents.HTM so you can see how some of the commands are displayed.

The last section in this chapter briefly describes the file Index.HTM. This file uses only a few commands not already demonstrated by Contents.HTM, but it has a rather interesting design.

The other documents used by AppointmentBook’s help system are fairly similar to Contents.HTM. If you want to examine them in detail, you will find them in the Ch3\HelpHTML directory on the compact disk.