Indigoware White Paper

How to Add Context-Sensitive Help to

Excel VBA Applications

Why add context-sensitive Help?

Adding context-sensitive Help can greatly improve the usability of your Microsoft
Excel Visual Basic for Applications (VBA) based applications by making it easier
for users to teach themselves how to use the application. The benefits are
twofold; users gain additional benefits by using more features of the application
and support costs are reduced.
If the development team or technical authors have gone to the trouble of writing a
comprehensive Help file, then it makes sense to make the small extra effort
required to make the information it contains as easy for the user to access as
possible. By using Indigoware’s Help Publisher for FrontPage in conjunction with
Excel VBA, providing context-sensitive Help can be a straight forward task.

How users can access context-sensitive Help

There are two main methods for users to access context-sensitive Help in Excel
VBA-based applications:
• Through a Help button on a form or message box.
• By adding a menu item or toolbar button.
• Through the ‘Insert Formula’ dialog box when inserting or editing added
custom functions.
‘F1 Help’ (usually invoked by pressing the F1 key) and ‘What’s This Help’
(invoked by clicking the ‘?’ button on a form’s title bar) are not possible in Excel
VBA applications due to incomplete implementations in VBA.

Example application
A zipped archive containing a simple Excel VBA application is available from
http://indigoware.com/developers which demonstrates all the techniques
described in this paper. It was produced using Microsoft Excel 2003 together
with Help Publisher for FrontPage version 2.2.

Excel VBA support for context-sensitive Help

Although UserForms have properties called ‘WhatsThisButton’ and
‘WhatsThisHelp’, VBA cannot actually support What’s This Help with HTML Help
files (Microsoft’s current Help file format and the type of Help file produced by
Help Publisher). These properties are a legacy from VBA’s support of Microsoft’s
previous Help file format WinHelp. Additionally VBA’s support for trapping when
the F1 key is pressed is very limited, making it difficult to provide Help when the
F1 key is pressed on a UserForm.
The good news however is that Excel VBA does have a built-in function for
displaying a specific Help topic in an HTML Help file. This makes it straight
forward to provide users with rich context-sensitive help for your Excel VBA-
based applications.

V1.1 Copyright © 2004 Indigoware Ltd Page 1 of 6

 Adding Help to Excel VBA Applications

Additionally it is possible to link the ‘Insert Function’ dialog (displayed by pressing

the button) to specific Help file topics for custom functions.
The approach used by Excel VBA to manage context-sensitive Help is based on
Help Context Ids.

What are Help Context Ids?

Help Context Ids are reference numbers used by the programmer to tell the
HTML Help viewer which Help topic to display. Although most VBA user
interface elements have a property called HelpContextID, of type Long integer,
which in theory can be set to a value which matches the Help Context Id of a
topic in the Help file, Excel VBA is unable to make use of this property (unlike
Visual Basic 6.0), so it is not worth setting it in Excel VBA applications.
Help Context Ids are still required however as a parameter of the various VBA
functions that support context-sensitive Help.
For example, if the Application.Help function is called with its HelpContextID
property set to 1000, then the Help topic which is associated with Help Context Id
1000 will be displayed. If no Help topic is associated with the given Help Context
Id an error will occur and the Help file's default topic will be displayed.

Mapping Help topics to Help Context Ids

The mapping between Help Context Ids and Help file topic pages is defined in
the .HHP Help project file which is used by the Help compiler. You can create
and edit .HHP files using HTML Help Workshop, however if you use Help
Publisher for FrontPage it will take care of creating the .HHP file automatically.

Using Help Publisher for FrontPage with a Excel VBA Project

Although it is possible to produce a Help file using only Microsoft’s HTML Help
Workshop utility, the task is a lot easier using Microsoft FrontPage together with
Indigoware’s Help Publisher add-in.
• You can then use FrontPage’s HTML editor to write the Help topics rather
than HTML Help Workshop’s own very basic HTML editor.
• You can use all of FrontPage’s additional functionality such as link and
spell checking.
• If you are using FrontPage 2003 you can use Dynamic Web Templates
making it easy to give your topic pages a consistent look and feel.
• You can use Help Publisher for FrontPage to manage the contents and
index, add navigation buttons, and even add ‘See Also’ menus, from
within FrontPage.
• Help Publisher for FrontPage can manage the mapping between topic
pages and Help Context Ids.
By using Help Publisher for FrontPage it is therefore unnecessary to edit the
HHP file directly or use the often buggy and complicated HTML Help Workshop
interface.

V1.1 Copyright © 2004 Indigoware Ltd Page 2 of 6

 Adding Help to Excel VBA Applications

Creating and editing the Help file with Help Publisher for FrontPage
To edit the Help file using Help Publisher for FrontPage:
1. Create a new FrontPage web site to contain the Help file topics.
2. Enable Help Publisher in this web site by selecting 'Enable Help Publisher
in Web Site' from the 'Help Publisher' menu in FrontPage.
3. Create and edit the Help topic pages just as if you are editing a normal
FrontPage web site.
4. Select ‘Project Options’ from the ‘Help Publisher menu. In the ‘Compiled
HTML Help Filename’ field on the ‘General’ tab, set the filename and
location of the compiled Help file. A good location is within the same
directory as the Excel workbook that contains the VBA code.
5. To compile the web site into a compiled HTML Help file select ‘Compile
HTML Help File’ from the ‘Help Publisher’ menu.
If you have an existing Help file you can import it into Help Publisher for
FrontPage using the Import wizard. See Help Publisher’s own Help file for
further information.

