Microsoft KB Archive/828419

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

Article ID: 828419

Article Last Modified on 6/30/2005

-

APPLIES TO


 * Microsoft Office Access 2003
 * Microsoft HTML Help 1.3

-





This article applies to a Microsoft Access database (.mdb) and a Microsoft Access project (.adp).

Advanced: Requires expert coding, interoperability, and multiuser skills.

IN THIS TASK

 * SUMMARY
 * Create the Help System by Using HTML Help Workshop
 * Create Help Topics
 * Create Context-Sensitive Help for Each Help Topic
 * Associate Help Context IDs with Topic Identifiers
 * Associate Help Topics with Topic Identifiers
 * Compile the Help System to Create a Single Compressed HTML File
 * Validate the Help System
 * Integrate the Help System in Access 2003
 * Create an Access Form to Test the Help System (.chm File)
 * Test the Help System (.chm File)
 * REFERENCES



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.

back to the top

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).

back to the top

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:
 * 1) Click Start, point to All Programs, and then click HTML Help Workshop.
 * 2) On the File menu, click New.
 * 3) In the New dialog box, click Project, and then click OK.
 * 4) In the New Project dialog box, click Next.
 * 5) In the New Project -- Destination dialog box, click Browse.
 * 6) In the Open dialog box, click C: in the Look in list.
 * 7) Create a new folder that is named TestHelpProject.
 * 8) In the Open dialog box, select TestHelpProject, and then click Open.
 * 9) In the File name box, type MyProject, and then click Open.
 * 10) In the New Project -- Destination dialog box, click Next.
 * 11) In the New Project -- Existing Files dialog box, click Next.
 * 12) In the New Project -- Finish dialog box, click Finish.
 * 13) On the File menu, click New.
 * 14) In the New dialog box, click HTML File, and then click OK.
 * 15) In the HTML Title dialog box, type Text Box Help, and then click OK.
 * 16) Between  and , type This Is the Help Topic for the Text Box, and then click OK.
 * 17) On the File menu, click Save File.
 * 18) 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.
 * 1) On the File menu, click New.
 * 2) In the New dialog box, click HTML File, and then click OK.
 * 3) In the HTML Title dialog box, type Button Help, and then click OK.
 * 4) Between  and , type This Is the Help Topic for the Button Control, and then click OK.
 * 5) On the File menu, click Save File.
 * 6) In the Save As dialog box, double-click C:\TestHelpProject. In the File Name box, type Sample2.htm, and then click Save.
 * 7) In HTML Help Workshop, click Add/Remove topic files.

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

back to the top

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.</li> In the Save As dialog box, double-click C:\TestHelpProject, type Popuptext.txt in the File Name dialog box, and then click Save.</li> Close Notepad.</li></ol>

back to the top

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: 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.
 * 1) define FirstTopic 1

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

To create a Map file for the Help topics, follow these steps:
 * 1) Click Start, and then click Run.
 * 2) In the Open box, type notepad, and then click OK.
 * 3) Copy the following text, and then paste the text in Notepad:


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

back to the top

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:
 * 1) Click Start, and then click Run.
 * 2) In the Open box, type notepad, and then click OK.
 * 3) In Notepad, type the following lines: TEXTBOXHELP=Sample1.htm; BUTTONHELP=Sample2.htm;
 * 4) On the File menu, click Save.
 * 5) In the Save As dialog box, double-click C:\TestHelpProject, and then select All Files from the Save as type list.
 * 6) In the File Name box, type Alias.h, and then click Save.

back to the top

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:
 * 1) Click Start, point to All Programs, and then click HTML Help Workshop.
 * 2) On the File menu, click Open.
 * 3) In the Open dialog box, click MyProject.hhp.
 * 4) 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.
 * 1) On the Map tab, click Header file.
 * 2) In the File to Include box, type C:\TestHelpProject\Map.h, and then click OK.

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

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

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

back to the top

Validate the Help System
To validate that the Help system has been successfully created, follow these steps:
 * 1) Start Microsoft Windows Explorer.
 * 2) Move to the MyProject.chm file in Windows Explorer.
 * 3) Double-click the MyProject.chm file to open the file.

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

back to the top

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.

back to the top

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. <ol> Start Access 2003.</li> Create a new database that is named TestHelp.mdb in the C:\TestHelpProject folder.</li> Open the TestHelp database.</li> 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</li> On the View menu, click Code.</li>  Declare the following constants and the following functions in the &quot;Declarations&quot; 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 = &quot;MyProject.chm::/Popuptext.txt&quot;

Private Declare Function HtmlHelp Lib &quot;hhctrl.ocx&quot; Alias &quot;HtmlHelpA&quot; (ByVal hwndCaller As Long, ByVal pszFile As String, ByVal uCommand As Long, ByVal dwData As Long) As Long Private Declare Function HtmlHelpByRefArg Lib &quot;hhctrl.ocx&quot; Alias &quot;HtmlHelpA&quot; (ByVal hwndCaller As Long, ByVal pszFile As String, ByVal uCommand As Long, ByRef dwData As Any) As Long Private Declare Function GetDlgCtrlID Lib &quot;user32&quot; (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 </li>  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 </li> Save the form with the name FormTest, and then close the form.</li></ol>

back to the top

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
 * 1) Start Access 2003.
 * 2) Open the TestHelp.mdb database.
 * 3) Open the FormTest form in form view.
 * 4) 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.
 * 1) 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
 * 1) Start Access 2003.
 * 2) Open the TestHelp.mdb database.
 * 3) Open the FormTest form in form view.
 * 4) Select Control1, and then press F2.

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

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

back to the top

<div class="references_section">