How to create an HTML Help system by using either the HTMLHelp API or the HTML Help in Access

View products that this article applies to.

Summary

Microsoft HTML Help Workshop is a Help authoring tool with an easy-to-use graphical interface. You can use HTML Help Workshop to create the following kinds of files:

Help project files
Topic files
Content files
Index files

You can put these files together to create an online Help system.

HTML Help Workshop version 1.3 is included with the Microsoft Office 2003 Resource Kit. HTML Help Workshop version 1.3 can be used to create a Help system that provides customized information and assistance.

This article describes how to create a simple Help system in HTML Help Workshop and then how to use the Help file in a Microsoft Office Access 2003 form by using the HTMLHelp API.

Create the Help System by Using HTML Help Workshop

You can create two kinds of Help topics by using HTML Help Workshop:

Window-Level Help In the window-level Help, the Help topic appears in a window when you trigger the Help topic. The source of the window-level Help topic is an HTML file.
Context-Sensitive Help In the context-sensitive Help, the Help topic appears in a pop-up window when you trigger the Help topic. The source of the context-sensitive Help topic is a text file that contains the content that must appear in the pop-up window for each Help topic.

Help topics are created individually, and then the topics are included in an HTML Help Workshop project. This project is then compiled to create an HTML Help System (*.chm file).

Create Help Topics

You can create a window-level Help topic by creating at least one HTML file for the Help topic. Use Notepad or an HTML editor to create the HTML files. HTML Help Workshop also permits you to create an HTML file. To create an HTML file for the Help topics by using HTML Help Workshop, follow these steps:

Click Start, point to All Programs, and then click HTML Help Workshop.
On the File menu, click New.
In the New dialog box, click Project, and then click OK.
In the New Project dialog box, click Next.
In the New Project -- Destination dialog box, click Browse.
In the Open dialog box, click C: in the Look in list.
Create a new folder that is named TestHelpProject.
In the Open dialog box, select TestHelpProject, and then click Open.
In the File name box, type MyProject, and then click Open.
In the New Project -- Destination dialog box, click Next.
In the New Project -- Existing Files dialog box, click Next.
In the New Project -- Finish dialog box, click Finish.
On the File menu, click New.
In the New dialog box, click HTML File, and then click OK.
In the HTML Title dialog box, type Text Box Help, and then click OK.
Between <BODY> and </BODY>, type This Is the Help Topic for the Text Box, and then click OK.
On the File menu, click Save File.
In the Save As dialog box, double-click C:\TestHelpProject. In the File Name box, type Sample1.htm, and then click Save.

The Sample1.htm Help file is saved in the C:\TestHelpProject folder.
On the File menu, click New.
In the New dialog box, click HTML File, and then click OK.
In the HTML Title dialog box, type Button Help, and then click OK.
Between <BODY> and </BODY>, type This Is the Help Topic for the Button Control, and then click OK.
On the File menu, click Save File.
In the Save As dialog box, double-click C:\TestHelpProject. In the File Name box, type Sample2.htm, and then click Save.
In HTML Help Workshop, click Add/Remove topic files.

Note Add/Remove topic files is the second button down on the Project tab.
In the Topic Files dialog box, click Add, and then locate and add the Sample1.htm file and the Sample2.htm file.

Create Context-Sensitive Help for Each Help Topic

The context-sensitive Help for all the supported Help topics must be listed in a text file. You can create the text file by using Notepad, and then you can include the text file in the current project in HTML Help Workshop.

To create the context-sensitive Help file for the Help topics, follow these steps:

Click Start, and then click Run.
In the Open box, type notepad, and then click OK.
Copy the following text, and then paste the text in Notepad:
```
.topic 1
This is a text pop-up window for Text Box Control Help.

.topic 2
This is a text pop-up window for Button Control Help.
```
Note Each of the Help topic references must start with .topic. The .topic must be followed by a space and then by a number or by a numeric constant. This number must represent the Context ID for the Help topic. The content of the pop-up window for the Help topic is on the next line.
On the File menu, click Save.
In the Save As dialog box, double-click C:\TestHelpProject, type Popuptext.txt in the File Name dialog box, and then click Save.
Close Notepad.

