Kapitel13

Hinzufügen von Hilfe zu eigenen Office-Lösungen

Beim Stöbern im Internet bin ich auf dieses ältere Dokument gestoßen. Ich möchte es den Interessierten nicht vorenthalten und unbearbeitet (und daher auch in Englisch) anbieten.

Chapter 13 - Adding Help to Your Custom Solution

Adding online Help to your Microsoft Office solution can reduce the amount of time required to train and support users of your solutions. By using the tools provided with Microsoft HTML Help Workshop or your favorite HTML editor, you can author topics for a Help system by using the same tools and technologies used to create Web pages — including hyperlinks, ActiveX controls, scripting, and Dynamic HTML (DHTML) support. You can then compile your topics into a single file and display them by using the same viewer that is used to display Help in Microsoft Office 2000.
By using standard properties and methods, you can integrate Help topics and context-sensitive Help into your solution's custom dialog boxes, error messages, and forms. If you want even more control over how HTML Help is displayed and integrated into your solution, you can work directly with HtmlHelp application programming interface (API) calls from your Visual Basic for Applications (VBA) code.
If you purchased Microsoft Office 2000 Developer or the Microsoft Office 2000 Resource Kit (Microsoft Press, 1999), you can use the Answer Wizard Software Development Kit (SDK) to integrate your own Help topics with those returned to users in Office 2000 by the Microsoft Office Assistant.
You can also use the navigation functionality of the HTML Help ActiveX control, such as a hierarchical table of contents or an index, on Web pages independently of using the HTML Help Viewer.

What Is Microsoft HTML Help?

Microsoft HTML Help is Microsoft's next-generation online Help authoring system. It is designed for use by authors or developers who create Help for software programs, multimedia titles, intranets, extranets, or the Internet. Topics in an HTML Help online Help system are authored as standard HTML files, which you can create with the editor in HTML Help Workshop or with any other HTML authoring tool, such as Microsoft Word or Microsoft FrontPage. The HTML Help Viewer uses the layout engine components of Microsoft Internet Explorer (Shdocvw.dll hosting Mshtml.dll) to display Help topics. As a result, Microsoft HTML Help topics can use the same technologies supported by Internet Explorer, such as HTML (including DHTML when the layout engine components for Internet Explorer version 4.0 or later are installed), ActiveX controls and documents, Java applets, scripting, HTML image formats (.jpeg, .gif, .png), and even video and audio.

Redistributing HTML Help Components

To display HTML Help, a user's computer must have both HTML Help components and Microsoft Internet Explorer layout engine components installed. If you are creating an Access run-time application and installing it on a computer that does not have Office 2000 installed, the components necessary to display HTML Help may not available. All the components necessary to display HTML Help are installed with any of the following:

  • Microsoft Office 2000
  • Microsoft Internet Explorer version 4.0 or later
  • Microsoft Windows 98

If none of these are available on a user's computer, you will need to redistribute some or all of the components necessary to display HTML Help.

 

If users have Internet Explorer version 3.02 installed, and the HTML Help system you are distributing doesn't require DHTML or other functionality supported only by Internet Explorer 4.0 or later, you can use the HTML Help Update component (Hhupd.exe) to redistribute HTML Help. In this case, if you use Hhupd.exe to install HTML Help, HTML Help will use the layout engine components of Internet Explorer 3.02. The HTML Help Update component is available from the HTML Help Web site at microsoft.com.
If the Help system you are distributing requires functionality available only from the layout engine components of Internet Explorer 4.0 or later, users must install the appropriate version of Internet Explorer in order to install both HTML Help and the necessary layout engine components. If you need to redistribute and install Internet Explorer, you can do so by using the Microsoft Internet Explorer Administration Kit (IEAK). For information about obtaining this kit, see the Internet Explorer Administration Kit Web site at http://ieak.microsoft.com/.
You create an HTML Help online Help system by using the tools provided with HTML Help Workshop. To download and install these tools, go to the HTML Help Web site at microsoft.com (see link above).
Third-party tools are also available for authoring and compiling HTML Help files. Information about third-party tools is also available on the HTML Help Web site.

HTML Help consists of the following tools

HTML Help Workshop (Hhw.exe), a Help authoring tool with an easy-to-use graphical interface for creating Help project files, HTML topic files, contents files, index files, and everything else you need to put together a Help system or Help Web site.

The HTML Help ActiveX control (HHCtrl.ocx), for inserting features such as Help navigation and secondary window functionality into an HTML file.

The HTML Help Java applet (HHCtrl.class and associated .class files), for inserting Help navigation and secondary window functionality into an HTML page when you want to use a Java applet instead of an ActiveX control.

The Microsoft HTML Help Image Editor (Flash.exe), a tool for creating screenshots; converting, editing, and viewing image files; and browsing thumbnail images.

The HTML Help Authoring Guide, an online guide for using HTML Help Workshop and designing a Help system, plus a complete HtmlHelp API reference for developers and an HTML tag reference for authors.

The HTML Help Viewer program (Hh.exe), which displays and runs your Help system. Topics displayed in the HTML Help Viewer can use the HTML Help ActiveX control so that any navigational elements such as a table of contents, index, full-text search, or related topic jumps specified by the author will be part of the Help system.

Along with these tools, HTML Help provides two important features:

The ability to convert existing Windows Help files to HTML Help files. The ability to compress your HTML files while compiling them into a single file. This feature greatly reduces the amount of disk space required for your HTML files and simplifies distribution. A compiled HTML Help file (.chm) plays the same role as a compiled Windows Help file (.hlp).

You can use HTML Help to create two types of Help systems. You can:

Create a compiled Help file that is viewed by using the HTML Help Viewer. This is typically the way HTML Help is used to provide help for an Office solution. For more information about using HTML Help in Office solutions, see "Adding Help to Your Office Solution" later in this chapter.
Create Web pages that use the HTML Help ActiveX control or the HTML Help Java applet to implement navigation and secondary window features to display HTML pages and other documents from a Web browser. If you provide the appropriate value for the CODEBASE attribute when you are inserting the HTML Help ActiveX control in a Web page, the control can be installed and downloaded if it isn't already installed when a user opens the Web page. This method can be used to run a locally installed Help system, but it is more typically used to create general-purpose Web sites. For more information about using HTML Help to create a Web site, see "Using HTML Help to Author a Web Site" later in this chapter.

HTML Help supports many of the same features as Microsoft WinHelp 4.0 and uses a similar development model with a Help project file to combine topic, contents, index, image, and other source files into one compiled HTML Help file. You can also use many of the same HTML Help features available in a compiled HTML Help file by using either the HTML Help ActiveX control or the HTML Help Java applet to display your Help system from a Web browser.

You can use HTML Help to display Help topics for users in a variety of ways:
  • By using the free-standing HTML Help Viewer
  • By using customized windows called within an Office solution
  • From a Web site, by using the HTML Help ActiveX control (for Internet Explorer) or the HTML Help Java applet (for browsers that support Java)

Note HTML Help also allows you to author context-sensitive pop-up Help for user-interface elements. However, Office 2000 applications don't support context-sensitive Help that has been authored by using HTML Help. To create context-sensitive Help for Office solutions, you must use WinHelp 4.0 (.hlp) files. For more information about authoring and implementing context-sensitive Help for Office solutions, see "Displaying Help in Forms and Documents" later in this chapter.

The HTML Help Viewer

The HTML Help Viewer is the default display method for all compiled HTML Help files and is used to display Help topics in Office 2000 applications. The HTML Help Viewer features a three-paned window as shown in Figure 13.1.

Figure 13.1 The HTML Help Viewer

