Special Edition Using Visual C++ 5 - Chapter 11

## Chapter 11

## Help

- Types of Help

  There are a number of different kinds of Help. Users, developers, and technical writers all divide Help along different lines.

- The file types that make up Help

  AppWizard and the Help compiler between them generate over 10 files related to Help. This section explains them.

- What AppWizard provides

  Code is added to your program and files are added to your project when you ask for context-sensitive Help.

- Designing your Help

  Good Help, like a good program, is designed before it is implemented. There are many tasks involved in the implementation, and there's a risk of getting lost if you're not sure where you're going.

- Connecting command Help to your application

  Dealing with Windows messages associated with menu items or buttons that request Help is quite simple.

- Connecting context Help to your application

  Dealing with Windows messages requesting context-sensitive Help is more difficult, but can be done. This section works you through it.

- Composing Help text in Word

  Using Word to compose Help files means learning all about footnote types, hidden text, and more. This section adds Help to an existing application to demonstrate the work involved.

- Help table of contents

  Making sure the user can reach your new topics from the Help Contents list is vital. The Help Workshop tool included with Visual C++ makes it simple.

Too many programmers neglect Help entirely. 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's 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 of the reasons people do this is because they believe implementing Help is really hard. But with Visual C++, 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 9, "Building a Complete Application: ShowString."

### Different Kinds of Help

There are a variety of ways of characterizing Help. This section presents four different questions you might ask about Help:

- How does the user invoke it?
- How does it look on-screen?
- What sort of answers does the user want?
- 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 has 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 bring it up?" There are a number of ways to bring up Help:

