A Help Example—No Programming Required

If you followed the instructions for EX20D in Chapter 20, you selected the AppWizard Context-Sensitive Help option. We'll now return to that example and explore the application framework's built-in help capability. You'll see how easy it is to link help topics to menu command IDs and frame window resource IDs. You edit RTF files, not CPP files.

Here are the steps for customizing the help for EX20D:

1. Verify that the help file was built correctly. If you have built the EX20D project already, chances are that the help file was created correctly as part of the build process. Check this by running the application and then pressing the F1 key. You should see the generic Application Help screen with the title "Modifying the Document," as shown below.

   If you do not see this screen, the MAKEHELP batch file did not run correctly. First check the last two lines of the ex20d.hpj file in the \hlp subdirectory. Are the paths correct for your Visual C++ installation? Next choose Options from the Tools menu, and click on the Directories tab. Make sure that the \VC98\bin subdirectory of your Visual C++ directory is one of the search directories for Executable Files.

   

   To generate the help file, highlight the ex20d.hpj file in the Workspace FileView window, and then choose Compile Ex20d.hpj from the Build menu. This runs the MAKEHELP batch file that is in your project directory. (You can also run it directly from an MS-DOS prompt.) You should observe some "file(s) copied" messages but no error messages. Rerun the EX20D program, and press F1 again.

   

   The Visual C++ make processor doesn't always detect all the dependencies in your help system. Sometimes you must run the MAKEHELP batch file yourself to rebuild the HLP file after making changes.

2. Test the generic help file. Try the following experiments:
   • Close the Help dialog, press Alt-F and then press F1. This should open the help topic for the File New command. You can also press F1 while holding down the mouse button on the File New menu item to see the same help topic.

   • Close the Help dialog, click the Context Help toolbar button (shown in "Shift-F1 Help"), and then choose Save from the File menu. Do you get the appropriate help topic?

   • Click the Context Help toolbar button again, and then select the frame window's title bar. You should get an explanation of a Windows title bar.

   • Close all child windows and then press F1. You should see a main index page that is also an old-style table of contents.

3. Change the application title. The file AfxCore.rtf, in the \vcpp32\ex20d\hlp directory, contains the string <<YourApp>> throughout. Replace it globally with EX20D.

4. Change the Modifying The Document Help screen. The file AfxCore.rtf in the \vcpp32\ex20d\hlp directory contains text for the generic Application Help screen. Search for Modifying the Document, and then change the text to something appropriate for the application. This topic has the help context ID HIDR_DOC1TYPE. The generated ex20d.hpj file provides the alias HIDR_EX20DTYPE.

5. Add a topic for the Window New String Window menu item. The New String Window menu item was added to EX20D and thus didn't have associated help text. Add a topic to AfxCore.rtf, as shown here.

   

   Notice the # footnote that links the topic to the context ID HID_WINDOW_NEW_STRING as defined in hlp\ex20d.hm. The program's command ID for the New String Window menu item is, of course, ID_WINDOW_NEW_STRING.

6. Rebuild the help file and test the application. Run the MAKEHELP batch file again, and then rerun the EX20D program. Try the two new help links.