The topic pane of the HTML Help Viewer is an embedded instance of the Internet Explorer layout engine (Shdocvw.dll hosting Mshtml.dll) and can display any content supported by Internet Explorer, including Office document formats (Microsoft Word, Microsoft Excel, and Microsoft PowerPoint). The navigation pane can include a variety of different ways of accessing Help topics, including a table of contents, an index, and a full-text search tab. The button pane contains a toolbar that by default contains the following buttons.

Button Description

Hide/Show
Allows users to display or hide the navigation pane.

Back
Displays the previous topic.

Print
Prints individual topics or groups of topics from the Contents tab.

Options
Displays a menu that provides keyboard accessibility to button commands and other options.

You can use HTML Help Workshop to customize the window definition of the default HTML Help Viewer window to add Forward, Stop, Refresh, Home, and Locate (to manually synchronize a topic to the contents) buttons to the button pane. You can also define up to two custom buttons to jump to URLs you specify. Figure 13.1 shows an example of a customized button pane.

Custom Help Windows

If you are distributing compiled HTML Help files, you can use HTML Help Workshop to customize the appearance of the default HTML Help Viewer window, or you can create additional custom window definitions that change the window's size, position, background color, and other attributes. You can also embed a Help window directly within the user interface of your solution. These are the types of windows you can create or customize:

  • The HTML Help Viewer window, which by default is displayed as the three-paned window described in the previous section. Its appearance can be customized by creating a custom window definition.
  • A secondary window is a custom window in which you assign topics to display. You can customize a secondary window to be as full-featured as the HTML Help Viewer or to have fewer features; for example, to display as a single pane without the toolbar.
  • An embedded topic window that is nested in an application; for example, as a window displayed on a tab in a dialog box. To implement an embedded window, an application must use calls to the HtmlHelp API. The docked Help window used to display Help in Office 2000 applications is an example of an embedded Help window.

You create window definitions and specify the default window type for your Help system in an HTML Help project file (.hhp). You can also specify custom window types to be used when you are displaying topics from the contents or index, and when you are linking to other topics by using the HTML Help ActiveX control.

If you develop your solution in Excel or PowerPoint, you can display your solution's Help topics in the same docked window used by the Office 2000 Help system. To do this, the default window type in your HTML Help project file must be defined with the same name as one of the window types used by the Office Help system. For more information about how to display custom Help topics in an Office application's Help window, see "Displaying Custom Help Topics in an Office Application's Help Window" later in this chapter.

Many of the features available in HTML Help are implemented through the HTML Help ActiveX control (HHCtrl.ocx). The HTML Help ActiveX control is used to provide navigation features (such as a table of contents), to display secondary windows and pop-up definitions, and to provide other features. The HTML Help ActiveX control can be used from topics in a compiled Help system as well as from HTML pages displayed in a Web browser. The functionality provided by the HTML Help ActiveX control will run in the HTML Help Viewer or in any browser that supports ActiveX technology, such as Internet Explorer (version 3.01 or later). Some features provided by the HTML Help ActiveX control are available only when it is used from a compiled HTML Help file (.chm) that is displayed by using the HTML Help Viewer.

The most commonly used features supported by the HTML Help ActiveX control are:

  • Table of contents (displayed in a tree control)
  • Index
  • Secondary windows (available only from a .chm file displayed in the HTML Help Viewer)
  • The ability to size and position windows (available only from a .chm file displayed in the HTML Help Viewer)
  • Pop-up definitions
  • Context-sensitive Help (available only from a .chm file displayed in applications that support this functionality)
  • Shortcut buttons to run other programs (available only from a .chm file displayed in the HTML Help Viewer)
  • Related Topics links
  • Training card Help (step-by-step interactive help that is available only from a .chm file displayed in the HTML Help Viewer)
  • Splash screen

The best way to insert the HTML Help ActiveX control in an HTML file is by opening the HTML file in HTML Help Workshop and clicking HTML Help Control on the Tags menu. A wizard appears that lets you choose what kind of command to use with the control and helps you define other parameters to apply to that command. When you click Finish, the wizard inserts the appropriate <OBJECT> and <PARAM> tags in the HTML file. For example, the following HTML fragment inserts an instance of the HTML Help ActiveX control that creates a Related Topics button to display a dialog box that lists two topics:

<OBJECT ID=HHCtrl TYPE="application/x-oleobject" CLASSID="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"
CODEBASE="HHCtrl.ocx#Version=4,73,8259,0" WIDTH=12 HEIGHT=12>
<PARAM NAME="Command" VALUE="Related Topics">
<PARAM NAME="Button" VALUE="Text:Related Topics">
<PARAM NAME="Item1" VALUE="First topic;topic1.htm">
<PARAM NAME="Item2" VALUE="Second topic;topic2.htm">
</OBJECT>

Note Unlike many ActiveX controls, the HTML Help ActiveX control can be inserted only in HTML files. Even though the HTML Help ActiveX control is available as the HHCtrl object in the list of controls that you can add to the Toolbox in Office applications, if you try to insert the control in a form or document, an error message is displayed. The version number shown in the previous sample HTML code for the CODEBASE attribute (Version=4,73,8259,0) is the current version of the control at the time of this writing. When you insert an HTML Help ActiveX control by using HTML Help Workshop, the version number will reflect the version of the control that is installed on your computer.

Once you have the <OBJECT> tag for an instance of the HTML Help ActiveX control inserted in an HTML page, you can use Microsoft JScript or Microsoft Visual Basic Scripting Edition (VBScript) to work with the control. For example, the following HTML fragment uses an instance of HHCtrl.ocx and the control's TextPopup method in JScript to create a text pop-up:

<OBJECT ID=HHCtrl TYPE="application/x-oleobject"
CLASSID="clsid:adb880a6-d8ff-11cf-9377-00aa003b7a11"
CODEBASE="HHCtrl.ocx#Version=4,73,8259,0">
</OBJECT> <P>This is a <A HREF=JavaScript:HHCtrl.TextPopup(MyText,"Verdana,10",9,9,-1,-1)> pop-up</A>. </P> 
<SCRIPT>MyText="This is how a text pop-up window looks."</SCRIPT>

If you prefer to use VBScript, you can create an identical text pop-up by replacing JavaScript in the <A HREF> tag with VBScript like this:

 <A HREF=VBScript:HHCtrl.TextPopup(MyText,"Verdana,10",9,9,-1,-1)> pop-up</A>

For more information about using script with the HTML Help ActiveX control, see the HTML Help ActiveX Control Reference Web site at microsoft.com.

The HTML Help ActiveX Control vs. the HTML Help Java Applet

Although the HTML Help Java applet provides much of the same functionality as the HTML Help ActiveX control, the Java applet is more useful when it is used on a Web site than when it is used in a compiled HTML Help file. The Java applet does not provide as many features as the ActiveX control does, and it loads the table of contents and index more slowly than the ActiveX control does. However, the Java applet allows your Web site to use HTML Help navigation features and still be compatible with browsers that don't support ActiveX controls. For more information about working with the Java applet, see "Working with the HTML Help Java Applet" later in this chapter.

You can deploy the files that make up your HTML Help online Help system in any of the following ways:

  • As a set of HTML files compiled into one or more locally installed compiled HTML Help files (.chm)
  • As a set of locally installed HTML files to be accessed through the Windows file system
  • As a set of HTML files to be accessed through an intranet, an extranet, or the Internet
  • A combination of these formats

