Programming for Command Help

Programming for Command Help

Command Help is simple from a developer's point of view. (Of course, you probably still
have to write the explanations, so don't relax too much.) As you've seen, AppWizard
added the Help Topics menu item and the message map entries to catch it, and the MFC
class CMDIChildFrame has the member function to process it, so you have no work to do
for that. However, if you choose to add another menu item to your Help menu, you do so
just like any other menu, using the ResourceView. Then, have your application class,
CShowStringApp, catch the message.
Say, for example, that ShowString deserves an item named Understanding Centering on
the Help menu. Here's how to make that happen:
1. Open ShowString, either your own copy from working along with Chapter 8 or a
copy you have downloaded from the book's Web site, in Visual Studio. You may
want to make a copy of the old project before you start, because ShowString is
the foundation for many of the projects in this book.
TIP: If you aren't familiar with editing menus and dialogs or catching
messages, you should read Chapter 9 before this one.
2. Open the IDR_MAINFRAME menu by switching to ResourceView, expanding
Menus, and double-clicking IDR_MAINFRAME. Add the Understanding Centering
item to the Help menu (just below Help Topics) and let Developer Studio assign it
the resource ID ID_HELP_UNDERSTANDINGCENTERING. This is one occasion
when a slightly shorter resource ID wouldn't hurt, but this chapter presents it
with the longer ID.
3. Add the item to the other menu, IDR_SHOWSTTYPE, as well. Use the same

resource ID.
4. Use ClassWizard to arrange for CShowStringApp to catch this message, as
discussed in Chapter 8. Add the code for the new function, which looks like this:
void CShowStringApp::OnHelpUnderstandingcentering()
{
WinHelp(HID_CENTERING);
}
This code fires up the Help system, passing it the Help topic ID HID_CENTERING. For this
to compile, that Help topic ID has to be known to the compiler, so in ShowString.h add
this line:
#define HID_CENTERING 0x01
The Help topic IDs in the range 0x0000 to 0xFFFF are reserved for user-defined Help
topics, so 0x01 is a fine choice. Now the C++ compiler is happy, but when this runs, the
call to WinHelp() isn't going to find the topic that explains centering. You need to add
a help mapping entry. This should be done in a new file named ShowStringx.hm. (The x is for
extra, because extra Help mapping entries are added here.) Choose File, New; select the
Files tab; highlight Text File; fill in the filename as ShowStringx.hm; and click OK. In
the new file, type this line:
HID_CENTERING 0x01
Save the file. Next, you need to edit the Help project file, ShowString.hpj. If you
doubleclick this from a folder such as Windows 95 Explorer, the Help Compiler opens it.
In this case, you want to edit it as text, so you should open it with Developer Studio by
double-clicking it in the FileView (and you wondered what the FileView was good for).
Add this line at the very bottom:
#include <ShowStringX.hm>
Press Enter at the end of this line so that there is a blank line after this last directive.
The Help compiler can be weird if there isn't a blank line after the last include.
Now, both the Help system and the compiler know about this new Help topic ID. Later in
this chapter, when you write the Help text, you will add a section that explains
centering and connect it to this Help topic ID.
The other common use of command Help is to add a Help button to a dialog box that
gives an overview of the dialog box. This used to be standard behavior but is now
recommended only for large dialog boxes, especially those with complex interactions
between the various controls. For simple boxes, the What's This? Help is a better choice,
because the information comes up in a small pop-up rather than an entire page of

explanations. To add a Help button to a dialog, follow the same process steps you
followed to add the menu item Help, Understanding Centering, but add a button to a
dialog rather than an item to a menu. You wouldn't create a new .hm file; add the
button's Help topic ID to ShowStringX.hm, which continues to grow in the next section.