Assigning Help Context Ids to Help topic pages

Help Context Ids can be assigned to Help topic pages using the ‘Help Context
Ids’ view of the Context Ids Editor. Alternatively they can be set from a Help
topic page’s Page Options dialog (select 'Page Options' from the 'Help Publisher'

V1.1 Copyright © 2004 Indigoware Ltd Page 3 of 6

 Adding Help to Excel VBA Applications

menu) by clicking 'Add' in the Context Id section. The Help Context Id names
can either be a number or the name of a constant.
Help Publisher for FrontPage can generate a Visual Basic module file containing
all the Help Context Ids assigned in the Help file.
To enable this option:
1. Select 'Context Ids Editor' from the 'Help Publisher' menu.
2. Select the 'Export File' view.
3. Set the 'Development Language' field to 'Visual Basic 6.0'.
4. In the 'Generated Module Filename' field, enter the desired filename for
the generated VB6 module.
5. Recompile the Help project using Help Publisher for FrontPage.
6. Import the generated Visual Basic module to your Excel VBA project.
Note that it is necessary to re-import the Visual Basic module into your Excel
VBA project in order to pick up any changes to the module file made by Help
Publisher for FrontPage.

V1.1 Copyright © 2004 Indigoware Ltd Page 4 of 6

 Adding Help to Excel VBA Applications

Adding a Help button to a UserForm

You can use the Application.Help function to display a relevant Help topic when
the user presses a Help button on a form. The following helper routine
demonstarates how to call this function. Avoid calling Application.Help with
HelpContextID equal to 0, as it causes an additional instance of the HTML Help
viewer to appear.

Public Sub DisplayHelp(Optional ContextID As Long = 0)

If ContextID = 0 Then
Application.Help ThisWorkbook.Path & "\HelpFile.chm"
Else
Application.Help ThisWorkbook.Path & "\HelpFile.chm", ContextID
End If

End Sub

Then add the following Help button Click event handler to the UserForm
(assumes the relevant Help topic is associated with Help Context Id 1010):

Private Sub cmdHelp_Click()

DisplayHelp 1010
End Sub

Run your Excel VBA application and you will now find that when the Help button
is pressed the relevant Help file topic is displayed.

Linking a Help topic to a custom function

Excel’s facilities for adding custom functions can be extremely useful. However
added functions can also be extremely cryptic for users. By creating a Help topic
documenting the custom function the user can gain assistance on using the
function by clicking ‘Help on this function’ in the ‘Insert Function’ and ‘Function
Arguments’ dialog boxes.
The link between the custom function and the Help topic is by using the HelpFile
and HelpContextID parameters of the Application.MacroOptions method as
shown below:

Application.MacroOptions Macro:="CAGR", Category:=Financial, _

Description:="Returns the Compound Annual Growth Rate", _
HelpFile:=ThisWorkbook.Path & "\HelpFile.chm", _
HelpContextID:=1011

See the example application and Excel’s own Help topic on the
Application.MacroOptions method for further details.

V1.1 Copyright © 2004 Indigoware Ltd Page 5 of 6

 Adding Help to Excel VBA Applications

Handling Help with MsgBox() and InputBox()

The final method of adding context-sensitive Help to a Excel VBA application is
when a message box is being displayed. Excel VBA’s MsgBox() and InputBox()
functions can optionally display a Help button if you:
• Include vbMsgBoxHelpButton in the buttons parameter (MsgBox() only).
• Set the HelpFile parameter to the Help file’s path.
• Set the Context parameter to the Help Context Id of the Help topic you
wish to display when the Help button is pressed.
The following code snippet shows an example:

' Display a message box with a help button linked to a help topic
MsgBox "Press the help button for further details.", _
Buttons:=vbOKOnly Or vbMsgBoxHelpButton, _
HelpFile:=ThisWorkbook.Path & "\HelpFile.chm", _
Context:=1012

Matching the style of Excel’s Help file

Microsoft has made available a couple of Cascading Style Sheets to give your
Microsoft Office-based Help files the same look and feel as the ones supplied by
Microsoft. They can be downloaded from:
http://www.microsoft.com/office/ork/xp/appndx/appa06.htm

Conclusion
Excel VBA provides the basic functionality necessary to support context-sensitive
Help. By following the techniques described in this paper, the information
contained in the Help file can be made available to the user in a more accessible
form.
The combination of using Indigoware’s Help Publisher for FrontPage with Excel
VBA can make the task of producing professional Help files that support context-
sensitive Help much easier.
If you are not already familiar with how to use Help Publisher for FrontPage to
edit the Help file’s contents and index, or how to add ‘See Also’ menus, now is a
good time to take the tutorial supplied with Help Publisher for FrontPage.

Free Trial
For a free trial version of Help Publisher for FrontPage visit:
http://indigoware.com/download.

Microsoft, Excel, Visual Basic and FrontPage are either registered trademarks or trademarks of
Microsoft Corporation in the United States and/or other countries.

V1.1 Copyright © 2004 Indigoware Ltd Page 6 of 6