The advantage of using compiled HTML Help files is that you can install a single file or small set of files on each user's local drive that can be accessed without a network connection. Additionally, compiled HTML Help files use disk space much more efficiently than uncompiled HTML files, particularly on hard disks that have been formatted with the FAT file system. For this reason, using locally installed HTML files is not generally recommended unless you want to be able to access your HTML files from outside your HTML Help online Help system.

The advantage of supplying the Help topics as a Web site is that you can update and add new Help topics from a single central location; however, providing Help this way requires that users have network access to your Web site. Moreover, certain features of HTML Help, such as full-text search, are available only when you are using compiled HTML Help files. You can also provide Help topics through a combination of both standard and compiled HTML formats, most typically in the form of a locally installed compiled HTML Help file with jumps from individual topics or the table of contents to Web pages on an intranet, an extranet, or the Internet. In addition, you can display an HTML page contained in a compiled HTML Help file from Internet Explorer by using an appropriately formatted URL. For information about how to do this, see "Using a URL to Open a Page in a Compiled HTML Help File" later in this chapter.

Adding Help to Your Office Solution

You can display Help topics to assist users of your Office solutions in the following ways. Object or area Kinds of Help you can provide

Documents
Help topics that are displayed by clicking a Help button or a command bar control

UserForms
Context-sensitive Help for controls Help topics that are displayed by clicking a Help button or pressing F1

Access forms and reports
Context-sensitive Help for controls Help topics that are displayed by clicking a Help button or pressing F1

Command bars
Context-sensitive Help for command bar controls Help topics that are displayed by clicking a command bar control

Office Assistant
Help topics that are displayed by clicking a button in the Help balloon or (if you have the Answer Wizard SDK and create the necessary files) by querying the Office Assistant

VBA code
Help topics that are displayed by using the Help method of the Application object Help topics that are displayed by clicking the Help button, when you are using the InputBox and MsgBox functions Help topics for custom error messages, when you are using the Raise method of the Err object Context-sensitive Help topics for custom properties and methods you define in class modules (displayed through the Object Browser or by pressing F1 in a code module) Help topics that are displayed by using HtmlHelp API calls

Script
Help topics that are displayed by using the commands and methods of the HTML Help ActiveX control

The following sections provide details and pointers on how to add Help to your Office solution in all of these ways.

Maintaining Backward Compatibility with Office 97 Applications

If your solution needs to maintain backward compatibility with Office 97 applications, you should supply all Help authored and compiled as WinHelp 4.0 files by using Microsoft Help Workshop or some other WinHelp 4.0 authoring tool. The standard properties and methods available to display Help in Office 97 applications don't support using HTML Help files to display context-sensitive Help or standard Help topics.

However, you can display standard Help topics (but not context-sensitive Help) in Office 97 applications from HTML Help files if you create a function declaration to call the HtmlHelp API directly to display the topic. For information about using the HtmlHelp API to display a standard Help topic, see "Displaying Help by Using the HtmlHelp API" later in this chapter.

For information about creating WinHelp 4.0 files, see the Help system in Microsoft Help Workshop. Microsoft Help Workshop can be downloaded for free from the Microsoft Technical Support Web site at microsoft.com. You can create three kinds of Help for your Office solutions:

  • Context-sensitive pop-up Help to describe your solution's interface elements. (This kind of Help is sometimes referred to as What's This Help.)
  • You can create context-sensitive Help for dialog boxes created by using UserForms or Access forms. This type of Help is displayed either by clicking the question mark button in the title bar of a dialog box and then clicking a control, or by moving the focus to a control and then pressing SHIFT+F1. A small borderless pop-up window appears next to the clicked control.
  • You can also create context-sensitive Help for command bar controls. Context-sensitive Help for command bar controls is displayed either by pressing SHIFT+F1 and then clicking the control, or by clicking What's This? on the Help menu before clicking the control.
  • Important While HTML Help does provide the ability to author and display pop-up windows for context-sensitive Help, UserForms, Access forms, and command bars in Office 2000 do not support using HTML Help files for context-sensitive Help. If you want to add context-sensitive Help for interface elements in your Office 2000 solution, you must author and compile your topics as WinHelp 4.0 (.hlp) files by using Microsoft Help Workshop or some other WinHelp 4.0 authoring tool.
  • Standard Help topics that can be displayed by clicking a Help button in a dialog box or form, or by clicking a control on a command bar.
  • Clicking a Help button in a dialog box or form displays a Help topic in a separate Help window. You can also associate a Help topic with the Help button displayed in dialog boxes created by using the InputBox and MsgBox functions, and you can provide Help topics for custom errors returned by using the Raise method. Similarly, you can provide a menu item or toolbar button on a command bar to display a Help topic.
  • Standard Help topics that can be displayed from the Object Browser to document the properties and methods you define in custom class modules.

Office 2000 applications can display standard Help topics authored and compiled by using either HTML Help (.chm) or WinHelp 4.0 (.hlp). Context-sensitive Help for Office 2000 solutions must be authored by using WinHelp 4.0. You can download the tools required to author and compile both HTML Help and WinHelp 4.0 from the following locations:

To download and install the tools used to create HTML Help files, go to the HTML Help Web site at microsoft.com
To download and install Microsoft Help Workshop, used to create WinHelp 4.0 files, go to the Microsoft Technical Support Web site at microsoft.com.

Jumping from a WinHelp Topic to an HTML Help Topic

Because Office 2000 applications require you to use WinHelp 4.0 topics to author context-sensitive Help, you may sometimes need to jump from a WinHelp 4.0 topic to an HTML Help topic. You author a jump from any WinHelp 4.0 topic to an HTML Help topic by using the ExecFile macro. For example, a jump in a WinHelp 4.0 file that is formatted like the following example opens the first page in the compiled HTML Help file that is installed for Internet Explorer 4.0 or later:

Internet Explorer Help!

The first argument passed to the ExecFile macro, hh, refers to the program to run, Hh.exe, the HTML Help Viewer. The second argument is the URL to open a page in a .chm file as described in "Using a URL to Open a Page in a Compiled HTML Help File" later in this chapter.

Creating HTML Help Topics

The top-level steps for using HTML Help Workshop to create a Help system are as follows:

Create a Help project file (.hhp) to manage your topics, art, contents (.hhc), index (.hhk), and other source files, and to define the on-screen appearance of your Help system.
Author Help topic files in HTML. If you want to use the same styles as Microsoft Office Help topics, use the Office.css cascading style sheet file in the Samples\CH13\Help Source subfolder on the companion CD-ROM. Create a table of contents file for easy navigation to Help topics. (Optional)
Create an index file for indexing Help topics. (Optional)
Create window definitions to define each kind of window in which you want to display Help information. (Optional if you only want to use the default HTML Help Viewer window)
Define and assign information types for custom grouping of topics for different audiences, such as beginning or advanced users, or to display different sets of topics for different versions or installations of your solution. (Optional)
Compile your Help file. (Optional if you are using the HTML Help ActiveX control or the HTML Help Java applet from a Web site)

For detailed information about each of these steps, see the Help index in HTML Help Workshop.

Creating Context IDs

To display Help topics in Office solutions by using standard properties or the Help method of the Application object, your compiled Help file must have a numeric value, called a context ID, for each topic you want to display. This is true for both context-sensitive Help and standard Help topics, and whether you are using a compiled HTML Help file or a WinHelp 4.0 file.

Creating Context IDs for WinHelp 4.0 Files

For WinHelp 4.0 files, the process of mapping context IDs is the same for both context-sensitive pop-up Help and standard Help topics. To create and map context IDs in a WinHelp 4.0 Help file