- By choosing an item from the Help menu, such as Help, Topics (Choosing What's This? or About does not bring up Help immediately.)
- By pressing F1
- By clicking the Help button on a dialog box
- By clicking a What's This? button on a toolbar and then clicking something else
- By choosing What's This? from the Help menu (the System menu for dialog box-based applications) and then clicking something
- By clicking a Question button on a dialog box and then clicking part of the dialog box
- By right-clicking something and choosing What's This? from the pop-up menu
- In some older applications, by pressing Shift+F1 and then clicking something
- 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 get into "Help mode" (more formally called "What's This?" mode) and another to indicate what Help is required. Users generally divide Help into single-step Help and two-step Help accordingly.

> You will get confused if you try to use Developer Studio itself to understand Help, in general. Much of the information is presented in HTML by InfoViewer, 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. If you have old versions of software like Word or Excel, they probably don't follow the Windows 95 guidelines for Help either, because these are quite different than the old Help guidelines.

Presenting Help

The second way of characterizing Help is to ask "How does it look?" There are a number of different-looking ways of showing Help:

- Help Topics dialog box. As shown in Figure 11.1, this dialog box allows users to scroll through an index, look at a table of contents, or find a word within the Help text.
- Ordinary Help window. As shown in Figure 11.2, this window has buttons like Help Topics, Back, and Options. It can be resized, minimized, maximized, or closed, and in many cases is always on top, like the system clock and other popular utilities.
- Pop-up windows. As shown in Figure 11.3, pop-up windows are relatively small and do not have buttons or menus. They disappear when you click outside them, cannot be resized or moved, and are perfect for a definition or quick explanation.

Fig. 11.1

The Help Topics dialog box allows users to go through the contents or index, or search the Help text with Find.

Fig. 11.2

An ordinary Help window has buttons and may have menus. It can be treated like any other window.

Fig. 11.3

A pop-up Help topic window gives the user far less control and should be used only for short explanations.

Using Help

A third way of characterizing Help, is according to the user's reasons for invoking it. Microsoft categorizes Help in this way and lists these kinds of Help:

- Contextual user assistance. Answers questions like "What does this button do?" or "What does this setting mean?"
- Task-oriented Help. Explains how to accomplish a certain task such as printing a document (it often contains numbered steps).
- Reference Help. Look up function parameters or font names, or other material that expert users need to refer to from time to time.

These describe the content of the material presented to the user. While these content descriptions are important to a Help designer and writer, they are not very useful from a programming point of view.

Programming Help

The final way of characterizing Help, and perhaps the most important to a developer, is by examining the code behind the scenes. There are three Windows messages that are sent when the user invokes Help in any of these ways:

- WM_COMMAND
- WM_HELP
- WM_CONTEXTMENU

> Windows messages are discussed in Chapter 4, "Messages and Commands."

When the user chooses a Help item from a menu, or clicks the Help button on a dialog box, the system sends a WM_COMMAND message as always. To display the associated Help, you catch these messages and call the WinHelp system.

When the user right-clicks an element of your application, a WM_CONTEXTMENU message is sent. You catch the message and build a shortcut menu on the spot. Because in most cases you will want a shortcut menu with only one item on it, What's This?, you can use a pre-built menu with just that item, and delegate the display of that menu to the Help system. More on this later, in the "Programming for Context Help" section.

When the user brings up Help in any other way, the framework handles most of it. You do not catch the message that puts the application into What's This? mode, you do not change the cursor, and you do not deal with clicks while in that mode. You catch a WM_HELP message that identifies the control, dialog box, or menu for which Help is required, and you provide that Help. Whether the user pressed F1, or went into What's This? mode and clicked the item does not matter. In fact, you cannot tell from within your application.

The WM_HELP and WM_CONTEXTMENU messages are handled almost identically, so from the point of view of the developer, there are two kinds of help. We'll call these command help and context help. Each are discussed later in this chapter, in the "Programming for Command Help" and "Programming for Context Help" sections, but keep in mind that there is no relationship between this split (between command and context help) and the split between one-step and two-step Help that users think of.

### Components of the Help System

As you might expect, a large number of files interact to make online Help work. The final product, which you deliver to your user, is the Help file, with the .hlp extension. It is built from component files. In the list that follows, appname refers to the name of your application's .exe file. If no name appears, there may be more than one file with a variety of names. The component files produced by AppWizard are as follows:

.h | These Header files define resource IDs and Help topic IDs for use within your C++ code.
.hm | These Help Mapping files define Help topic IDs. appname.hm is generated every time you build your application—do not change it yourself.
.rtf | These Rich Text Format files contain the Help text for each Help topic.
appname.cnt | You use this table of contents file to create the Contents tab of the Help Topics dialog box. (You should distribute this contents file with your application in addition to the Help file.)
appname.hpj | This Help ProJect file pulls together .hm and .rtf files to produce, when compiled, a .hlp file.

While being used, the Help system generates other files. When you uninstall your application be sure to look for and remove the following files, in addition to the .hlp file:

- appname.gid is a configuration file, typically hidden.
- appname.fts is a full text search file, generated when your user does a Find through your Help text.
- appname.ftg is a full text search group list, also generated when your user does a Find.

Help Topic IDs are the connection between your Help text and the Help system. Your program eventually directs the Help system to display a Help topic, using a name like HID_FILE_OPEN, and the system looks for this Help topic ID in the Help file, compiled from the .rtf files, including the .rtf file that contains your Help text for that Help topic ID. (This process is illustrated in Figure 11.4.) These topic IDs have to be defined twice—once for use by the Help system and once for use by your program. When the Help system is displaying a topic or the Help Topics dialog box, it takes over displaying other Help topics as the user requests them, with no work on your part.

Fig. 11.4

Your program, the Help system, and your Help files all work together to display a topic.

### Help Support from AppWizard

When you build an MDI application (no database or OLE support) with AppWizard and choose the Context Sensitive Help option, here's what you get:

1. Message map entries are added to catch the commands ID_HELP_FINDER, ID_HELP, ID_CONTEXT_HELP, and ID_DEFAULT_HELP. No code is added to handle these; they are passed to CMDIFrameWnd member functions.
2. A What's This? button is added to the toolbar.
3. A Help Topics item is added to the Help menu for both menus provided by AppWizard: the one used when a file is open and the smaller one used when no files are open.
4. Accelerators for F1 (ID_HELP) and Shift+F1 (ID_CONTEXT_HELP) are added.
5. The default message in the status bar is changed from Ready to For Help, press F1.
6. A status bar prompt is added, to be displayed while in What's This? mode: Select an object on which to get Help.
7. Status bar prompts are added for the Help menu and its items.
8. afxcore.rtf, a Help text file for standard menu items like File, Open, is copied into the project.
9. afxprint.rtf, a Help text file for printing and print previewing, is copied into the project. (These files are added separately because not all projects include printing and print previewing. If this project has database- or OLE-related features, more help is provided.)
10. Twenty two .bmp files, included as illustrations in the Help for topics like File, Open, are copied into the project.

With this solid foundation, the task of implementing Help for this application breaks down into three steps:

1. First, you must plan your Help. Do you intend to provide reference material only, task-oriented instructions only, or both? To what extent will you supplement these with context pop-ups?

2. Second, you must provide the programming "hooks" that will result in the display of the Help topics you have designed. This is done differently for command and context Help, as you see in the sections that follow.

3. Third, you must build the .rtf files with the Help topic IDs and text to explain your application. If you have designed the Help system well and truly understand your application, this should be simple, though time-consuming.

> On large projects, the Help text is often written by a technical writer rather than a programmer. This requires careful coordination: for example, you have to provide Topic IDs to the Help writer, and you may have to explain some functions so that they can be described in the Help. You have to work closely together throughout a project like this and respect each other's area of expertise.

### Planning Your Help Approach

Developing Help is like developing your software. You shouldn't do it without a plan. And, strictly speaking, you shouldn't do it last. A famous experiment decades ago split a programming class into two groups. One group was required to hand in a completed user manual for a program before writing the program, the other to finish the program before writing the manual. The group who wrote the manual first produced better programs: they noticed design errors early, before they were carved in code, and they found the program much easier to write, as well.

If your application is of any size, the work involved in developing a Help system for it would fill a book. If you need further information on how to do this, consider the book Designing Windows 95 Help: A Guide to Creating Online Documents, by Mary Deaton and Cheryl Lockett Zubak, published by QUE. In this section, there is only room for a few basic guidelines.

The result of this planning process is a list of Help topics and the primary way they will be reached. The topics you plan are likely to include:

- A page or so of Help on each menu item, reached by getting into What's This? mode and clicking the item.
- A page, reachable from the Contents, that lists all the menus and their menu items, with links to the pages for those items.
- A page, reachable from the Contents, for each major task that a user might perform with the application. This includes examples or tutorials.
- Context Help for the controls on all dialog boxes.

While that may seem like a lot of work, remember that all the boilerplate resources have been documented already in the material provided by AppWizard. That includes menu items, common dialog boxes, and more.

After you have a complete list of material and the primary way each page is reached, think about links between pages (for example, the AppWizard-supplied Help for File, Open mentions using File, New, and vice versa) and pop-up definitions for jargon and keywords.

In this section you plan Help for ShowString, the application introduced in Chapter 9, "Building a Complete Application: ShowString." This simple application displays a string that the user can set. The string may be centered vertically or horizontally, and it can be black, green, or red. There is a new menu (Tools) with one item (Options) that brings up a dialog box on which the user can set all these options at once. The Help tasks you need to tackle include

- Changing AppWizard's placeholder strings to ShowString or other strings specific to this application
- Adding a topic about the Tools menu and the Options item
- Adding a topic about each control on the Options dialog box
- Adding a Question button to the Options dialog box
- Changing the text supplied by AppWizard and displayed when the user requests context Help about the view
- Adding an Understanding Centering topic to the Help menu and writing it
- Adjusting the Contents to point to the new pages

The remainder of this chapter tackles this list of tasks.

### Programming for Command Help

Command Help is actually quite simple from a developer's point of view. (Of course, you probably still have to write the explanations, so don't get too relaxed.) 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. But if you choose to add another menu item to your Help menu, you do so just like any other menu, using the Resource View. Then have your application class, CShowStringApp, catch the message. Say, for example, that ShowString deserves an item on the Help menu called Understanding Centering. Add this item to both menus and let Developer Studio assign it the resource ID ID_HELP_UNDERSTANDINGCENTERING. Actually, this is one occasion where a slightly shorter resource ID wouldn't hurt, but this chapter presents it with the longer ID.

