Help

Help

l Different Kinds of Help
m Getting Help
m Presenting Help
m Using Help
m Programming Help
l Components of the Help System
l Help Support from AppWizard
l Planning Your Help Approach
l Programming for Command Help
l Programming for Context Help
l Writing Help Text
m Changing Placeholder Strings
m Adding Topics
m Changing the How to Modify Text Topic
l Adjustments to the Contents
Too many programmers entirely neglect online Help. Even those who add Help to an
application tend to leave it to the end of a project, and when the inevitable time
squeeze comes, guess what? There is no time to write the Help text or make the software
adjustments that arrange for that text to display when the user requests Help. One
reason people do this is because they believe implementing Help is really hard. With
Visual C++, though, it's a lot easier than you might anticipate. Visual C++ even writes
some of your Help text for you! This chapter is going to add Help, after the fact, to the

ShowString application built in Chapter 8, "Building a Complete Application:
ShowString."
Different Kinds of Help
You can characterize Help in a variety of ways. This section presents four different
questions you might ask about Help:
l How does the user invoke it?
l How does it look onscreen?
l What sort of answers does the user want?
l How does the developer implement it in code?
None of these questions has a single answer. There are at least nine different ways for
a user to invoke Help, three standard Help appearances, and three different
programming tasks you must implement in order to display Help. These different ways of
looking at Help can help you understand why the implementation involves a number of
different techniques, which can be confusing at first.
Getting Help
The first way of characterizing Help is to ask "How does the user open it up?" There are
a number of ways to open Help:
l By choosing an item from the Help menu, such as Help, Contents (choosing What's
This? or About does not open Help immediately)
l By pressing the F1 key
l By clicking the Help button on a dialog box
l By clicking a What's This? button on a toolbar and then clicking something else
l By choosing What's This? from the Help menu (the System menu for dialog box
based applications) and then clicking something
l By clicking a Question button on a dialog box and then clicking part of the
dialog box
l By right-clicking something and choosing What's This? from the pop-up menu

l In some older applications, by pressing Shift+F1 and then clicking something
l Outside the application completely, by double-clicking the HLP file
For the first three actions in this list, the user does one thing (chooses a menu item,
presses F1, or clicks a button), and Help appears immediately. For the next five actions,
there are two steps: typically, one click to go into Help mode (more formally called
What's This? mode) and another to indicate which Help is required. Users generally
divide Help into single-step Help and two-step Help, accordingly.
NOTE: You will become confused if you try to use Visual Studio to
understand Help, in general. Much of the information is presented as HTML
Help in a separate product, typically MSDN, though there are some
circumstances under which more traditional Help appears. Use simple
utilities and accessories that come with your operating system or use your
operating system itself to follow along.
HTML Help
Until fairly recently, all Help files were built from RTF files, as described
in this chapter, and displayed with the Microsoft Help engine. Microsoft has
now started to use HTML files for its Help, and has released a number of
tools to simplify the job of creating and maintaining HTML Help.
There are a number of advantages to an HTML Help system: Your Help files
can contain links to Internet resources, for example. You can incorporate
any active content that your browser understands, including ActiveX
controls, Java applets, and scripting. Many developers find attractive Help
systems quicker to build in HTML.
Unfortunately, there are also disadvantages. The interface is not as rich as
the traditional Help interface, for example. Many developers take one look
at the HTML Help provided with Visual Studio and vow never to produce
HTML Help files for their own products.
If you would like to use HTML Help rather than the traditional Help files
discussed in this chapter, start by visiting
http://www.microsoft.com/workshop/author/htmlhelp to get a copy of
the HTML Help Workshop and plenty of documentation and examples.
Most of the work involved in creating HTML Help is the same as the

traditional Help techniques presented here, but involves, for example,
calling HTMLHelp() instead of ::WinHelp(). Instead of editing RTF files with
Word, you edit HTML files with the HTML Help Workshop editor.