Tip 196: Using the Common Dialog Control to Invoke Context-Sensitive Help

December 5, 1995

Abstract

The Common Dialog control in Microsoft® Visual Basic® allows you to invoke Help immediately and does not require that you use a dialog box. This article explains how to use the Common Dialog control to access specific Microsoft Windows® Help files.

Accessing Context-Sensitive Help

Most Microsoft® Windows® users know they can get Help at any time by pressing the f1 function key. When f1 is detected, Windows activates its WinHelp application. This application then displays Help information for the item located under the mouse pointer. This form of contextual user assistance is called context-sensitive Help.

You can easily add this technique to your own Microsoft Visual Basic® applications. Tip 15: Creating a List of Directories Stored on a Disk contains a full discussion of using the Windows application programming interface (API) WinHelp function; but in this case, you will use the Common Dialog control to access Help. It is sometimes preferable to use the Help function of the Common Dialog control rather than using the WinHelp function itself. The Common Dialog control allows you to invoke Help immediately and does not require that you use a dialog box.

In the example program below, you use the Common Dialog control to call up the Windows WinHelp application. To do this, you need only to set the Action property of the Common Dialog control to a value of 6. This tells the control that you want to access the Windows WinHelp application.

Next, you set the HelpKey property of the Common Dialog control to the text with which you want to invoke Help. This is the word or phrase you typed in the Text Box control.

Finally, you set the HelpCommand property of the Common Dialog control to HELP_KEY. This allows us to perform a context-sensitive search in the Help file.

Example Program

This program shows how to access a Windows Help file based on a specific string in a Text Box control.

1. Create a new project in Visual Basic. Form1 is created by default.
   
   
2. Add the following constants to the General Declarations section of Form1:

   Const KEY_F1 = &H70
   Const HELP_KEY = &H101
   

3. Add the following code to the Form_Load event for Form1:

   Private Sub Form_Load()
       KeyPreview = True
       CommonDialog1.HelpFile = "c:\vb\vb.hlp"
   End Sub
   

4. Add the following code to the Form_KeyDown event for Form1:

   Private Sub Form_KeyDown(KeyCode As Integer, Shift As Integer)
       If KeyCode = KEY_F1 Then
           If TypeOf Me.ActiveControl Is TextBox Then
               If ActiveControl.SelText <> "" Then
                   CommonDialog1.HelpKey = ActiveControl.SelText
                   CommonDialog1.HelpCommand = HELP_KEY
                   CommonDialog1.Action = 6
               Else
                   MsgBox "Error - no phrase was selected to get help for"
               End If
               KeyCode = 0
           Else
               MsgBox "The Text Box must have the focus"
           End If
       End If
   
   End Sub
   

5. Add a Text Box control to Form1. Text1 is created by default.
   
   
6. Add a Common Dialog control to Form1. CommonDialog1 is created by default.

Run the example program by pressing f5. Type some text in the Text Box control, such as "We need help on the CommonDialog Control right now." Highlight the phrase "CommonDialog Control" in the Text Box control. Press f1. The program displays the Help page for the Common Dialog control. Note that if you attempt to invoke Help without first selecting a word or phrase in the Text Box control, an error message appears. By the same token, if the Text Box control does not have the focus when you press f1, an error is generated.