Use ClassWizard to arrange for CShowStringApp to catch this message, as discussed in Chapter 9, "Building a Complete Application: ShowString." (You may want to open the Help version of this project now from the CODE\CHAP11 directory on the C and follow along, or make a copy of the ShowString you built in Chapter 9 and make these changes as you read.) The new function looks like this:

    void CShowStringApp::OnHelpUnderstandingcentering()

    {

        WinHelp(HID_CENTERING);

    }

This single line of 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() is not 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 file name as ShowStringx.hm, and click OK. In the new file, type in this line:

    HID_CENTERING      0x01

Save the file. Next you need to edit the Help project file, ShowString.hpj. If you double-click this from a folder such as Windows 95 Explorer, the Help Compiler opens it. In this case you actually want to edit it as text, so you should open it with Developer Studio. In Developer Studio's Project Workspace Window, click the FileView tab and then open ShowString.hpj by double-clicking it in the File View (and you wondered what the File View was good for) and add this line at the very bottom:

    #include <ShowStringX.hm>

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 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. Simply follow the steps you followed to add the menu item Help, Understanding Centering, but add a button rather than a menu item. Do not create a new .hm file; add the button's Help topic ID to ShowStringX.hm, which continues to grow in the next section.

### Programming for Context Help

Your first task in arranging for context Help is to get a Question button onto the Options dialog box, since AppWizard already added one to the toolbar. Open the Options dialog box by double-clicking it in the Resource View, and then choose View, Properties. Click the Extended Styles tab, and then make sure that the Context Help check box is selected, as shown in Figure 11.5.

Fig. 11.5

The Context Help check box on the Extended Styles tab of the Dialog Properties dialog box arranges for the Question box on the Options dialog box of ShowString.

