Connecting WinHelp to C++/MFC Programs by Don Lammers Copyright 1999-2001 by Don Lammers. All rights reserved. Last updated 2001-02-22 Presented with author's permission by Shadow Mountain Tech Contents Scope.................................................................................................................................................................. 1 Acknowledgements............................................................................................................................................ 1 Connecting Context Sensitive WinHelp to C++/MFC Programs ...................................................................... 2 Calling WinHelp Directly from Your C++ Code............................................................................................. 11 Calling WinHelp from a Command Line......................................................................................................... 15 Training Cards from C++................................................................................................................................. 16 Resources......................................................................................................................................................... 18 Scope MFC provides several hooks for easily connecting to WinHelp. In addition, you can call the WinHelp API from anywhere in your program for additional access to help. The Connecting Context Sensitive WinHelp to C++/MFC Programs section shows how to connect to the built in hooks that MFC provides, and is therefore specific to programming with MFC. The remainder of the document should be easily adaptable to any version of C++, as it sets forth the Windows calls and command line interface for WinHelp. Acknowledgements The following information is from my own experimentation and from people who have walked this path before me. Thanks to all of the following: Microsoft Help WorkShop Help, Microsoft Knowledge Base, The Developer's Guide to WINHELP.EXE (Jim Mischel), Building Windows 95 Help (Nancy Hickman), Paul O'Rear, Developing Online Help for Windows 95 (Boggan, Farkas, and Welinske), Gordon F. MacLeod, Burt Abreu. Connecting WinHelp to C++/MFC Programs 1 Connecting Context Sensitive WinHelp to C++/MFC Programs MFC provides for calling WinHelp topics using the WinHelp function of the CWnd class, from which the Main Frame window of your program is derived if you use the App Wizard. In addition you can override dialog box routines to get control level F1 or right click help if needed. This section shows the steps necessary to hook context sensitive WinHelp into a program created using MFC. Create a Program with Built-In Help If you use the MFC App Wizard to create your project you can include WinHelp support for the main window as part of the automatically generated files. To create a new project with context sensitive help support: 1. From the Visual C++ File menu, choose New. 2. Choose MFC AppWizard (.exe). 3. When given the option, make sure that the Context Sensitive Help box is checked. 4. Continue through the process to set up the program the way you want. This creates the following: • An application with a menu and (if you requested it) a toolbar. • A help file with topics for each of the automatically generated menu items and toolbar buttons. The help author can use this framework as a starting point. • A .hm file with the topic ID to number mapping. This file can be used directly by WinHelp. • An operational What's This? Help button on the toolbar. Clicking this button puts the program into What's This? Help mode. Clicking on a menu or control then opens its help. • Shift-F1 hooked up to put the program into What's this? Help mode. • F1 hooked up to open general help for the child window with focus or the control (but not menu) on which the user is currently clicking. • When you create a dialog box, F1 hooked up to open a general help topic for the whole dialog box. • All help topics opened in the main WinHelp window. Note: • Since no dialog boxes are created in this process, you will need to add context sensitive help support for each dialog box as you create it. • Once you have the initial help file and .hm file, it is usually easier to have the help author add new topics using their preferred help authoring tool. You can still have the program generate the framework help each time you build, because that will give you appropriate additional topic mapping entries. Connecting WinHelp to C++/MFC Programs 2 Set the Help File Name The default help file name for an MFC generated program is the name of the executable with a .hlp extension. If your help file is named anything else, you need to set the m_pszHelpFilePath variable before using the built in help features of MFC so that the program knows the help file to call. To set the help file name for MFC calls: • Set the m_pszHelpFilePath variable member of the application class in the InitInstance function. m_pszHelpFilePath is a public variable of type const char*. According to MS, you should first free the memory associated with the default string (the app name with a .hlp extension). //First free the string allocated by MFC at CWinApp startup. //The string is allocated before InitInstance is called. free((void*)m_pszHelpFilePath); //Change the name of the .HLP file. //The CWinApp destructor will free the memory. m_pszHelpFilePath=_tcsdup(_T("d:\\somedir\\myhelp.hlp")); Tips: • m_pszHelpFilePath can be changed at runtime, so you can reset it in code as needed to call additional help files. • If you have more than one help file to call from the program you should put the code for changing help file names in a separate subroutine. This makes any changes during the project much easier to implement. • You can let the help author edit the help file name and window specification by putting them in a separate text file. Setting this file up in INI file format lets you use standard INI file commands to access this "text database." Make Sure WinHelp Can Find the Help File Make sure that WinHelp can always find the help file. Since your program can be started from shortcuts created by the user, the installation program should register the help file or you should call help from your program using the full path and file name. If the help system contains more than one .hlp file and a master Table of Contents (.cnt file), and not all of these are in the same folder, it will be necessary to register the help file and the master TOC to make the master TOC work, regardless of any other issues. To ensure that the program and WinHelp can always find the help file: • Register the help file by creating a string value under HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\Help. The name of the string value is the help file name (without path) and the value is the path. • Always use the full path and file name when setting m_pszHelpFilePath, even if the help file is in the same folder as the program executable. Connecting WinHelp to C++/MFC Programs 3 Manually Add the Context Hooks If you already have a program and need to add help, you can manually edit the files to create the necessary hooks. To add context sensitive help manually: 1. Add the necessary message map entries in the message map of the Main Frame class. If you created the program with the MFC App Wizard and specified that you wanted context help, these items should already be in the file. ON_COMMAND(ID_HELP_FINDER, CMDIFrameWnd::OnHelpFinder) ON_COMMAND(ID_HELP, CMDIFrameWnd::OnHelp) ON_COMMAND(ID_CONTEXT_HELP, CMDIFrameWnd::OnContextHelp) ON_COMMAND(ID_DEFAULT_HELP, CMDIFrameWnd::OnHelpFinder) 2. Copy the What's This? Help icon into a button on your toolbar. This icon is available as a bitmap in C:\Program Files\Microsoft Visual Studio\Common\Graphics\Bitmaps\OffCtlBr\Small\Color\help.bmp. 3. Assign ID_CONTEXT_HELP to the What's This? Help button. Note: • This creates the same basic hooks in the program as the App Wizard, but does not generate a framework help file or the .hm file with the topic ID mapping. You will need to create a list of IDs for the help author to use. Override the Default Context Help Behavior The default WinHelp call made from the hooks automatically created by the App Wizard opens each help topic in the main WinHelp window. Unfortunately the current recommended behavior is: • Control level help is opened in a popup. • Window level help is opened in a secondary window. To create these conditions, you must override the default functions. To create currently recommended behavior: 1. In the Main Frame class, create an OnHelpInfo function using the Class Wizard: BOOL CMainFrame::OnHelpInfo(HELPINFO* pHelpInfo) { return TRUE; } This effectively disables the function, and is necessary because, in combination with the next override, all topics accessed through the F1 key will be called twice. Unfortunately you cannot use the OnHelpInfo function in the Main Frame since (unlike in dialog boxes) it is triggered only by the F1 key and not by Shift- F1 or the key. Connecting WinHelp to C++/MFC Programs 4 2. In the Main Frame class, create a WinHelp function using the Class Wizard: void CMainFrame::WinHelp(DWORD dwData, UINT nCmd) { CWinApp* theApp = AfxGetApp(); CString helpFilePath = theApp->m_pszHelpFilePath; switch ( dwData ) { case HIDR_MAINFRAME: case HIDR_MFCWIZTYPE: case HIDD_ABOUTBOX: case HIDD_TESTDLG: //Topics that need to go into a secondary window. helpFilePath = helpFilePath + ">second"; ::WinHelp(m_hWnd, helpFilePath, HELP_CONTEXT, dwData); break; case WHATEVER