Associate Help Context IDs with Topic Identifiers

You can assign the Context ID numbers to the specific topics in a Map file. The Map file is actually a C header file that is used by the Help compiler when the Help compiler compresses all the *.htm files into one *.chm file. The Map file is a plain-text file that contains the #define statement for each topic in your Help system.

For example, you can use the following code:

#define FirstTopic 1

In the Map file, each statement must include a topic identifier that is followed by the Context ID. The applications that use the Help system can refer to a topic by using the Context ID that is defined in the Map file. Therefore, Map files help you to associate Help Context IDs to each Help topic.

Note The Map file is a text file with an .h extension.

To create a Map file for the Help topics, follow these steps:

Click Start, and then click Run.
In the Open box, type notepad, and then click OK.
Copy the following text, and then paste the text in Notepad:

#define TEXTBOXHELP 1 #define BUTTONHELP 2
On the File menu, click Save.
In the Save As dialog box, double-click C:\TestHelpProject, and then select All Files from the Save as type list.
In the File Name box, type Map.h, and then click Save.

Associate Help Topics with Topic Identifiers

The Help topics (.html files) must be associated to the topic identifiers that are defined in the Map file. You can do this if you define aliases for the Help topics. An alias is the relationship between a window-level Help topic (.html file) and a topic identifier in a Map file. Therefore, you must create the window-level Help topics before you create the aliases.

To create aliases for window-level topics to function correctly, follow these steps:

Click Start, and then click Run.
In the Open box, type notepad, and then click OK.
In Notepad, type the following lines: TEXTBOXHELP=Sample1.htm; BUTTONHELP=Sample2.htm;
On the File menu, click Save.
In the Save As dialog box, double-click C:\TestHelpProject, and then select All Files from the Save as type list.
In the File Name box, type Alias.h, and then click Save.

Compile the Help System to Create a Single Compressed HTML File

After all the Help topics (.html files), the text file, the map file, and the alias file are created individually, you must now integrate all the files in the current HTML Help Workshop project. Then you must compile the project. As a result, you now have a single compressed HTML Help file with a .chm extension that is created in the current directory.

To integrate all the Help files and then to compile the HTML Help Workshop project, follow these steps:

Click Start, point to All Programs, and then click HTML Help Workshop.
On the File menu, click Open.
In the Open dialog box, click MyProject.hhp.
In HTML Help Workshop, click HTMLHelp API Information on the Project tab.

Note This is the fourth button down on the left side of the Project tab.
On the Map tab, click Header file.
In the File to Include box, type C:\TestHelpProject\Map.h, and then click OK.

Notice that #include Map.h appears in the list.
On the Alias tab, click Include.
In the File to Include box, type C:\TestHelpProject\Alias.h, and then click OK.

Notice that #include Alias.h appears in the list.
On the Text-Popups tab, click Text file.
In the File to Include box, type C:\TestHelpProject\Popuptext.txt, and then click OK.
Click OK.
On the File menu, click Compile.

The MyProject.hhp Help file compiles to create the MyProject.chm file.

Validate the Help System

To validate that the Help system has been successfully created, follow these steps:

Start Microsoft Windows Explorer.
Move to the MyProject.chm file in Windows Explorer.
Double-click the MyProject.chm file to open the file.

Notice that when the HTMLHelp window opens, one of the topic pages appears.

Integrate the Help System in Access 2003

You can use the Help system that you created in a previous section of this article in Access 2003. In this example, the Help system is tested through a form that is created in the Access 2003 database.

Create an Access Form to Test the Help System (.chm File)

Microsoft provides programming examples for illustration only, without warranty either expressed or implied. This includes, but is not limited to, the implied warranties of merchantability or fitness for a particular purpose. This article assumes that you are familiar with the programming language that is being demonstrated and with the tools that are used to create and to debug procedures. Microsoft support engineers can help explain the functionality of a particular procedure, but they will not modify these examples to provide added functionality or construct procedures to meet your specific requirements.