As mentioned earlier, there are two messages sent in context Help: WM_HELP when a user clicks something while in What's This? mode, and WM_CONTEXTMENU when a user right-clicks something. You need to arrange for your dialog box class, COptionsDialog, to catch these messages. You do so by adding entries outside the special ClassWizard comments. The message map in OptionsDialog.h should look like this:

    // Generated message map functions

        //{{AFX_MSG(COptionsDialog)

            // NOTE: the ClassWizard will add member functions here

        //}}AFX_MSG

        afx_msg BOOL OnHelpInfo(HELPINFO* lpHelpInfo);

        afx_msg void OnContextMenu(CWnd* pWnd, CPoint point);

         DECLARE_MESSAGE_MAP()

The message map in OptionsDialog.cpp should look like this:

    BEGIN_MESSAGE_MAP(COptionsDialog, CDialog)

        //{{AFX_MSG_MAP(COptionsDialog)

            // NOTE: the ClassWizard will add message map macros here

        //}}AFX_MSG_MAP

        ON_WM_HELPINFO()

        ON_WM_CONTEXTMENU()

    END_MESSAGE_MAP()

These macros arrange for WM_HELP to be caught by OnHelpInfo(), and for WM_CONTEXTMENU to be caught by OnContextMenu(). The next step is to write those functions. They both need to use a table to connect resource IDs to Help topic IDs. Add these lines at the beginning of OptionsDialog.cpp, after the comment block that reads // COptionsDialog dialog:

    static DWORD aHelpIDs[] =

    {

        IDC_OPTIONS_STRING, HIDD_OPTIONS_STRING,

        IDC_OPTIONS_BLACK, HIDD_OPTIONS_BLACK,

        IDC_OPTIONS_RED, HIDD_OPTIONS_RED,

        IDC_OPTIONS_GREEN, HIDD_OPTIONS_GREEN,

        IDC_OPTIONS_HORIZCENTER, HIDD_OPTIONS_HORIZCENTER,

        IDC_OPTIONS_VERTCENTER, HIDD_OPTIONS_VERTCENTER,

        IDOK, HIDD_OPTIONS_OK,

        IDCANCEL, HIDD_OPTIONS_CANCEL,

        0, 0

    };

The Help system uses this array (you pass the address to the WinHelp() function) to connect resource IDs and Help topic IDs. The compiler, however, has never heard of HIDD_OPTIONS_STRING, so add these lines to OptionsDialog.h, before the definition of the COptionsDialog class:

    #define HIDD_OPTIONS_STRING 2

    #define HIDD_OPTIONS_BLACK 3

    #define HIDD_OPTIONS_RED 4

    #define HIDD_OPTIONS_GREEN 5

    #define HIDD_OPTIONS_HORIZCENTER 6

    #define HIDD_OPTIONS_VERTCENTER 7

    #define HIDD_OPTIONS_OK 8

    #define HIDD_OPTIONS_CANCEL 9

The numbers are chosen arbitrarily. Now, as before, the compiler is happy, since all these constants are defined, but the Help system doesn't know what's going on because these topics are not in the Help mapping file yet. So, add these lines to ShowStringX.hm:

    HIDD_OPTIONS_STRING      0x02

    HIDD_OPTIONS_BLACK      0x03

    HIDD_OPTIONS_RED      0x04

    HIDD_OPTIONS_GREEN      0x05

    HIDD_OPTIONS_HORIZCENTER      0x06

    HIDD_OPTIONS_VERTCENTER      0x07

    HIDD_OPTIONS_OK      0x08

    HIDD_OPTIONS_CANCEL       0x09

Be sure to use the same numbers as in the #define statements in OptionsDialog.h. The stage is set; all that remains is to write the functions. Here's what OnHelpInfo() looks like:

    BOOL COptionsDialog::OnHelpInfo(HELPINFO *lpHelpInfo)

    {

        if (lpHelpInfo->iContextType == HELPINFO_WINDOW) // must be for a control

        {

            // have to call SDK WinHelp not CWinApp::WinHelp

            // because CWinApp::WinHelp doesn't take a

            // handle as a parameter.

            ::WinHelp((HWND)lpHelpInfo->hItemHandle,

                AfxGetApp()->m_pszHelpFilePath,

                HELP_WM_HELP, (DWORD)aHelpIDs);

        }

        return TRUE;

    }

This function just calls the SDK WinHelp function and passes the handle to the control, the path to the Help file, the command HELP_WM_HELP to request a context-sensitive pop-up Help topic, and the table of resource IDs and Help topic IDs built earlier. There's no other work for your function to do after kicking WinHelp() into action.

> If you've never seen the :: scope resolution operator used without a class name before it, it means call the function that is not in any class, and in Windows programming that generally means the SDK function.

> The third parameter of this call to WinHelp directs the Help system to put up a certain style of Help window. HELP_WM_HELP gets you a pop-up menu, as does HELP_WM_CONTEXTMENU. HELP_CONTEXT gets an ordinary Help window, which can be resized and moved, and allows Help navigation. HELP_FINDER brings up the Help Topics dialog box. HELP_CONTENTS and HELP_INDEX are obsolete and should be replaced with HELP_FINDER if you maintain code that uses them.

