| Tenouk C & C++ | MFC Home | Splitter Windows & Multiple Views 5 | Context-Sensitive Help 2 | Download | Site Index |


 

 

 

 

 

Module 15:

Context-Sensitive Help 1

 

 

 

 

 

 

Program examples compiled using Visual C++ 6.0 (MFC 6.0) compiler on Windows XP Pro machine with Service Pack 2. Topics and sub topics for this Tutorial are listed below:

  1. Context-Sensitive Help

  2. The Windows WinHelp Program

  3. Rich Text Format

  4. Writing a Simple Help File

 

 

 

Context-Sensitive Windows Help

 

Help technology is in a transition phase at the moment. The Hypertext Markup Language (HTML) format seems to be replacing rich text format (RTF). You can see this in the new Visual C++ online documentation via the MSDN viewer, which uses a new HTML-based help system called HTML Help. Microsoft is developing tools for compiling and indexing HTML files that are not shipped with Visual C++ 6.0. In the meantime, Microsoft Foundation Class (MFC) Library version 6.0 application framework programs are set up to use the WinHelp help engine included with Microsoft Windows. That means you'll be writing RTF files and your programs will be using compiled HLP files. This module first shows you how to construct and process a simple stand-alone help file that has a table of contents and lets the user jump between topics. Next you'll see how your MFC library program activates WinHelp with help context IDs derived from window and command IDs keyed to an AppWizard-generated help file. Finally you'll learn how to use the MFC library help message routing system to customize the help capability.

 

The Windows WinHelp Program

 

If you've used commercial Windows-based applications, you've probably marveled at their sophisticated help screens:  graphics, hyperlinks, and popups abound. At some software firms, including Microsoft, help authoring has been elevated to a profession in its own right. This section won't turn you into a help expert, but you can get started by learning to prepare a simple no-frills help file.

 

Rich Text Format

 

The original Windows SDK documentation showed you how to format help files with the ASCII file format called rich text format. We'll be using rich text format too, but we'll be working in WYSIWYG mode, thereby avoiding the direct use of awkward escape sequences. You'll write with the same fonts, sizes, and styles that your user sees on the help screens. You'll definitely need a word processor that handles RTF. I've used Microsoft Word for this book, but many other word processors accommodate the RTF format.

Several commercial Windows help tools are available, including RoboHELP from Blue Sky Software and ForeHelp from the Forefront Corporation. RoboHELP is a set of templates and macros for Microsoft Word, and ForeHelp is a stand-alone package that simulates WinHelp, giving you immediate feedback as you write the help system.

 

Writing a Simple Help File

 

We're going to write a simple help file with a table of contents and three topics. This help file is designed to be run directly from WinHelp and started from Windows. No C++ programming is involved. Here are the steps:

 

Create a \mfcproject \mymfc22 directory or any other directory that you have designated for your project.

 

Write the main help text file. Use Microsoft Word (or another RTF-compatible word processor) to type text as shown here. In this example it is Microsoft Word 2003.

 

Main help text file saved in RTF format.

 

Figure 1: Main help text file saved in RTF format.

 

Be sure to apply the double-underline and hidden text formatting correctly and to insert the page break at the correct place.

To see hidden text, you must turn on your word processor's hidden text viewing mode. In Word, choose Options from the Tools menu, click on the View tab, and select All in the Formatting marks (Nonprinting Characters – for older version) section or click the Show/Hide (   )icon.

 

Enabling the Word’s Show/Hide view option.

 

Figure 2: Enabling the Word’s Show/Hide view option.

 

Insert footnotes for the Table Of Contents screen. The Table Of Contents screen is the first topic screen in this help system. Using the specified custom footnote marks, insert the following footnotes at the beginning of the topic title.

 

Footnote Mark

Text

Description

#

HID_CONTENTS

Help context ID

$

SIMPLE Help Contents

Topic title

 

Table 1

 

When you're finished with this step, the document should look like this.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Our completed main help text file.

 

Figure 3: Our completed main help text file.

 

Insert footnotes for the Help Topic 1 screen. The Help Topic 1 screen is the second topic screen in the help system. Using the specified custom footnote marks, insert the footnotes shown here.

 

Footnote Mark

Text

Description

#

HID_TOPIC1

Help context ID

$

SIMPLE Help Topic 1

Topic title

K

SIMPLE Topics

Keyword text

 

Table 2.

 