Start Access 2003.
Create a new database that is named TestHelp.mdb in the C:\TestHelpProject folder.
Open the TestHelp database.
In the TestHelp database, add a form with the following specifications:

Form: Test
------------------------------
Caption: TestForm
HelpFile: MyProject.chm
HelpContextId: 1

TextBox
------------------------------
Name: Control1
HelpContextId: 1

Button
---------------------------------
Name: Control2
HelpContextId: 2
On the View menu, click Code.

Declare the following constants and the following functions in the "Declarations" section.

Option Compare Database

Const HH_DISPLAY_TOPIC As Long = &H0
Const HH_SET_WIN_TYPE As Long = &H4
Const HH_GET_WIN_TYPE As Long = &H5
Const HH_GET_WIN_HANDLE As Long = &H6
Const HH_DISPLAY_TEXT_POPUP As Long = &HE
Const HH_HELP_CONTEXT  As Long = &HF
Const HH_TP_HELP_CONTEXTMENU As Long = &H10
Const HH_TP_HELP_WM_HELP As Long = &H11
Const g_sHTMLHelpFile As String = "MyProject.chm::/Popuptext.txt"

Private Declare Function HtmlHelp Lib "hhctrl.ocx" Alias "HtmlHelpA" (ByVal hwndCaller As Long, ByVal pszFile As String, ByVal uCommand As Long, ByVal dwData As Long) As Long
Private Declare Function HtmlHelpByRefArg Lib "hhctrl.ocx" Alias "HtmlHelpA" (ByVal hwndCaller As Long, ByVal pszFile As String, ByVal uCommand As Long, ByRef dwData As Any) As Long
Private Declare Function GetDlgCtrlID Lib "user32" (ByVal hWnd As Long) As Long
Private Type HH_IDPAIR
    dwControlId As Long
    dwTopicId As Long
End Type

      'This array must contain the number of controls that have
      'context-sensitive Help, plus one more for a zero-terminating
      'pair.
      Private ids(3) As HH_IDPAIR

Invoke the HTMLHelp API to display the context-sensitive Help. To do this, type or paste the following code in the code window.

Note The following code maps the F2 key to the context-sensitive Help for the active control.

Private Sub Control1_KeyUp(KeyCode As Integer, Shift As Integer)
If KeyCode = vbKeyF2 Then
           iRetCode = HtmlHelpByRefArg(Me.hWnd, _
                  g_sHTMLHelpFile, HH_TP_HELP_WM_HELP, ids(0))

      End If
End Sub

Private Sub Control2_KeyUp(KeyCode As Integer, Shift As Integer)

       If KeyCode = vbKeyF2 Then
           iRetCode = HtmlHelpByRefArg(Me.hWnd, _
                  g_sHTMLHelpFile, HH_TP_HELP_WM_HELP, ids(1))

      End If
End Sub

Private Sub Form_Load()

       ids(0).dwControlId = GetDlgCtrlID(Me.hWnd)
       ids(0).dwTopicId = Me.Control1.HelpContextId
       ids(1).dwControlId = GetDlgCtrlID(Me.hWnd)
       ids(1).dwTopicId = Me.Control2.HelpContextId
       ids(2).dwControlId = 0
       ids(2).dwTopicId = 0
End Sub

Save the form with the name FormTest, and then close the form.

Test the Help System (.chm File)

Use the form in an Access 2003 database to test both the window-level Help and the context-sensitive Help.

Test the Window-Level Help

Start Access 2003.
Open the TestHelp.mdb database.
Open the FormTest form in form view.
Move the focus to the Control1 text box on the form, and then press F1.

Notice that the window-level Help topic for the Text Box control appears.
Move the focus to the Control2 button on the form, and then press F1.

Notice that the window-level Help topic for the Button control appears.

Test the Context-Sensitive Help

Start Access 2003.
Open the TestHelp.mdb database.
Open the FormTest form in form view.
Select Control1, and then press F2.

Notice that the context-sensitive Help for the Text Box control appears.
Select Control2, and then press F2.

Notice that the context-sensitive Help for the Button control appears.

↑ Back to the top