Use Word to create a document, inserting a page break between each topic.
On the Insert menu, click Footnote to add a footnote to the first paragraph in each topic. In the Footnote and Endnote dialog box, click Custom mark and type # as the footnote symbol. As the footnote text, type a unique string called a topic ID for each topic; for example, HelpTopic1.
Save the document as a Rich Text Format file (.rtf).
Use Microsoft Help Workshop to create a Help project file that specifies this .rtf file as your topic file, and then either manually map each topic ID to a unique numeric context ID or create a C header file to do this.
Compile your Help file.

For more information about creating WinHelp files, see the Help system in Microsoft Help Workshop.

Creating Context IDs for HTML Help Files

In Office applications, HTML Help files can be used only for standard Help topics, and the process of mapping context IDs in HTML Help files is different than that used for WinHelp 4.0 files. In HTML Help, Help topics that will be displayed in the HTML Help Viewer or a Help window are authored by using a separate HTML file for each topic. After you have authored your Help topics, you will want to create jumps between them. To do this, instead of using a topic ID to specify the topic to jump to as is done for WinHelp 4.0 files, you author a standard HTML hyperlink that specifies the HTML file name of the topic. For example, the following <A> (anchor) tag creates a jump to the topic authored in the Options.htm file:

 <A HREF="Options.htm">Options

To retain compatibility with applications that expect context IDs, HTML Help requires you to perform two steps to create numeric context IDs for each topic file you want to display:

Create a C header file that maps an arbitrary topic ID text string to a numeric context ID.
Map each topic ID from the header file to the actual HTML file name of the topic you want to display. In HTML Help Workshop, this is called aliasing topic IDs to HTML file names. You can do this manually through the HTML Help Workshop user interface, or by creating a text file with an .h extension.

The following procedures assume you have already created Help topics for your HTML Help file.
To create a C-style header file to map topic IDs to context IDs

Create a new text file in HTML Help Workshop or in your favorite text editor.
For each topic you want to create a context ID for, enter a line in this format:
#define topic_id nnnn // comment
The string constant after #define is the topic ID and the number following it is the context ID. Each topic ID and context ID must be unique within your Help project. The "//" comment introducer and comment text are optional.
Save the text file with your other HTML Help source files and make sure it is named with an .h extension.

In HTML Help Workshop, open your Help project file, click the HtmlHelp API Information button on the Project tab, and then on the Map tab, click Header File and specify the header file.

After you have created your header file and specified it for your Help project file, you must alias each of the topic ID strings in the header file. You can do this manually or by including a text file that defines each alias. Before doing this, you should print out or open a copy of the map header file you created in the previous procedure so that you can view the names of each topic ID string.

To manually alias topic IDs to context IDs

  • Open your Help project file in HTML Help Workshop.
  • Click the HtmlHelp API Information button on the Project tab, and then click the Alias tab.
  • To manually specify the alias for each topic ID string, click Add, type the topic ID string you want to alias in the first box, and then select the HTML file that contains the topic in the second box.

To alias topic IDs to context IDs by using a text file

  • Create a text file and enter a line in this format for each topic ID you want to alias to an HTML file:
  • topic_id=filename.htm ; comment
  • The topic_id string constant is the topic ID from the mapping header file, and the file name following the equal sign (=) is the HTML file name of the topic you want to display. The ";" comment introducer and comment text that follows are optional.
  • Save the text file, making sure it has an .h extension.
  • Open your Help project file in HTML Help Workshop.
  • Click the HtmlHelp API Information button on the Project tab, and then click the Alias tab.
  • Click Include and specify the text file you just created.

Once you have mapped context IDs to the topic IDs in your compiled WinHelp 4.0 and HTML Help files, you use the appropriate context IDs in the design-time settings of forms and controls, and in your program code to display the correct Help topic.

For more information about creating HTML Help files, see the Help system in HTML Help Workshop.

Displaying Custom Help Topics in an Office Application's Help Window Built-in Help in Office 2000 applications is displayed in a docked window on the right side of the application window. If you are displaying a custom Help topic from Excel or PowerPoint by using the Help method of the Application object, you can also display your Help topic in this same window. This isn't possible in Word and Access because they require you to use a call to the HtmlHelp API to display a custom Help topic. Custom Help topics in Word and Access are always displayed in floating windows as defined by the window type specified in the HtmlHelp API call. If you prefer not to display your Excel or PowerPoint solution's Help in a docked window, you can use the HtmlHelp API to display the Help topic as described in "Displaying Help by Using the HtmlHelp API" later in this chapter.

To display a custom Help topic in an Office application's docked Help window, the compiled HTML Help file for your Help project must have a default window definition that is named either MSO_Small or MSO_Large. If you want, you can define toolbar buttons that are different from those in the standard Help window, but changes to other details of the window definition, such as the window's size and placement, will be ignored. The Help topic window will automatically be sized and placed in the application's docked Help window.

In addition to naming the default window definition, the window type's notification ID (referred to as idNotify in the HtmlHelp API) must be set to a nonzero value. This setting is not available in HTML Help Workshop's user interface. In order to make this setting for your Help project, you must edit the Help project file (.hhp) with a text editor and add a nonzero value at the end of your window definition. For example, the default window definition in the Sample.hhp file included in the Samples\CH13\Help Source subfolder on the companion CD-ROM looks like this:

 [WINDOWS]
MSO_Small="Sample Help","Toc.hhc","Sample.hhk","home.htm",,,,,,0x2121,200,0x300e,[0,0,445,514],,,,,,,1

The arbitrary value 1 was added to the end of the MSO_Small definition in order to specify a nonzero value for idNotify. After you change this value, make sure that this window definition is also specified as the default window (for example, Default Window=MSO_Small) in the [OPTIONS] section of the .hhp file, and then compile your Help file.
In addition to defining the window type as described above, you must also make sure the Office Assistant is displayed, or your Help topic will not be displayed in the docked Help window. If the Office Assistant isn't displayed, your topic will be displayed with the navigation pane expanded to show the Contents, Answer Wizard, and Index tabs. To make sure the Office Assistant is displayed, the code that displays your topic should set the Visible property of the Assistant object to True before it opens your topic.

To display Help for your solution, you must specify the path to the Help file that contains the topics you want to display. If you know where Help will be installed for your solution, you can hard-code the complete path to the file. However, if the exact path to your Help file isn't known, you must determine a way for your solution to find your Help file at run time. The simplest way to do this is to install your solution and Help file in the same folder, and then use the Path property of the application that is running to determine what folder the document or database was opened from. For example, this fragment of code uses the ActiveWorkbook property to return the current Excel Workbook object and the Path property to determine its location, and then appends the name of the Help file:

ActiveWorkbook.Path & "\sample.chm"

You can use the Path property the same way by using the ActiveDocument property or the Document object in Word, the ActivePresentation property or the Presentation object in PowerPoint, or the CurrentProject object in Access.

In UserForms and Access forms, you can display context-sensitive Help for interface elements and you can display standard Help topics from a Help button on the form. You can also display Help from a form's command bar by adding a toolbar button or menu item that displays a Help topic. In Word, Excel, and PowerPoint documents, you can display Help by using the Toolbox to insert a Help button in the document.

The method you use to implement context-sensitive Help in forms is very similar across all Office applications. Although the methods used for UserForms and Access forms differ slightly, essentially you specify property settings to identify the Help file that contains context-sensitive Help and then specify the context ID of the context-sensitive Help topic to display for each control.

