ch11.htm

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

END_MESSAGE_MAP()
</PRE>
<P>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:</P>
<P>
<PRE>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
};
</PRE>
<P>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:</P>
<P>
<PRE>#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
</PRE>
<P>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:</P>
<P>
<PRE>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
</PRE>
<P>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:</P>
<P>
<PRE>BOOL COptionsDialog::OnHelpInfo(HELPINFO *lpHelpInfo)
{
    if (lpHelpInfo-&gt;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-&gt;hItemHandle, 
            AfxGetApp()-&gt;m_pszHelpFilePath, 
            HELP_WM_HELP, (DWORD)aHelpIDs);
    }
    return TRUE;
}
</PRE>
<P>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.</P>


<BLOCKQUOTE>
	<P>
<HR>
<strong>TIP:</strong> If you've never seen the :: scope resolution operator used without
	a classname before it, it means &quot;call the function that isn't in any class,&quot;
	and in Windows programming, that generally means the SDK function. 
<HR>
<BR>
	</P>

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

	<P>HELP_CONTENTS and HELP_INDEX are obsolete and should be replaced with HELP_FINDER
	if you maintain code that uses them.&#160; 
<HR>


</BLOCKQUOTE>

<P>OnContextMenu() is even simpler. Add this code at the end of OptionsDialog.cpp:</P>
<P>
<PRE>void COptionsDialog::OnContextMenu(CWnd *pWnd, CPoint /*point*/)
{
     ::WinHelp((HWND)*pWnd, AfxGetApp()-&gt;m_pszHelpFilePath, 
          HELP_CONTEXTMENU, (DWORD)aHelpIDs);
}
</PRE>
<P>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.</P>
<P>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.</P>
<P>
<H2><A NAME="Heading11"></A>Writing Help Text</H2>
<P>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 <I>Designing
Windows 95 Help</I> discusses choosing an authoring tool.</P>


<BLOCKQUOTE>
	<P>
<HR>
<strong>TIP:</strong> 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, &quot;Building an ActiveX
	Server Application.&quot; 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. 
<HR>


</BLOCKQUOTE>

<P>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.</P>
<P><A HREF="javascript:popUp('11fig06.gif')"><B>FIG. 11.6</B></A><B> </B><I>Help
text, such as this boilerplate provided by AppWizard, can be edited in Word.</I></P>
<P>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:</P>

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

<P>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.</P>
<P>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.</P>
<P><A HREF="javascript:popUp('11fig07.gif')"><B>FIG. 11.7</B></A><B> </B><I>ShowString
displays the boilerplate Help generated by AppWizard.</I></P>
<P>With the programming out of the way, it's time to tackle the list of Help tasks
for ShowString from the &quot;Planning Your Help Approach&quot; section earlier in
this chapter. These instructions assume you are using Word.</P>
<P>
<H3><A NAME="Heading12"></A>Changing Placeholder Strings</H3>
<P>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:</P>

<DL>
	<DD><B>1. </B>Position the cursor at the very beginning of the document and choose
	Edit, Replace.
	<P>
	<DT></DT>
	<DD><B>2. </B>Enter <B>&lt;&lt;YourApp&gt;&gt;</B> in the Find What box and <B>ShowString</B>
	in the Replace With box.
	<P>
	<DT></DT>
	<DD><B>3. </B>Click Replace All.
</DL>

<P>Open afxprint.rtf and repeat these steps.</P>

<P>Switch back to afxcore.rtf and look through the text for &lt;&lt; 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:</P>

<DL>
	<DT></DT>
	<DD><B>1. </B>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.
	<P>
	<DT></DT>
	<DD><B>2. </B>The next section, after the page break, is a table describing the items
	on the File menu. Because there's no Send item on ShowString's File menu, remove
	the Send row of the File menu table.
	<P>
	<DT></DT>
	<DD><B>3. </B>The third section is a table listing the items on the Edit menu. Remove
	the Paste Link, Insert New Object, and Links rows.
	<P>
	<DT></DT>
	<DD><B>4. </B>The fourth section is for the View menu and doesn't need any changes.
	<P>
	<DT></DT>
	<DD><B>5. </B>The fifth section is for the Window menu. Remove the Split row from
	the Window menu table.
	<P>
	<DT></DT>
	<DD><B>6. </B>The sixth section is for the Help menu and doesn't need any changes.
	<P>
	<DT></DT>
	<DD><B>7. </B>The seventh section is for the New command (File menu). Remove the
	sentence about choosing a file type and the reminder to remove it.
	<P>
	<DT></DT>
	<DD><B>8. </B>Entirely delete the eighth section, the File New dialog box topic,
	including the page break before or after it, but not both. Whenever you remove a
	section, remove one of the breaks so that the file doesn't contain two consecutive
	page breaks.
	<P>
	<DT></DT>
	<DD><B>9. </B>The next topic is for the File, Open command and doesn't need any changes.
	<P>
	<DT></DT>
	<DD><B>10. </B>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.
	<P>
	<DT></DT>
	<DD><B>11. </B>Continue down the file until you find the File, Send topic and remove
	it entirely, including one page break either before or after it.
	<P>
	<DT></DT>
	<DD><B>12. </B>In the File Save As topic, remove the suggestion to describe other
	options because there are none.
	<P>
	<DT></DT>
	<DD><B>13. </B>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 8, 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 on adding support for the menu items to a later version of ShowString.
	Add some text to all these topics, explaining that they aren't implemented in this
	version of the product. Leave the shortcuts sections there so that users can find
	out why Ctrl+Z does nothing.
	<P>
	<DT></DT>
	<DD><B>14. </B>Continue down through the file to the Toolbar topic, where you find
	this reminder: &lt;&lt; Add or remove toolbar buttons from the list below according
	to which ones your application offers. &gt;&gt; Remove the reminder and delete the
	references to the Cut, Copy, Paste, Undo, First Record, Previous Record, Next Record,
	and Last Record buttons.
	<P>
	<DT></DT>
	<DD><B>15. </B>About halfway down the file is a topic for the Split command (Window
	menu). Remove the entire topic.
	<P>
	<DT></DT>
	<DD><B>16. </B>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.
	<P>
	<DT></DT>
	<DD><B>17. </B>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.
	<P>
	<DT></DT>
	<DD><B>18. </B>Because the ShowString view doesn't inherit from CScrollView, it doesn't
	scroll. Remove the Scrollbars Help topic and its page break.
	<P>
	<DT></DT>
	<DD><B>19. </B>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.
	<P>
	<DT></DT>
	<DD><B>20. </B>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.
	<P>
	<DT></DT>