OnContextMenu() is even simpler:

    void COptionsDialog::OnContextMenu(CWnd *pWnd, CPoint /*point*/)

    {

         ::WinHelp((HWND)*pWnd, AfxGetApp()->m_pszHelpFilePath,

              HELP_CONTEXTMENU, (DWORD)aHelpIDs);

    }

This function doesn't need to check that the right-click is on a control as OnHelpInfo() did, so it just calls the SDK WinHelp. WinHelp() takes care of displaying the shortcut menu with only a What's This item and then displays Help when that item is chosen.

To check your typing, build the project by choosing Build, Build, and then compile the Help file by giving focus to ShowString.hpj and choosing Build, Compile. (You also can right-click ShowString.hpj in the File View of the Project Workspace Window and choose Compile from the shortcut menu.) There's not much point in testing it, though; the AppWizard stuff is sure to work, and without Help content connected to those topics, none of the code you just added can succeed in displaying content.

### Writing Help Text

You write Help text in an RTF file, using special formatting codes, which mean something rather different than they usually do. The traditional way to do this was in Word, but a large crop of Help authoring tools have sprung up that are far easier to use than Word. Rather than teach you yet another tool, this section presents instructions for writing Help text in Word. However, do keep in mind that there are easier ways, and on a project of a decent size you easily save the time and money you invest in a Help authoring tool. There is an entire chapter in Designing Windows 95 Help on choosing an authoring tool.

> You can open Word documents from within Developer Studio. Choose File, Open, and select the file. The Word menus and toolbars will appear. This works because Word documents are ActiveX Document Objects, discussed in Chapter 15, "Building an ActiveX Server Application." Most developers prefer to switch from Word to Developer Studio with the taskbar than to have a number of files open in Developer Studio and to switch among them with the Window menu, so the explanations in this section assume you are running Word separately. If you would rather work entirely within Developer Studio, feel free to so do.

Figure 11.6 shows afxcore.rtf open in Word. Choose View, Footnotes to display the footnotes across the bottom of the screen—they are vital. This is how the text connects to the Help topic IDs. Choose Tools, Options, select the View tab, and make sure the hidden text check box is selected. This is how links between topics are entered. The topics are separated by page breaks.

Fig. 11.6

Help text, like this boilerplate provided by AppWizard, can be edited in Word for Windows.

There are eight kinds of footnotes and each has a different meaning. Only the first three footnote types in the following list are in general use:

- #, the Help topic ID. The SDK WinHelp function looks for this topic ID when displaying Help.
- $, the topic title. This title displays in search results.
- K, keywords. These appear in the Index tab of the Help Topics dialog box.
- A, A-keyword. These keywords can be jumped to but do not appear in the Index tab of the Help Topics dialog box.
- +, browse code. This marks the topic's place in a sequence of topics.
- !, macro entry. This makes the topic a macro to be run when the user requests the topic.
- *, build tag. You use this to include certain tags only in certain builds of the Help file.
- >, window type. This overrides the type of window for this topic.

The double-underlined text, followed by hidden text, identifies a jump to another Help topic. If a user clicks to follow the link, this Help topic leaves the screen. If the text before the hidden text was single-underlined, following the link opens a pop-up over this Help topic, perfect for definitions and notes. (You also may see Help text files in which strikethrough text is used; this is exactly the same as double-underlined—a jump to another topic.) In all three cases, the hidden text is the topic ID of the material to be jumped to or popped up.

Figure 11.7 shows how the File, New Help material appears from within ShowString. To display it yourself, run ShowString by choosing Build, Execute from within Developer Studio, and then choose Help, Help topics in ShowString. Open the menus book, double-click the File menu topic, and click New.

Fig. 11.7

ShowString displays the boilerplate Help generated by AppWizard.

With the programming out of the way, it's time to tackle the list of Help tasks for ShowString from the "Planning Your Help Approach" section earlier in this chapter. These instructions assume you are using Word.

Changing Placeholder Strings