The method you use to implement a Help button on a form or document depends on which Office application is hosting the form or document. In all cases, you run code triggered by the Click event of the Help command button, but the method used to call the Help topic differs depending on the application. In Excel and PowerPoint, you can use the Help method of the Application object to display a custom Help topic. In Word, the Help method of the Application object allows you to display only built-in Help, and Access has no such method. For this reason, implementing a Help button in both Word and Access requires you to use an API call to the HTML Help or WinHelp engine to display the Help topic. If you prefer to use the same method for displaying Help topics regardless of the application (for example, if you want to create code that will run in all four applications), you must use an API call to the Help engine.

Displaying Context-Sensitive Help in UserForms

Implementing context-sensitive Help for interface elements in UserForms is the same regardless of which Office application the form will be used with.

To define context-sensitive Help for UserForms

  • Create a WinHelp 4.0 Help file that contains the Help topics you want to display. For more information about creating a Help file, see "Creating a Help File to Use with an Office Solution" earlier in this chapter.
  • Open the Visual Basic Editor in the application you are working with.
  • In the Project Explorer, right-click the name of the VBA project for the document you are working with, and then click Project Properties.
  • In the Help File Name box, specify the full path and name of the Help file that contains context-sensitive Help topics.
  • If you don't want to include the full path to the Help file, omit steps 3 and 4 and add code to the form's Initialize event that specifies the path by using the HelpFile and Path properties of the document. For example:
    Dim strHelpPath As String
    strHelpPath = ActiveDocument.Path & "\samplepopups.hlp"
    ActiveDocument.VBProject.HelpFile = strHelpPath
  • Note You can specify only one Help file per VBA project. If you want to define context-sensitive Help for more than one UserForm or for class modules in the project, the Help file you specify must contain Help topics for all of these items.
  • Open the UserForm you want to work with, and set the form's WhatsThisButton and WhatsThisHelp properties to True.
  • For each control that you want to display context-sensitive Help for, set the control's HelpContextID property to the context ID of the Help topic you want to display for that control.

Displaying Context-Sensitive Help in Access Forms

Implementing context-sensitive Help for interface elements in Access forms is similar to the process of defining context-sensitive Help for UserForms, except the form and control properties you set are slightly different. In addition, you can specify different Help files for each form, and specify the window type in which to display the topic. To display the topic in a full WinHelp 4.0 Help window, enter the context ID as a positive value; that is, enter it exactly as it is defined in your .hlp file. To display the topic in a small borderless pop-up window that appears adjacent to the interface element, precede the context ID with a minus sign ( – ). Note that this does not mean you need to use negative values for context IDs when authoring your .hlp file; you need only precede the authored value with a minus sign.

To define context-sensitive Help for Access forms
  • Create a WinHelp 4.0 Help file that contains the Help topics you want to display. For more information about creating a Help file, see "Creating a Help File to Use with an Office Solution" earlier in this chapter.
  • Open the form you want to work with in Design view and display the form's property sheet. To do this, click Select Form on the Edit menu, and then click Properties on the View menu.
  • Click the Other tab, and then set the HelpFile property to the full path and name of the Help file that contains context-sensitive Help topics.
  • If you don't want to include the full path to the Help file, omit steps 2 and 3 and add code to the form's Load event that specifies the path by using the form's HelpFile property and the CurrentProject object's Path property. For example:
    Dim strHelpPath As String
    strHelpPath = CurrentProject.Path & "\samplepopups.hlp"
    Me.HelpFile = strHelpPath
  • In the form's property sheet, click the Format tab, set the MinMaxButtons property to None, and set the WhatsThisButton property to Yes.
  • For each control that you want to display context-sensitive Help for, set the control's HelpContextID property to the context ID of the topic you want to display for that control. To display the topic in a borderless pop-up window, precede the context ID with a minus sign ( – ).

Creating a Help Button

In Excel and PowerPoint, you can use the Help method of the Application object to display a custom Help topic. But in Word and Access, you must use a call to the HtmlHelp or WinHelp API. In either case, implementing a Help button in a UserForm, Access form, or document is simply a matter of adding a command button to the form or document and defining a line of code to specify the Help file and context ID of the topic you want to display.

To use the Help method of the Application object in Excel, you would add a line like the following to the Help button's Click event procedure: Application.Help ActiveWorkbook.Path & "\sample.chm", 2001 In PowerPoint, you would use the same line, but you'd use the ActivePresentation property to access the current path. For example: Application.Help ActivePresentation.Path & "\sample.chm", 2001 For more information about using the Help method of the Application object, see "Displaying Help by Using the Help Method" later in this chapter.

To use the HtmlHelp API to display a Help topic, you must include a function declaration to use the HtmlHelp API in the Declarations section of a form, class, or standard module, and then add a line of code like the following to the Help button's Click event procedure: Call HtmlHelp(0, ActiveDocument.Path &"\sample.chm", HH_HELP_CONTEXT, ByVal 2001&) For more information about using a call to the HtmlHelp API to display a Help topic, see "Displaying Help by Using the HtmlHelp API" later in this chapter.

In much the same way as forms, you can display both context-sensitive Help for custom command bar controls, and also call a standard Help topic when a user clicks a toolbar button or menu item. The same restrictions for displaying context-sensitive Help also apply to displaying standard Help topics: In Excel and PowerPoint, you can use the Help method of the Application object; in Word and Access, you must call the Help engine directly by using an API call.

Displaying Context-Sensitive Help for Command Bar Controls

To implement context-sensitive Help for a command bar control, you set the control's HelpFile property to the name of the Help file that contains the context-sensitive Help topic, and set the HelpContextID property to the context ID of the topic you want to display. There is no need to do this for built-in command bar controls used in custom command bars because they already have context-sensitive Help topics associated with them.

In all Office applications, you can set the HelpFile and HelpContextID properties by using VBA code. In Access, you can also set these properties through the user interface by clicking Customize on the Tools menu. The following code fragment sets these properties for a command bar control:

With ctlCBarControl
 .Caption = "M&y Help"
 .BeginGroup = True
 .FaceId = 0
 .OnAction = "DisplayHelp"
 .HelpFile = strAppPath & "\samplepopups.hlp"
 .HelpContextID = 1004
 .Visible = True 
End With

Displaying a Standard Help Topic from a Toolbar Button or Menu Item

Displaying a Help topic when a user clicks a toolbar button or menu item is similar to creating a Help button for a form. However, command bar controls don't provide a Click event, so you must first create a Sub or Function procedure that displays the Help topic, and then set the control's OnAction property to the name of that procedure. The same restrictions apply when you are creating a procedure to display a Help topic as when you are creating a Help button: You can use the Help method of the Application object to display a custom Help topic only in Excel and PowerPoint, but you must use an API call to HTML Help to display a custom Help topic in Word and Access.

For more information about creating command bars and command bar controls, see Chapter 6, "Working with Shared Office Components." You can use the Office Assistant to display a balloon that allows users to access custom Help topics. If you have the Answer Wizard SDK, you can also integrate your custom Help topics with the built-in Help topics provided with Office.

Displaying Help Topics from an Office Assistant Balloon

You can use the Assistant to display a balloon containing buttons and labels that users can click to open custom Help topics. As with other methods of displaying custom Help topics, you can use the Help method of the Application object to display a custom Help topic in Excel and PowerPoint, but you must use an API call to HTML Help to display a custom Help topic in Word and Access.

The following procedure can be used from Excel or PowerPoint (if you replace ActiveWorkbook.Path with ActivePresentation.Path) to display a Help balloon with labels and buttons for two topics:

Sub HelpFromAssistant() 
Dim intTopic As Integer 
Dim blnVisible As Boolean 
Dim strMsg As String 
blnVisible = Assistant.Visible ' Determine if the Assistant is already visible. 
If blnVisible = False Then With Assistant .Visible = True .Animation = msoAnimationIdle End With 
Else Assistant.Animation = msoAnimationIdle 
End If ' Display Help balloon with two buttons and store user's ' selection in intTopic.
With Assistant.NewBalloon
 .BalloonType = msoBalloonTypeButtons
 .Heading = "Displaying Help Topics"
 .Text = "Select a topic:"
 .Labels(1).Text = "Topic One"
 .Labels(2).Text = "Topic Two"
 .Button = msoButtonSetCancel
 .Mode = msoModeModal
  intTopic = .Show 
End With 
' Determine which button the user clicked and display the Help 
' topic. This code works only in Excel 2000 because it refers to 
' a .chm file. Replace with a WinHelp 4.0 .hlp file if you also 
' need this code to run in Excel 97. 
Select Case intTopic 
Case 1 Application.Help ActiveWorkbook.Path & "\sample.chm", 2001 
Case 2 Application.Help ActiveWorkbook.Path & "\sample.chm", 2002 
End Select 
End Sub

The HelpFromAssistant procedure is available in the modHTMLHelp module in ExcelHelp.xls in the Samples\CH13 subfolder on the companion CD-ROM. The same code can be used from Word or Access if you replace the calls to the Help method of the Application object with calls to the HtmlHelp API to display the topics. For Word, the Select Case statements would look like this: Select Case intTopic Case 1 Call HtmlHelp(0, ActiveDocument.Path & "\sample.chm", HH_HELP_CONTEXT, _ ByVal 2001&) Case 2 Call HtmlHelp(0, ActiveDocument.Path & "\sample.chm", HH_HELP_CONTEXT, _ ByVal 2002&) End Select

In Access, you would use the Path property of the CurrentProject object to display a topic from a compiled HTML Help file located in the same folder as the current database. For example:

Call HtmlHelp(0, CurrentProject.Path & "\sample.chm", HH_HELP_CONTEXT, ByVal 2001&)

For more information about working with the Office Assistant, see Chapter 6, "Working with Shared Office Components."

Using the Assistant with Access Run-Time Applications

If you are creating an Access run-time application and installing it on a computer that does not have Office installed, the Assistant object is not available. However, the Office Assistant is based on the Microsoft Agent ActiveX control, which is freely distributable. For Access run-time applications, you can use the Agent control to provide the full range of Assistant services without accessing the Assistant's object model. For more information about using the Agent control, see the Microsoft Agent Web site at http://www.microsoft.com/intdev/agent .

If Office is not installed on the computer where your Access run-time application will be used, you may also need to install HTML Help components. For more information, see the "Redistributing HTML Help Components" sidebar earlier in this chapter.

Creating an Answer Wizard Index to Display Custom Help Topics from the Office Assistant

If you purchased Office 2000 Developer or the Microsoft Office 2000 Resource Kit (Microsoft Press, 1999), you can use the Microsoft Answer Wizard Builder available with the Answer Wizard SDK to create a custom Answer Wizard index with references to your custom Help topics. When this custom Answer Wizard index is installed with your solution, if a user asks a question that applies to your solution, your custom Help topics will be displayed along with those built-in Help topics returned by the Office Assistant. This way of integrating Help topics is most appropriate for Office solutions that are deployed as add-ins. For information about the Answer Wizard SDK, see the Microsoft Office 2000 Resource Kit (Microsoft Press, 1999) or Office 2000 Developer.

The Microsoft Office 9.0 object library provides methods for the AnswerWizard and AnswerWizardFiles objects that allow developers to control when a custom Answer Wizard index is used by the Office Assistant to return custom Help topics. For information about these objects and methods, search the Microsoft Office Visual Basic Reference Help index for "AnswerWizard object" and "AnswerWizardFiles object."

As mentioned earlier in this chapter, there are two ways to display a custom Help topic from code. In Excel and PowerPoint, you can use the Help method of the Application object, but in Word and Access you must use an API call to HTML Help or to WinHelp to display the Help topic. For this reason, if you need to use the same code across applications, you must use an API call. The following sections describe how to do both, and also detail how to display Help topics from the InputBox and MsgBox functions, how to display Help topics when error messages are displayed, and how to associate Help topics with properties and methods in class modules.

Displaying Help by Using the Help Method

The Help method of the Application object can be used from Excel and PowerPoint to display a custom Help topic. You can invoke the Help method from practically any context, but it is most commonly used to display a Help topic from a command button or from a menu item or toolbar button. You use the following syntax to call the Help method expression.Help(HelpFile, HelpContextID) where expression returns an Application object, HelpFile is the name of either a .chm or .hlp file, and HelpContextID is the context ID of the topic you want to display. The HelpFile argument must include the full path to the file.

For example, the following code fragment opens the Help file Sample.chm in the current folder of the active Excel workbook and displays the topic mapped to context ID 2001:

Application.Help ActiveWorkbook.Path & "\sample.chm", 2001

While you can't display a custom Help topic by using the Help method of the Application object in Word, you can use it to display built-in Help. For more information about how to do this, search the Microsoft Word Visual Basic Reference Help index for "Help method."

Displaying Help by Using the HtmlHelp API

Because the current implementation of the HTML Help ActiveX control can't be inserted in a form and doesn't provide Component Object Model (COM) interfaces, you must call its API directly if you need to use features beyond those supported by the methods and properties available in VBA. Because Word and Access don't currently provide a built-in method for displaying custom Help topics, you must use the HtmlHelp API to display a custom Help topic in those applications.

Before you can use an API call from VBA code, you must create a function declaration in the Declarations section of a form, class, or standard module. The HtmlHelp API requires a single function declaration that looks like this:

Declare Function HtmlHelp Lib "HHCtrl.ocx" Alias "HtmHelpA" _ 
(ByVal hwndCaller As Long, _ 
ByVal pszFile As String, _ 
ByVal uCommand As Long, _ 
dwData As Any) As Long

This declaration uses the ANSI version of the HtmlHelp function exported by HHCtrl.ocx. For more information about using API calls from VBA, see Chapter 10, "The Windows API and Other Dynamic-Link Libraries." The arguments of the HtmlHelp function provide the following functionality.

Argument Description

hwndCaller
A handle to an application window or Null. This window handle may be used as a parent, owner, or message recipient for HTML Help, depending on how it is used. In VBA, instead of setting this to vbNullString, set it to 0 (zero).

pszFile
File to display; optionally also specifies which window type to display it in, delimited with the right angle bracket character (filename>windowtype). If you omit the window type, the HtmlHelp function will use the default window type specified in the HTML Help project file. For uCommand values that don't require a source file, pszFile can be Null, or 0 (zero), in VBA. However, a compiled HTML Help file is typically specified.

uCommand
The action to perform; see the remainder of this section for examples of how to display a Help topic by using either the HH_HELP_CONTEXT or HH_DISPLAY_TOPIC command.

dwData
Specifies additional data depending on the value of uCommand. Note that in this declaration this argument is declared As Any, because this argument accepts several different data types. You must be careful to pass the correct data type or risk an invalid page fault (also known as general protection fault [GPF]).

The HtmlHelp function supports a broad variety of HTML Help functionality and provides detailed control unavailable through other programmatic means. The rest of this section describes how to use the HtmlHelp function to display a custom Help topic. For more information about using other commands with the uCommand argument, see the HtmlHelp API Reference in the Help system for HTML Help Workshop.

To make using the HtmlHelp function from VBA simpler, in addition to the function declaration, you should also declare the following constants to pass as the uCommand argument:

Const HH_DISPLAY_TOPIC = &H0 Const HH_HELP_CONTEXT = &HF

The constants in the following table are used to specify which uCommand command to use with the HtmlHelp function to display a Help topic.

