ch11.htm

VC使用大全。里面集合了VC使用的各种使用技巧。非常有用。

<H3><B>Components of the Help System</B></H3>

<P>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, <font 
color="#008000">appname</font> 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:</P>

<TABLE BORDER>

<TR>

<TD>

<P><B>.h</B></P>

<TD>

<P>These <I>Header</I> files define resource IDs and Help topic IDs for use within your C++ code.</P>

<TR>

<TD>

<P><B>.hm</B></P>

<TD>

<P>These <I>Help Mapping</I> files define Help topic IDs. <font color="#008000">appname.hm</font> is generated every time you build your application&#151;do not change it yourself.</P>

<TR>

<TD>

<P><B>.rtf</B></P>

<TD>

<P>These <I>Rich Text Format</I> files contain the Help text for each Help topic.</P>

<TR>

<TD>

<P><B><font color="#008000">appname.cnt</font></B></P>

<TD>

<P>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.)</P>

<TR>

<TD>

<P><B><font color="#008000">appname.hpj</font></B></P>

<TD>

<P>This <I>Help ProJect</I> file pulls together .hm and .rtf files to produce, when compiled, a .hlp file.</P></TABLE>

<P>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:</P>

<ul>

<li> <B><font color="#008000">appname.gid</font></B> is a configuration file, typically hidden.</P>

<li> <B><font color="#008000">appname.fts</font></B> is a full text search file, generated when your user does a Find through your Help text.</P>

<li> <B><font color="#008000">appname.ftg</font></B> is a full text search group list, also generated when your user does a Find.</P>

</ul>

<P>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 <font color="#008000">HID_FILE_OPEN</font>, 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&#151;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.</P>

<A HREF="Mfigs04.gif" tppabs="http://www.mcp.com/814147200/0-7897/0-7897-1145-1/figs/ch11/Mfigs04.gif"><b>Fig. 11.4</b></A>

<P><I>Your program, the Help system, and your Help files all work together to display a topic.</I></P>

<H3><B>Help Support from AppWizard</B></H3>

<P>When you build an MDI application (no database or OLE support) with AppWizard and choose the Context Sensitive <U>H</U>elp option, here's what you get:</P>

<ol>

<li> Message map entries are added to catch the commands <font color="#008000">ID_HELP_FINDER</font>, <font color="#008000">ID_HELP</font>, <font color="#008000">ID_CONTEXT_HELP</font>, and <font color="#008000">ID_DEFAULT_HELP</font>. No code is added to 
handle these; they are passed to <font color="#008000">CMDIFrameWnd</font> member functions.</P>

<li> A What's This? button is added to the toolbar.</P>

<li> A <U>H</U>elp Topics item is added to the <U>H</U>elp 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.</P>

<li> Accelerators for F1 (<font color="#008000">ID_HELP</font>) and Shift+F1 (<font color="#008000">ID_CONTEXT_HELP</font>) are added.</P>

<li> The default message in the status bar is changed from <font color="#008000">Ready</font> to <font color="#008000">For Help, press F1</font>.</P>

<li> A status bar prompt is added, to be displayed while in What's This? mode: <font color="#008000">Select an object on </font><font color="#008000">which to get Help</font>.</P>

<li> Status bar prompts are added for the <U>H</U>elp menu and its items.</P>

<li> <font color="#008000">afxcore.rtf</font>, a Help text file for standard menu items like <U>F</U>ile, <U>O</U>pen, is copied into the project.</P>

<li> <font color="#008000">afxprint.rtf</font>, 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.)</P>

<li> Twenty two .bmp files, included as illustrations in the Help for topics like <U>F</U>ile, <U>O</U>pen, are copied into the project.</P>

</ol>

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

<ol>

<li><P> 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?</P>

<li><P> Second, you must provide the programming &quot;hooks&quot; 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.</P>

<li><P> 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.</P>

</ol>

<blockquote><p><img src="note.gif" tppabs="http://www.mcp.com/814147200/0-7897/0-7897-1145-1/note.gif">

<P>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.</P>

<p><img src="bottom.gif" tppabs="http://www.mcp.com/814147200/0-7897/0-7897-1145-1/bottom.gif"></blockquote>

<H3><B>Planning Your Help Approach</B></H3>

<P>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.</P>

<P>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 <I>Designing Windows 95 Help: A Guide to </I><I>Creating Online 
Documents</I>, by Mary Deaton and Cheryl Lockett Zubak, published by QUE. In this section, there is only room for a few basic guidelines.</P>

<P>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:</P>

<ul>

<li> A page or so of Help on each menu item, reached by getting into What's This? mode and clicking the item.</P>

<li> A page, reachable from the Contents, that lists all the menus and their menu items, with links to the pages for those items.</P>

<li> A page, reachable from the Contents, for each major task that a user might perform with the application. This includes examples or tutorials.</P>

<li> Context Help for the controls on all dialog boxes.</P>

</ul>

<P>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.</P>

<P>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 <U>F</U>ile, <U>O</U>pen mentions using <U>F</U>ile, <U>N</U>ew, and vice versa) and 
pop-up definitions for jargon and keywords.</P>

<P>In this section you plan Help for ShowString, the application introduced in <A HREF="index09.htm" tppabs="http://www.mcp.com/814147200/0-7897/0-7897-1145-1/index09.htm" target="text">Chapter 9</A>, &quot;Building a Complete Application: ShowString.&quot; 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 (<U>T</U>ools) with one item (<U>O</U>ptions) 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</P>

<ul>

<li> Changing AppWizard's placeholder strings to ShowString or other strings specific to this application</P>

<li> Adding a topic about the <U>T</U>ools menu and the <U>O</U>ptions item</P>

<li> Adding a topic about each control on the Options dialog box</P>

<li> Adding a Question button to the Options dialog box</P>

<li> Changing the text supplied by AppWizard and displayed when the user requests context Help about the view</P>

<li> Adding an Understanding Centering topic to the <U>H</U>elp menu and writing it</P>

<li> Adjusting the Contents to point to the new pages</P>

</ul>

<P>The remainder of this chapter tackles this list of tasks.</P>

<H3><B>Programming for Command Help</B></H3>

<P>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 <U>H</U>elp Topics menu item and the message map 
entries to catch it, and the MFC class <font color="#008000">CMDIChildFrame</font> 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, <font color="#008000">CShowStringApp</font>, catch the message. Say, for example, that ShowString deserves an item on the <U>H</U>elp menu called <U>U</U>nderstanding Centering. Add this item to 
both menus and let Developer Studio assign it the resource ID <font color="#008000">ID_HELP_UNDERSTANDINGCENTERING</font>. Actually, this is one occasion where a slightly shorter resource ID wouldn't hurt, but this chapter presents it with the longer 
ID.</P>

<P>Use ClassWizard to arrange for <font color="#008000">CShowStringApp</font> to catch this message, as discussed in <A HREF="index09.htm" tppabs="http://www.mcp.com/814147200/0-7897/0-7897-1145-1/index09.htm" target="text">Chapter 9</A>, &quot;Building a Complete Application: ShowString.&quot; (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 <A HREF="index09.htm" tppabs="http://www.mcp.com/814147200/0-7897/0-7897-1145-1/index09.htm" target="text">Chapter 9</A> and make these changes as you read.) The new function looks like this:</P>


<pre><font color="#008000">void CShowStringApp::OnHelpUnderstandingcentering() </font></pre>

<pre><font color="#008000">{</font></pre>