To change the placeholder strings left behind by AppWizard in the boilerplate Help files, open afxcore.rtf in Word. (It's in the hlp folder of the ShowString project folder.) Then follow these steps:

1. Position the cursor at the very beginning of the document and choose Edit, Replace.

2. Enter <<YourApp>> in the Find What box and ShowString in the Replace With box

3. Click Replace All.

Open afxprint.rtf and repeat these steps.

Switch back to afxcore.rtf, and look through the text for << characters (use Edit, Find, and remember that Shift+F4 is the shortcut to repeat your previous Find). These identify places where you must make a change or a decision. For ShowString, the changes in afxcore.rtf are these:

1. The first section in the file is the ShowString Help Index. Remove the How To section and the reminder to add some How To topics. In a real application, you add topics here.

2. The next section, after the page break, is a table describing the items on the File menu. Since there is no Send item on ShowString's File menu, remove the Send row of the File menu table.

3. The third section is a table listing the items on the Edit menu. Remove the Paste Link, Insert New Object, and Links rows.

4. The fourth section is for the View menu and does not need any changes.

5. The fifth section is for the Window menu. Remove the Split row from the Window menu table.

6. The sixth section is for the Help menu and does not need any changes.

7. The seventh section is for the New command (File menu). Remove the sentence about choosing a file type and the reminder to remove it.

8. Delete the eighth section, the File New dialog box topic, entirely, including the page break before or after it, but not both. Whenever you remove a section, remove on of the breaks so that the file does not contain two consecutive page breaks.

9. The next topic is for the File Open command and does not need any changes.

10. Moving on to the File Open dialog box topic, edit the text to mention that the List Files of Type list box contains only All Files.

11. Continue down the file until you find the File Send topic and remove it entirely, including the page break before or after it.

12. In the File Save As topic, remove the suggestion to describe other options since there are none.

13. When you reach the Edit Undo topic, you start to see why programs written after their manuals are better programs. The way ShowString was written in Chapter 9, "Building a Complete Application: ShowString," the Undo item will never be enabled, nor will Cut, Copy, or Paste. You could remove the Help topics about these unsupported menu items, but it's probably better to plan to add support for the menu items to a later version of ShowString. Add some text to all these topics explaining that they are not implemented in this version of the product. Leave the shortcuts sections there so that users can find out why Ctrl+Z does nothing.

14. Continue down through the file to the Toolbar topic, where you find this reminder: << Add or remove toolbar buttons from the list below according to which ones your application offers. >> Remove the reminder and delete the references to the Undo, First Record, Previous Record, Next Record, and Last Record buttons.

15. About halfway down the file is a topic for #Split Command (Window menu). Remove the entire topic.

16. Move down to the #Index command (Help menu) topic and remove it. Also remove the Using Help command (Help menu) and #About command (Help menu) topics.

17. In the Title Bar topic, remove the directive to insert a graphic. If you would rather follow the directive, create a bitmap in a .bmp file of the title bar with screen shot software, cropping the shot down to just the title bar, and insert the graphic with the bmc directive, just as the bullet.bmp graphic is inserted a few lines lower in the file.

18. Because the ShowString view does not inherit from CScrollView, it doesn't scroll. Remove the Scrollbars Help topic and its page break.

19. In the Close command topic (not the File Close topic, which was much earlier in the file,) the shortcut for Alt+F4 should be described like this: closes ShowString.

20. Remove the Ruler, Choose Font, Choose Color, Edit Find, Find Dialog, Edit Replace, Replace dialog box, Edit Repeat, Edit Clear, Edit Clear All, Next Pane, and Previous Pane topics.

21. Skip the How To Modify Text topic for now and leave it unchanged.

22. Remove the final directive about tailoring the No Help Available messages to each message box.

That completes the extensive changes required to the boilerplate afxcore.rtf file generated by AppWizard. In the other boilerplate file, afxprint.rtf, simply scroll to the bottom and remove the Page Setup topic.

Would you like to test all this work? Save afxcore.rtf and afxprint.rtf within Word. Switch to Developer Studio and choose Build, Build to bring the project up to date. Then open ShowString.hpj and choose Build, Compile. This pulls all the .rtf files together into ShowString.hlp. Choose Build, Execute to run ShowString, and choose Help, Help Topics from the ShowString menus. As you can see in Figure 11.8, the Window menu topic is now substantially shorter. You can check that your other changes have been made, as well.

Fig. 11.8

After saving the rtf files and compiling the Help project, you can test to see that your changes have been made successfully.

Adding Topics

When you are adding new topics, you don't add new topics to the boilerplate files that were provided. Those files should stay untouched unless you want to change the description of File Open or other boilerplate topics. Instead, create a new file by choosing File, New in Word and saving it in the hlp folder of the ShowString project folder as ShowString.rtf. (Make sure to change the Save File As Type list box selection to Rich Text Format.) If this was a large project, you could divide it up into several .rtf files, but one will suffice for ShowString. In Developer Studio, open ShowString.hpj by double-clicking it in the FileView tab, and find the section headed [FILES]. Add this line at the end of that section:

    showstring.rtf

The Tools Menu

Back in Word, switch to afxcore.rtf and copy the topic for the File menu into the Clipboard; then switch back to ShowString.rtf and paste it in. (Don't forget to include the page break after the topic in the selection when you copy.) Choose View, Footnotes to display the footnotes, and Tools, Options, View tab, Hidden Text to display the hidden text. Now you are going to edit the copied File topic to make it the Tools topic. Change the footnotes first. They are as follows:

- The # footnote is the topic ID. The Help system uses this to find this topic from the Contents page. Change it to menu_tools.
- The K footnote is the keyword entry. Although the Options dialog box probably deserves several keywords, this menu doesn't, so remove that footnote by selecting the letter K in the Help topic and pressing Delete. You must select the letter; it is not enough to click just before it. The footnote is deleted at the same time.
- The $ footnote is the topic title. Change it to Tools menu commandsU>.

In the topic, change File to Tools on the first two lines, and delete all the rows of the table but one. Change the underlined text of that row to Options, the hidden text immediately following to HID_TOOLS_OPTIONS, and the right column of that row to Changes string, color, and centering. Figure 11.9 shows the way ShowString.rtf looks in Word after these changes.

Fig. 11.9

Change the ShowString.rtf file to explain the new menu item.

> If you can't remember the Help topic IDs your project is using, check your .hm files. The ones added by Developer Studio, such as HID_TOOLS_OPTIONS for the menu item with resource ID ID_TOOLS_OPTIONS, are in ShowString.hm, whereas ShowStringx.hm contains the Help topic IDs added by hand for context Help.

The Tools, Options menu item

Switch back to afxcore, copy the File New topic, and paste it into ShowString.rtf as before. The topic and its footnotes are copied together. Watch carefully to be sure you are working with the footnotes for the Tools Options topic and not the ones for the Tools menu. Follow these steps:

1. Change the # footnote to HID_TOOLS_OPTIONS.

2. Change the K keyword. There are several keywords that should lead here, and each needs to be separated from the next by a semicolon (;). Some need to be two-level keywords with the levels separated by commas. A good first start is string, changing;color, changing;centering, changing;appearance, controlling.

3. Change the $ keyword to Tools Options command.

4. Change the first line of the topic to Options command (Tools menu).

5. Delete the rest of the topic and replace it with a short description of this menu item. The following text is OK:

       Use this command to change the appearance of the ShowString

       display with the Options dialog box. The string being displayed,

       color of the text, and vertical and horizontal centering are

       all controlled from this dialog.

If you want to test this, too, save the files in Word, compile the Help project, run ShowString, and choose Tools. Highlight the Options item by moving the highlight with the cursor keys, but do not click Options to select it; press F1 instead. Figure 11.10 shows the Help window that displays.

Fig. 11.10

The new Tools Options Help is reached by pressing F1 while the item is highlighted on the menu.

Each Control on the Options Dialog

Copy the File New topic into ShowString.rtf again and cut it down drastically. To do this, follow these steps:

1. Remove the K and $ footnotes.

2. Change the # footnote to HIDD_OPTIONS.

3. Change the first line to (Options dialog).

4. Delete the other text in the topic.

Copy this block into the Clipboard and paste it in seven more times, so that you have a skeleton for each control on the dialog box. Remember to copy the page break before or after the topic, too. Then edit each skeleton to document the following topic IDs:

- HIDD_OPTIONS_STRING
- HIDD_OPTIONS_BLACK
- HIDD_OPTIONS_RED
- HIDD_OPTIONS_GREEN
- HIDD_OPTIONS_HORIZCENTER
- HIDD_OPTIONS_VERTCENTER
- HIDD_OPTIONS_OK
- HIDD_OPTIONS_CANCEL

Change the topic ID and add a sentence or two of text. Be consistent. The samples included with this chapter are all a single sentence that starts with an imperative verb like "Click" or "Select" and ends with a period (.). If you would rather choose a different style for your pop-up boxes, use the same style for all of them. It confuses the user if pop-up boxes are inconsistent and tends to make them believe your coding is sloppy, too.

To test your work, compile ShowString.hpj again, run ShowString, and choose Tools, Options. Click the question mark button and then click somewhere on the dialog box. Explore each of the controls to be sure you have entered the correct text. Figure 11.11 shows the context Help for the String edit box.

Fig. 11.11

Display Help for a dialog box control by clicking the Question button in the upper-right corner and then clicking a control.

Understanding Centering

In ShowString.rtf, paste in another copy of the File New topic. Make the following changes:

1. Change the # footnote to HID_CENTERING (the topic ID you added to ShowStringx.hm and called in CShowStringApp::OnHelpUnderstandingcentering()).

2. Change the K footnote to centering.

3. Change the $ footnote to Understanding Centering.

4. Change the title on the first line to Understanding Centering.

5. Replace the text with a short explanation of centering, like this:

       ShowString can center the displayed string within the view. The two

       options, "center horizontally" and "center vertically", can be set

       independently on the Options dialog box, reached by choosing the Options

       item on the Tools menu. Text that is not centered horizontally is

       displayed at the left edge of the window. Text that is not centered

       vertically is displayed at the top of the window.

6. Add links from the word Tools to the menu_tools topic and from the word Options to HID_TOOLS_OPTIONS, as before. Remember to watch for extra spaces.

Test this change in the usual way, and when you choose Help, Understanding Centering from the ShowString menus, you should see something like Figure 11.12. Try following the links; you can use the Back button to return to the centering topic.

Fig. 11.12

Display a teaching Help topic by choosing it from the Help menu.

Changing the "How to Modify Text" topic

App Wizard already provided a How to Modify Text topic at the bottom of afxcore.rtf that needs to be edited to explain how ShowString works. It displays when the user selects the view area for context Help. Replace the text with a much shorter explanation that tells the user to choose Tools, Options. To add a link to that topic (short though it is), type HID_TOOLS_OPTIONS immediately after the word Options in the Help topic. While you're at it, type menu_tools immediately after the word Tools. Select the word Options and press Ctrl+Shift+D to double-underline it; then do the same for Tools. Select HID_TOOLS_OPTIONS and press Ctrl+Shift+H to hide it; then do the same for menu_tools.

> If you've reassigned these keys, you can do the formatting the long way. To double-underline text, select it and choose Format, Font. Drop down the Underline box and choose Double, then click OK. To hide text, select it and choose Format, Font, then select the Hidden box and click OK.

> There cannot be any spaces between the double-underlined text and the hidden text, or at the end of the hidden text. Word can give you some trouble about this, because the Smart Cut and Paste feature that works so nicely with words can insert extra spaces where you don't want them, or make it impossible to select only half a word. You can turn the feature off in Word by choosing Tools, Options, the Edit tab, and by deselecting the Automatic Word Selection and Use Smart Cut and Paste check boxes.

Ready to test again? Save the files in Word, compile the Help project file, and execute ShowString; then click the What's This? button on the toolbar, and click in the main view. Your new "How to Modify Text" entry should display.

### Adjustments to the Contents

This tiny little application is almost entirely documented now. You need to add the Tools menu and Understanding Centering to the Contents and check the index. The easiest way to tackle the Contents is with Help Workshop. Close all the Help-related files that are open in Developer Studio and Word, and bring up Help Workshop (it's in the Developer Studio folder). Open ShowString.cnt by choosing File, Open and working your way through the Open dialog box. This is the Contents file for ShowString.

In the first open book, click the View Menu item and then click the Add Below button. (Alternatively, click the Window Menu item and then the Add Above button.) The Edit Contents Tab Entry dialog box, shown in Figure 11.13, appears. Fill it in as shown; by leaving the last two entries blank, the default Help File and Window Type are used. Click OK.

Fig. 11.13

Add entries to the Contents tab with Help Workshop's Edit Contents Tab Entry dialog box.

Click the placeholder book, and click Add Above again. When the Edit Contents Tab Entry dialog box appears, select the Heading radio button from the list across the top. As shown in Figure 11.14, you can change only the title here. Do not use Understanding Centering, since that is the title of the only topic under this heading. Click OK.

Fig. 11.14

Add headings to the Contents tab with Help Workshop's Edit Contents Tab Entry dialog box by selecting the Heading radio button.

Add a topic below the new heading for Understanding Centering, whose ID is HID_CENTERING, and remove the placeholder heading and topic. Save your changes, close Help Workshop, compile ShowString.hpj in Developer Studio again, and test your Help. Choose Help, Help Topics, and you should see something like Figure 11.15.

Fig. 11.15

After saving the .cnt file and compiling the .hpj file, display the new table of contents by choosing Help, Help Topics.

While you have the Help Topics dialog box open, click the Index tab. Figure 11.16 shows how the K footnotes you entered throughout this section have all been added to the index. If it looks a little sparse, you can always go to the .rtf files and add more keywords, remembering to separate them with semicolons.

Fig. 11.16

The index has been built from the K footnotes in the .rtf files.

### From Here...

This chapter has shown you all of the types of Help, the different ways the user invokes it, and the behind-the-scenes code that brings it up on the screen. You have also seen how to edit and write Help topics and Help contents files. Of course, there is much more to cover. If you have a large system to document, you need a book just on Help to give you a good perspective on designing and writing your Help content. Other parts of this book that might interest you include:

- Chapter 4, "Messages and Commands," gives more details on catching the messages generated when a user chooses a menu item or clicks a button.
- Chapter 9, "Building a Complete Application: ShowString," introduces you to the sample application that was documented in this chapter.
- Chapter 10, "Status Bars and Toolbars," shows you some other ways to help your user understand your application.
- Part V, "ActiveX Applications and ActiveX Controls," continues to expand ShowString by adding various kinds of ActiveX functionality. (Part V consists of Chapters 13-17.)

© 1997, QUE Corporation, an imprint of Macmillan Publishing USA, a Simon and Schuster Company.