uCommand command

Description

HH_DISPLAY_TOPIC
Displays a Help topic by passing the name of the HTML file that contains the topic as the dwData argument.

HH_HELP_CONTEXT
Displays a Help topic by passing the mapped context ID for the topic as the dwData argument.

The command you choose to use depends on whether you have mapped context IDs for each topic as described earlier in this chapter in "Creating a Help File to Use with an Office Solution." If you haven't created context IDs, you must use the HH_DISPLAY_TOPIC command. If you have created context IDs, you can use either command.

When you are using either command from an Office application, you should pass 0 (zero) as the hwndCaller argument so that HTML Help will display the Help topic in sibling mode. Sibling mode (shown in Figure 13.2) causes HTML Help to display Help topics in a separate top-level overlapped Help window that is displayed alongside the calling application. The user can freely switch between the application and the Help window.

Figure 13.2 Sibling Mode

The following line of code shows how to display a Help topic by using the HH_DISPLAY_TOPIC command:

Call HtmlHelp(0, "c:\help\Sample.chm", HH_DISPLAY_TOPIC, By Val "Topic1.htm")

This code will display the topic authored in Topic1.htm, which is compiled in the Sample.chm file. Because no window type was specified for the pszFile argument, the topic will be displayed by using the default window type specified in the HTML Help project file that was used when the Help file was compiled.

The following line of code shows how to display a Help topic by using the HH_HELP_CONTEXT command:

Call HtmlHelp(0, "c:\help\Sample.chm>mso_small", HH_DISPLAY_TOPIC, By Val 2001&)

This code will display the topic specified by the mapped context ID 2001 in the Sample.chm file. The ampersand (&) following the context ID is required to specify that the value being passed to the HtmlHelp function is a Long data type. The topic will be displayed by using the mso_small window type specified in the pszFile argument. In order for this line of code to work correctly, the mso_small window type must be specified in the HTML Help project file that was used when the Help file was compiled. Displaying Help by Using the InputBox and MsgBox Functions Both the InputBox and MsgBox functions provide optional helpfile and context arguments that can be use to display a Help topic when a user clicks the Help button or presses F1. To display a custom Help topic, you must specify both optional arguments. The helpfile argument is a string value that specifies the Help file that contains the topic you want to display. This argument can accept either a .chm or .hlp file. The context argument specifies the mapped context ID of the topic to display.

If you specify the helpfile and context arguments when you are using the InputBox function, a Help button will automatically be added to the dialog box created by the InputBox function. If you specify the helpfile and context arguments when you are using the MsgBox function, you must also specify the vbMsgBoxHelpButton built-in constant in the buttons argument in order to add a Help button to the dialog box created by the MsgBox function.

The following code fragment shows how to display a Help topic when you are using the InputBox function:

InputBox Prompt:="Enter data", _ HelpFile:=strAppPath & "\sample.chm", _ Context:="2001"

The following line of code shows how to display a Help topic when you are using the MsgBox function:

MsgBox Prompt:= "You must enter a valid date.", _ Buttons:=vbMsgBoxHelpButton, _ HelpFile:= strAppPath & "\sample.chm", _ Context:= "2002"

The InputBox and MsgBox functions allow you to display a Help topic contained in a compiled HTML Help file in all Office applications, including Word and Access. There is no need to use the HtmlHelp API to display a Help topic in a .chm file when you are using these functions in Word and Access.

Displaying Help for Custom Error Messages

The Raise method of the Err object has optional helpfile and helpcontext arguments that set the HelpFile and HelpContext properties of the Err object to the specified Help file name and context ID when your custom error is triggered. If the error trap in your procedure then passes these values to the MsgBox function, you can add a Help button to call additional Help from your error message dialog box. The following code example shows how to do this:

Sub ShowErrorHelp()
Dim strAppPath As String
strAppPath = ActiveDocument.Path
On Error GoTo ShowErrorHelp_Err
Err.Raise Number:=vbObjectError + 1234, _
Source:="Sub ShowErrorHelp", _
Description:="This error has a reason.", _
HelpFile:=strAppPath & "\sample.chm", _
HelpContext:=2003
ShowErrorHelp_End:
Exit

Sub ShowErrorHelp_Err:
MsgBox Prompt:=Err.Description, _
Buttons:=vbMsgBoxHelpButton, _
HelpFile:=Err.HelpFile, _
Context:=Err.HelpContext Resume ShowErrorHelp_End
End Sub

The ShowErrorHelp procedure is available in the modHTMLHelp module in the WordHelp.doc in the Samples\CH13 subfolder on the companion CD-ROM. The helpfile and helpcontext arguments of the Raise method support using a compiled HTML Help file in all Office applications, including Word and Access. There is no need to use the HtmlHelp API to display a Help topic in a .chm file when you are using the Raise method to return a Help file name and context ID in Word and Access.

Displaying Help for Properties and Methods in Class Modules

You can also add Help information for the custom properties and methods in your class modules. If you do so, Help can be displayed for these properties and methods by pressing F1 when they are viewed in the Object Browser or used in a procedure. This feature is useful if you will be distributing your applications to other developers.

To provide Help for properties and methods in a class module

  • Create a Help file that contains the topics you want to display and maps each topic to a numeric context ID. For more information about creating a Help file, see "Creating a Help File to Use with an Office Solution" earlier in this chapter.
  • Open the Visual Basic Editor in the application you are working with.
  • In the Project Explorer, right-click the name of the VBA project for the document you are working with, and then click projectname Properties.
  • In the Help File Name box, specify the name of the Help file that contains the Help topics. If you don't include the full path, Help will be displayed as long as the Help file is installed in the same folder as your solution.
  • Note You can specify only one Help file per VBA project. If you want to define context-sensitive Help for more than one class module or for UserForms in the project, the Help file you specify must contain topics for all of these items.
  • Open the Object Browser, and then click the name of your class module in the Classes box.
  • In the Members Of box, right-click a property or method, and then click Properties.
  • In the Member Options dialog box, type the context ID of the topic to display in the Help Context ID box. You can also type a description that will display in the Object Browser in the Description box.
  • Repeat steps 6 and 7 for each property and method in your class module.

The WordHelp.doc file in the Samples\CH13 subfolder on the companion CD-ROM contains a class module (clsTimerClass) that has Help topics associated with its properties and methods. In addition, the modTimerHelp module demonstrates how to display these Help topics from a procedure. Using HTML Help to Author a Web Site There are two ways to use HTML Help functionality when authoring Web sites. You can:

  • Use the HTML Help ActiveX control or the HTML Help Java applet to implement navigation to documents on your Web site by using a hierarchical table of contents tree control or an index.
  • Use HTML Help Workshop to create a compiled HTML Help file, and then create URLs to display HTML pages from the compiled HTML Help file in Internet Explorer.

To implement navigation by using the HTML Help ActiveX or the HTML Help Java applet, you first create the HTML files and other documents you want to use from your Web site. Then you use HTML Help Workshop to create table of contents and index files to navigate to your documents. Finally, you insert the control or applet in a Web page and use it to display the table of contents and index you created. Typically a Web site authored by using the HTML Help ActiveX control or Java applet uses a custom frameset to produce similar functionality to the freestanding HTML Help Viewer. Displaying an HTML page from a compiled HTML Help file simply requires you to format the appropriate URL to open and display the HTML file. Framesets are a way of specifying multiple independent regions, called frames, within a browser window. Each frame in a frameset displays a separate HTML document. You can have frames that scroll and resize, depending on how you author the frameset. You assign each frame a name, so that links from one frame can jump to another frame.