Clone the Help Topic 1 screen. Copy the entire Help Topic 1 section of the document, including the page break, to the clipboard, and then paste two copies of the text into the document. The footnotes are copied along with the text. In the first copy, change all occurrences of 1 to 2. In the second copy, change all occurrences of 1 to 3. Don't forget to change the footnotes. With Word, seeing which footnote goes with which topic can be a little difficult, so, be careful. When you're finished with this step, the document text (including footnotes) should look something like this.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

-------------------------------------------------------------------------

Creating other help topics by copying/cloning.

 

Figure 4: Creating other help topics by copying/cloning.

 

Save the document. Save the document as \mfcproject\mymfc22\Simple.rtf. Specify Rich Text Format as the file type.

 

Saving our main help text file in RTF format.

 

Figure 5: Saving our main help text file in RTF format.

 

Write a help project file. Using Visual C++ or another text editor, create the file \mfcproject\mymfc22\Simple.hpj, as follows:

 

[OPTIONS]

CONTENTS=HID_CONTENTS

TITLE=SIMPLE Application Help

COMPRESS=true

WARNING=2

 

[FILES]

Simple.rtf

 

This file specifies the context ID of the Table Of Contents screen and the name of the RTF file that contains the help text. Be sure to save the file in text (ASCII) format.

Build the help file. From Windows, run the Microsoft Help Workshop (HCRTF.EXE) utility (located by default in Program Files\Microsoft Visual Studio\Common\Tools).

 

The HCRTF.EXE utility.

 

Figure 6: The HCRTF.EXE utility, just double click to launch it.

 

Open the file \mfcproject\mymfc22\Simple.hpj, and then click the Save And Compile button.

 

Simple.hpj file opened in HCRTF.EXE program.

 

Figure 7: Simple.hpj file opened in HCRTF.EXE program.

 

Compiled Simple.hpj file generating Simple.hlp file.

 

Figure 8: Compiled Simple.hpj file generating Simple.hlp file.

 

 

This step runs the Windows Help Compiler with the project file Simple.hpj. The output is the help file Simple.hlp in the same directory.

 

If you use Word 97 to create or edit RTF files, make sure you use version 4.02 (or later) of the HCRTF.EXE utility. Earlier versions of the HCRTF.EXE cannot process the rich text flags generated by Word 97.

 

Run WinHelp with the new help file. From Windows Explorer, double-click the file \mfcproject \mymfc22\Simple.hlp. The Table Of Contents screen should look like this.

 

Our Simple.hlp program.

 

Figure 9: Our Simple.hlp program.

 

Now move the mouse cursor to Topic 1. Notice that the cursor changes from an arrow to a pointing hand. When you press the left mouse button, the Help Topic 1 screen should appear, as shown here.

 

Exploring our help file.

 

Figure 10: Exploring our help file.

 

The HID_TOPIC1 text in the Table Of Contents screen links to the corresponding context ID (the # footnote) in the topic page. This link is known as a jump. The link to Help Topic 2 is coded as a pop-up jump. When you click on Topic 2, here's what you see.

 

Pop-up window for our help file.

 

Figure 11: Pop-up window for our help file.

 

Click the WinHelp Contents pushbutton. Clicking this button should take you to the Table Of Contents screen, as shown at the beginning of the previous step. WinHelp knows the ID of the Table Of Contents window because you specified it in the HPJ file.

 

Click the WinHelp Index pushbutton. When you click the Index button, WinHelp opens its Index dialog, which displays the help file's list of keywords. In Simple.hlp, all topics (excluding the table of contents) have the same keyword (the K footnotes): SIMPLE Topics. When you double-click on this keyword, you see all associated topic titles (the $ footnotes), as shown here.

 

Invoking WinHelp Index.

 

Figure 12: Invoking WinHelp Index.

 

What you have here is a two-level help search hierarchy. The user can type the first few letters of the keyword and then select a topic from a list box. The more carefully you select your keywords and topic titles, the more effective your help system will be.

 

 

Continue on next module...part 2.

 

 

 

 

 

 

Further reading and digging:

  1. MSDN MFC 7.0 class library online documentation.

  2. MSDN MFC 9.0 class library online documentation - latest version.

  3. MSDN Library

  4. Windows data type.

  5. Win32 programming Tutorial.

  6. The best of C/C++, MFC, Windows and other related books.

  7. Unicode and Multibyte character set: Story and program examples.

 

 

 

 


 

| Tenouk C & C++ | MFC Home | Splitter Windows & Multiple Views 5 | Context-Sensitive Help 2 | Download | Site Index |