Installation of the Microsoft HTML Help SDK

The HTMLHelp SDK is not provided with Visual Studio, at least not version 6. So if you have not installed it separately then you need to, as described in Installing HTML Help. Then look at my Introduction to HTMLHelp article if you need help getting started writing HTML Help files. Then set up the VC environment as described in Including HTML Help Support Files in an Application.

Program Modifications

The following is my version of how to modify a MFC application to use HTMLHelp.

Modifying the Resources

First create string resources to be used as prompts for the menus. Add the following ids with these strings or whatever other strings you choose. The resource editor will probably use the correct “Value” so you should not need to be concerned about that. I don’t know if it matters whether the exact values I show here must be used. Also it is probably not necessary to use all 6, probably only ID_HELP_CONTENTS, ID_HELP_INDEX and ID_HELP_SEARCH are necessary.
ID
Value
Caption
ID_HELP_INDEX
57666
Display the Index of the Help file\nDisplay Index
ID_HELP_FINDER
57667
List Help topics\nHelp Topics
ID_HELP_USING
57668
Display instructions about how to use help\nHelp
ID_HELP
57670
Shows the help file
ID_HELP_SEARCH
57671
Display the Search tab of the Help file\nDisplay Search
ID_HELP_CONTENTS
57672
Display the Table of Contents of the Help file\nDisplay Contents
Next add the following to a menu: ID_HELP_CONTENTS, ID_HELP_INDEX and ID_HELP_SEARCH. It is necessary to add them to a menu first since otherwise they will not be available in the ClassWizard to add handlers for them.

Modifying the Application

In your application’s InitInstance add the following so that the help file path and filename are set automatically. This assumes that your chm file is the same filename as your exe file except with a chm extension instead of the exe extension. It should also be in the same directory. That is the convention MFC uses and the following will just change the extension from hlp to chm. Next this code verifies that the chm file exists.

	CString strHelpFile = m_pszHelpFilePath;
strHelpFile.MakeLower();
if (strHelpFile.Right(4) == ".hlp") {
	strHelpFile = strHelpFile.Left(strHelpFile.GetLength()-4) + ".chm";
	free((void*)m_pszHelpFilePath);
	m_pszHelpFilePath = _tcsdup(strHelpFile);
	}
CFileStatus FileStatus;
if (!CFile::GetStatus(m_pszHelpFilePath, FileStatus)) {
	CString Message("Help file not found:\r\n");
	AfxMessageBox(Message+m_pszHelpFilePath);
	return FALSE;		// Optional; this can be removed
	}

Modifying CMainFrame

Use ClassWizard to add handlers for ID_HELP_CONTENTS, ID_HELP_INDEX and ID_HELP_SEARCH then modify them as follows. I don’t know where I got the following code for OnHelpSearch from and I am not sure what it does. I should get answers to both those questions.

void CMainFrame::OnHelpContents() {
HWND hWnd = HtmlHelp(0, AfxGetApp()->m_pszHelpFilePath, HH_DISPLAY_TOC, NULL);
}
void CMainFrame::OnHelpIndex() {
HWND hWnd = HtmlHelp(0, AfxGetApp()->m_pszHelpFilePath, HH_DISPLAY_INDEX, NULL);
}
void CMainFrame::OnHelpSearch() {
HH_FTS_QUERY q;
memset(&q, 0, sizeof(HH_FTS_QUERY));
q.cbStruct = sizeof(HH_FTS_QUERY);
q.fUniCodeStrings = FALSE;
q.pszSearchQuery = "";
q.iProximity = HH_FTS_DEFAULT_PROXIMITY;
q.fStemmedSearch = FALSE;
q.fTitleOnly = FALSE;
q.fExecute = TRUE;
q.pszWindow = NULL;
HWND hWnd = HtmlHelp(0, AfxGetApp()->m_pszHelpFilePath, HH_DISPLAY_SEARCH, (DWORD)&q);
}

Then use ClassWizard again to override WinHelp, which is a virtual function, and then modify it as follows.

void CMainFrame::WinHelp(DWORD dwData, UINT nCmd) {
HWND hWnd = HtmlHelp(m_hWnd, AfxGetApp()->m_pszHelpFilePath, nCmd, dwData);
}

Custom Build Step

It is very convenient to have a custom build step for your chm file so that if you change it then it gets copied from wherever it is put by the HTMLHelp compiler to your project’s output directory (Debug or Release or whatever) automatically. By using a custom build step, this copy is done whenever you do a build of your VC project but only if the chm file has been changed. To create a custom build step for the help file, first add the file to the project. Then create the custom build step by using the “Custom Build Step” of the project settings. Select the chm file in the tree on the left then enter the following:

Description:

 
Copying $(InputPath)
Commands:
 
 
copy $(InputPath) $(OutDir)\$(InputName).chm
Outputs:
 
$(OutDir)\$(InputName).chm