ch11.htm

A very good resource on Visual C++ 6.0 environment. It teaches through step by step approach and fin

<TABLE BORDER="1">
	<TR ALIGN="LEFT" VALIGN="TOP">
		<TD ALIGN="LEFT">h</TD>
		<TD ALIGN="LEFT">These Header files define resource IDs and Help topic IDs for use within your C++
			code.</TD>
	</TR>
	<TR ALIGN="LEFT" VALIGN="TOP">
		<TD ALIGN="LEFT">.hm</TD>
		<TD ALIGN="LEFT">These Help Mapping files define Help topic IDs. appname.hm is generated every time
			you build your application--don't change it yourself.</TD>
	</TR>
	<TR ALIGN="LEFT" VALIGN="TOP">
		<TD ALIGN="LEFT">.rtf</TD>
		<TD ALIGN="LEFT">These Rich Text Format files contain the Help text for each Help topic.</TD>
	</TR>
	<TR ALIGN="LEFT" VALIGN="TOP">
		<TD ALIGN="LEFT">appname.cnt</TD>
		<TD ALIGN="LEFT">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.)</TD>
	</TR>
	<TR ALIGN="LEFT" VALIGN="TOP">
		<TD ALIGN="LEFT">appname.hpj</TD>
		<TD ALIGN="LEFT">This Help ProJect file pulls together .hm and .rtf files to produce, when compiled,
			a .hlp file.</TD>
	</TR>
</TABLE>
</P>
<P>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:</P>

<UL>
	<LI><I>appname.gid</I> is a configuration file, typically hidden.
	<P>
	<LI><I>appname.fts</I> is a full text search file, generated when your user does
	a Find through your Help text.
	<P>
	<LI><I>appname.ftg</I> is a full text search group list, also generated when your
	user does a Find.
</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 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.</P>
<P><A HREF="javascript:popUp('11fig04.gif')"><B>FIG. 11.4</B></A><B> </B><I>Your
program, the Help system, and your Help files all work together to display a topic.</I></P>
<H2><I></I></H2>
<H2><A NAME="Heading7"></A>Help Support from AppWizard</H2>
<P>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:</P>

<UL>
	<LI>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.
	<P>
	<LI>A What's This? button is added to the toolbar.
	<P>
	<LI>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.
	<P>
	<LI>Accelerators for F1 (ID_HELP) and Shift+F1 (ID_CONTEXT_HELP) are added.
	<P>
	<LI>The default message in the status bar is changed from Ready to For Help, press
	F1.
	<P>
	<LI>A status bar prompt is added, to be displayed while in What's This? mode: Select
	an object on which to get Help.
	<P>
	<LI>Status bar prompts are added for the Help menu and its items.
	<P>
	<LI>afxcore.rtf, a Help text file for standard menu items such as File, Open, is
	copied into the project.
	<P>
	<LI>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.)
	<P>
	<LI>Twenty-two .bmp files, included as illustrations in Help for topics such as File,
	Open, are copied into the project.
</UL>

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

<DL>
	<DD><B>1. </B>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>
	<DT></DT>
	<DD><B>2. </B>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 will see in the sections that follow.
	<P>
	<DT></DT>
	<DD><B>3. </B>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>
</DL>



<BLOCKQUOTE>
	<P>
<HR>
<strong>NOTE:</strong> 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. 
<HR>


</BLOCKQUOTE>

<H2><A NAME="Heading8"></A>Planning Your Help Approach</H2>
<P>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.</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 Creating Online Documents</I>,
written by Mary Deaton and Cheryl Lockett Zubak, published by Que. In this section,
there is room for only 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 the following:</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 (or by pressing F1 on a highlighted menu 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.
</UL>

<P>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.</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 File,
Open mentions using File, New 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 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:</P>

<UL>
	<LI>Changing AppWizard's placeholder strings to ShowString or other strings specific
	to this application
	<P>
	<LI>Adding a topic about the Tools menu and the Options 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 Help menu and writing it
	<P>
	<LI>Adjusting the Contents to point to the new pages
</UL>

<P>The remainder of this chapter tackles this list of tasks.</P>
<P>
<H2><A NAME="Heading9"></A>Programming for Command Help</H2>
<P>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.</P>
<P>Say, for example, that ShowString deserves an item named Understanding Centering
on the Help menu. Here's how to make that happen:</P>

<DL>
	<DT></DT>
	<DD><B>1. </B>Open ShowString, either your own copy from working along with Chapter
	8 or a copy you have downloaded from the book's Web site, in Visual Studio. You may
	want to make a copy of the old project before you start, because ShowString is the
	foundation for many of the projects in this book.
</DL>



<BLOCKQUOTE>
	<P>
<HR>
<strong>TIP:</strong> If you aren't familiar with editing menus and dialogs or catching
	messages, you should read Chapter 9 before this one. 
<HR>


</BLOCKQUOTE>


<DL>
	<DT></DT>
	<DD><B>2. </B>Open the IDR_MAINFRAME menu by switching to ResourceView, expanding
	Menus, and double-clicking IDR_MAINFRAME. Add the Understanding Centering item to
	the Help menu (just below Help Topics) and let Developer Studio assign it the resource
	ID ID_HELP_UNDERSTANDINGCENTERING. This is one occasion when a slightly shorter resource
	ID wouldn't hurt, but this chapter presents it with the longer ID.
	<P>
	<DT></DT>
	<DD><B>3. </B>Add the item to the other menu, IDR_SHOWSTTYPE, as well. Use the same
	resource ID.
	<P>
	<DT></DT>
	<DD><B>4. </B>Use ClassWizard to arrange for CShowStringApp to catch this message,
	as discussed in Chapter 8. Add the code for the new function, which looks like this:
	<P>
</DL>

<PRE>void CShowStringApp::OnHelpUnderstandingcentering() 
{
    WinHelp(HID_CENTERING);
}
</PRE>
<P>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:</P>
<P>
<PRE><B>#define HID_CENTERING 0x01</B>
</PRE>
<P>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 <I>help mapping entry</I>. This should be done in a new file named
ShowStringx.hm. (The <I>x</I> 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:</P>
<P>
<PRE><B>HID_CENTERING      0x01</B>
</PRE>
<P>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:</P>
<P>
<PRE><B>#include &lt;ShowStringX.hm&gt;</B>
</PRE>
<P>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.</P>
<P>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.</P>
<P>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.</P>
<P>
<H2><A NAME="Heading10"></A>Programming for Context Help</H2>
<P>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.</P>
<P><A HREF="javascript:popUp('11fig05.gif')"><B>FIG. 11.5</B></A><B> </B><I>Turn
on the Question box on the Options dialog box of ShowString.</I></P>
<P>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:</P>
<P>
<PRE>// 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()
</PRE>
<P>The message map in OptionsDialog.cpp should look like this:</P>
<P>
<PRE>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()