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'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 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."
You can characterize Help in a variety of ways. This section presents four different questions you might ask about Help:
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.
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:
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 HelpUntil 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.
The second way of characterizing Help is to ask, "How does it look?" You can display Help in several ways:
FIG. 11.1 The Help Topics dialog box enables 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 sometimes 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.
A third way of characterizing Help is according to the user's reasons for invoking it. In the book The Windows Interface Guidelines for Software Design, Microsoft categorizes Help in this way and lists these kinds of Help:
These describe the content of the material presented to the user. Although these content descriptions are important to a Help designer and writer, they're not very useful from a programming point of view.
TIP: The book mentioned previously is provided with the MSDN CDs included with Visual Studio. In Visual Studio, press F1 to bring up MSDN. On the Contents tab of MSDN, expand the Books item, then expand the interface guidelines book. Chapter 12, "User Assistance," gives Help guidelines.
The final way of characterizing Help, and perhaps the most important to a developer, is by examining the code behind the scenes. Three Windows messages are sent when the user invokes Help:
NOTE: Windows messages are discussed in Chapter 3, "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 prebuilt menu with only 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 opens Help in any other way, the framework handles most of it. You don't catch the message that puts the application into What's This? mode, you don't change the cursor, and you don't 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 doesn't matter. In fact, you can't 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 is discussed later in this chapter in the "Programming for Command Help" and "Programming for Context Help" sections, but keep in mind that there's no relationship between this split (between command and context help) and the split between one-step and two-step Help that users think of.
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 might 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--don't 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 from the user's hard disk, be sure to look for and remove the following files, in addition to the .hlp and .cnt files:
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 such as 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.
When you build an MDI application (no database or OLE support) with AppWizard and choose the Context-Sensitive Help option (in Step 4), here's what you find:
With this solid foundation, the task of implementing Help for this application breaks down into three steps:
NOTE: On large projects, often a technical writer rather than a programmer writes the Help text. This requires careful coordination: For example, you have to provide topic IDs to the Help writer, and you might 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.
Developing Help is like developing your software. You shouldn't do it without a plan. 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 the errors were carved in code, and they found writing programs much easier 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, written by Mary Deaton and Cheryl Lockett Zubak, published by Que. In this section, there is room for only 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 the following:
Although that might seem like a lot of work, remember that all the boilerplate resources have been documented already in the material provided by AppWizard. This 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 8. This simple application displays a string that the user can set. The string can be centered vertically or horizontally, and it can be black, green, or red. A new menu (Tools) with one item (Options) opens a dialog box on which the user can set all these options at once. The Help tasks you need to tackle include the following:
The remainder of this chapter tackles this list of tasks.
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:
TIP: If you aren't familiar with editing menus and dialogs or catching messages, you should read Chapter 9 before this one.
){kind=link}
){kind=link}
){kind=link}
){kind=link}
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 double-click 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's 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.
Your first task in arranging for context Help is to get a Question button onto the Options dialog box, because AppWizard already added one to the toolbar. Open the Options dialog box by double-clicking it in the ResourceView 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 Turn on the Question box on the Options dialog box of ShowString.
As mentioned earlier, two messages are relevant to 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. Because ClassWizard doesn't include them in the list of messages it will catch, you will add entries outside the special ClassWizard comments. The message map in OptionsDialog.h should look like this:
){kind=link}
// 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 these functions. They both need to use a table to connect resource IDs to Help topic IDs. To create this table, add these lines at the be-ginning 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, after the two functions are written, the compiler will be happy because all these constants are defined. The Help system, however, doesn't know what's going on because these topics aren't in the Help mapping file yet. Therefore, 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 add the code for the functions at the end of OptionsDialog.cpp. 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 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.
TIP: If you've never seen the :: scope resolution operator used without a classname before it, it means "call the function that isn't in any class," and in Windows programming, that generally means the SDK function.
NOTE: The third parameter of this call to WinHelp() directs the Help system to put up a certain style of Help window. HELP_WM_HELP gives you a pop-up menu, as does HELP_WM_CONTEXTMENU. HELP_CONTEXT produces an ordinary Help window, which can be resized and moved, and enables Help navigation. HELP_FINDER opens 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. Add this code at the end of OptionsDialog.cpp:
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 can also right-click ShowString.hpj in the FileView 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.
You write Help text in an RTF file, using special formatting codes that mean something rather different than they usually do. The traditional way to do this has been in Microsoft 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. An entire chapter in Designing Windows 95 Help discusses choosing an authoring tool.
TIP: You can open Word documents from within Developer Studio. Simply choose File, Open and select the file--the starter RTF files for ShowString are in the HLP folder. 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 rather than have a number of files open in Developer Studio and switch among them with the Window menu, so the explanations in this section assume that 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, such as this boilerplate provided by AppWizard, can be edited in Word.
There are eight kinds of footnotes, each with a different meaning. Only the first three footnote types in the following list are in general use:
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 can also 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. Alternatively, choose the File menu, and while the highlight is on New, press F1.
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.
To change the placeholder strings left behind by AppWizard in the boilerplate Help files, open afxcore.rtf in Word if it isn't already open. (It's in the hlp folder of the ShowString project folder.) Then follow these steps:
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:
That completes the extensive changes required to the boilerplate afxcore.rtf file generated by AppWizard. In the other boilerplate file, afxprint.rtf, 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.
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 were 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:
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.
TIP: 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:
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 don't 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:
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:
Change the topic ID and add a sentence or two of text. Be consistent. The examples included with this chapter are each 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 when 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 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:
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.
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.
AppWizard 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.
TIP: 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.
TIP: There can't 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 can make it impossible to select only half a word. You can turn off the feature in Word by choosing Tools, Options, the Edit tab and by deselecting the When Selecting, Automatically Select Entire Word 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.
This tiny little application is almost entirely documented now. You need to add the Tools menu and Understanding Centering to the Contents and to 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 open Help Workshop by choosing Start, Programs, Microsoft Visual Studio 6.0, Microsoft Visual Studio 6.0 Tools, Help Workshop. Open ShowString.cnt by choosing File, Open and working your way through the Open dialog box. (If you can't find the contents file, be sure to change the File Type drop-down. It's probably in your Debug directory.) 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 named <<add your application-specific topics here>> 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. Don't use Understanding Centering because that's the title of the only topic under this heading. Enter Displaying a string and click OK.
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 expand each heading. You will see something like Figure 11.15.
FIG. 11.14 Add headings to the Contents tab with Help Workshop's Edit Contents Tab Entry dialog box.
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.
Now the Help file for this application is complete, and you've arranged for the relevant sections of the file to be displayed when the user requests online Help. You can apply these concepts to your own application, and never again deliver an undocumented product.
© Copyright, Macmillan Computer Publishing. All rights reserved.
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}