After you have created a frameset, you add the HTML Help ActiveX control or the HTML Help Java applet (discussed in the following section) to the frames that you want to have HTML Help functionality. For example, one frame can use the HTML Help ActiveX control to display a table of contents that, when clicked, displays an HTML page or Office document in an adjoining frame.

You can use the HTML Help ActiveX control to add the following functionality to HTML pages displayed in your frameset:

  • A table of contents
  • An index
  • Related topic links
  • A splash screen
  • Pop-up windows that display simple text strings without formatting

Figure 13.3 shows an example of a frameset in which the HTML Help ActiveX control is used to display a contents or index pane in the left frame.

Figure 13.3 A Frameset Authored by Using the HTML Help ActiveX Control

You can author the HTML files that make up the topics for an HTML Help frameset in whatever editor you choose, but to insert the HTML Help ActiveX control in your pages, it is recommended that you use the HTML Help Control command on the Tags menu of HTML Help Workshop. For more information about using the HTML Help ActiveX control, see "Working with the HTML Help ActiveX Control" earlier in this chapter.

You should author the files used to create the table of contents (.hhc) and index (.hhk) in HTML Help Workshop, but once you understand their format, you can update and modify them by using a text editor, if you want. The .hhc and .hhk files themselves (not a compiled HTML Help file that contains compiled versions of them) must be copied to your Web site in order to support a table of contents and index. Unlike a compiled index, an HTML Help index file used on a Web site can't merge keywords from other indexes or use keyword links (KLinks).

To view a sample frameset that uses the HTML Help ActiveX control to display a table of contents and index for navigation to HTML files and Office documents, see HTMLHelpActiveX.htm in the Samples\CH13\Frameset subfolder on the companion CD-ROM.

Working with the HTML Help Java Applet

If you need to have compatibility with browsers that don't support ActiveX controls, you can add HTML Help functionality to Web pages by using the HTML Help Java applet.

You can use the HTML Help Java applet to add the following HTML Help features to HTML pages displayed in your frameset:

  • A table of contents
  • An index
  • Related Topics links

Note that the HTML Help Java applet doesn't support displaying text pop-up windows. To create similar functionality, you can use the JavaScript alert method of the window object to display a dialog box that contains a text string. For example, the following JavaScript displays a simple pop-up message:

<P>This is a <A HREF='JavaScript:alert("This a JavaScript message.")' TITLE="This is a JavaScript message.">pop-up</A>.</P>

The TITLE attribute of the <A> tag provides a pop-up window for browsers that support this functionality. To use the HTML Help Java applet from an HTML page, insert an <APPLET> tag similar to the one in the following example:

<APPLET CODE=HHCtrl.class ALIGN="baseline" WIDTH=240 HEIGHT=270 NAME=HHCtrl ARCHIVE="HHCtrl.zip"> 
<PARAM NAME="Cabbase" VALUE="HHCtrl.cab"> 
<PARAM NAME="Command" VALUE="Contents"> 
<PARAM NAME="Item1" VALUE="hh_toc_java.hhc"> 
</APPLET>

The CODE attribute specifies HHCtrl.class, which is the name of the Java class used to load the HTML Help Java applet. Netscape Navigator uses the ARCHIVE attribute to specify a .zip file that contains Java class files. In this case, HHCtrl.zip contains all the Java class files required by the HTML Help Java applet. Similarly, the Cabbase parameter is used by Microsoft Internet Explorer to specify the name of a compressed archive that contains Java class files, in this case in the .cab file format. A copy of HHCtrl.cab is installed in the C:\Program Files\HTML Help Workshop\Java subfolder when you install HTML Help Workshop. You can create your own .zip archive by compressing all the .class files included in the Java subfolder.

The Command parameter is used to specify the kind of HTML Help functionality to be used with this instance of the HTML Help Java applet. You can specify the following commands.

Command Description

Contents
Specifies that a table of contents will be displayed based on the information supplied in the HTML Help table of contents file specified in the Item1 parameter (normally an .hhc file). The specified file must reside in the same folder as the document containing the applet. You must also include a copy of cntimage.gif (from the C:\Program Files\HTML Help Workshop\Java folder created when you install HTML Help Workshop) to display folder and document icons in the table of contents tree view.

Index
Specifies that an index will be displayed based on the information supplied in the HTML Help index file specified in the Item1 parameter (normally an .hhk file). The specified file must reside in the same folder as the document containing the applet.

Related Topics
Specifies that a dialog box listing related topics will be displayed based on the information supplied in one or more Itemn parameters in this format:
<PARAM NAME="Itemn" VALUE="TopicTitle;TopicFile.htm">

You can see additional parameters supported by the Contents, Index, and Related Topics commands by opening an HTML file in HTML Help Workshop, and then clicking HTML Help Control on the Tags menu. A wizard that is used to insert the HTML Help ActiveX control appears. You can select the Table of Contents, Index, or Related Topics command from this wizard to insert an <OBJECT> tag for the selected command. Most of the parameters supported by the <OBJECT> tag for the HTML Help ActiveX control can be used with the corresponding command for the HTML Help Java applet.

To view a sample frameset that uses the HTML Help Java applet to display a table of contents and index for navigation to HTML files and Office documents, see HTMLHelpJava.htm in the Samples\CH13\Frameset subfolder on the companion CD-ROM.

You can use a URL to open an HTML page in a compiled HTML Help file from Internet Explorer or an Office hyperlink. The kind of URL you use depends on which version of Internet Explorer users have installed, and whether the compiled HTML Help file is being opened directly from the file system or from an HTTP server.

When you are using Internet Explorer versions 3.x or later, you can open a specific HTML page contained in a compiled HTML Help file from the file system by using a URL in this format:

mk:@MSITStore:path\filename.chm::\page.chm

When you are using Internet Explorer versions 4.x or later, you can open an HTML page in a compiled HTML Help file from the file system by using a URL in this format:

its:path\filename.chm::/page.chm

For example, you can open the first page in the compiled HTML Help file installed for the Internet Explorer 4.x or later Help system by using this URL:

its:c:\windows\help\iexplore.chm::/iexplore_welcome.htm

When you are using Internet Explorer 4.x or later, you can open a page in a compiled HTML Help file located on an HTTP server by using a URL in this format:

its:http://serverpath/filename.chm::/page.htm

Where to Go from Here

For additional information about the subjects discussed in this chapter, see the following sources.

HTML Help

HTML Help Web site (http://www.microsoft.com/workshop/author/htmlhelp/default.asp)

HTML Help ActiveX Control Reference Web site (http://www.microsoft.com/workshop/author/htmlhelp/hharef.asp)

Steve Wexler. Official Microsoft HTML Help Authoring Kit. Redmond, WA: Microsoft Press, 1998.

WinHelp 4.0

Microsoft Windows 95 Help Authoring Kit. Redmond, WA: Microsoft Press, 1995.

Microsoft Help Workshop (download from the Microsoft Technical Support Web site at http://support.microsoft.com/download/support/mslfiles/hcwsetup.exe)

Answer Wizard SDK

Microsoft Office 2000 Resource Kit Web site (http://www.microsoft.com/office/ork/)

Microsoft Office 2000 Resource Kit. Redmond, WA: Microsoft Press, 1999.

Code Samples

The code samples shown in this chapter, along with sample Help files, can be copied from the files in the Samples\CH13 subfolder on the companion CD-ROM. Additional sample files for this chapter are located in the Samples\CH13\Frameset and Samples\CH13\Help Source subfolders.

Last updated January 12, 2000
© 2000 Microsoft Corporation. All rights reserved. Terms of use.

Last modified: 11.07.2010