لطفا منتظر باشید ...
The Windows WinHelp Program
If you've used commercial Windows-based applications, you're familiar with their sophisticated help screens, in which graphics, hyperlinks, and pop-ups abound. At some software firms, including Microsoft, help authoring has been elevated to a profession in its own right. This chapter 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 using the ASCII file format called Rich Text Format (RTF). We'll be using RTF too, but we'll be working in WYSIWYG mode to avoid the direct use of awkward escape sequences. You'll write with the same fonts, sizes, and styles that users will see on the help screens. You'll definitely need a word processor that handles RTF. Microsoft Word is just fine, but many other word processors also accommodate the RTF format.
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 \vcppnet\Ex19a subdirectory.
Write the main help text file. Use Word (or another RTF-compatible word processor) to type text as shown here.
Be sure to apply the double-underline and hidden text formatting correctly and to insert the page break at the correct place.
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 |
When you're finished with this step, the document should look like this:
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 these footnotes:
Footnote Mark | Text | Description |
|---|---|---|
# | HID_TOPIC1 | Help context ID |
$ | SIMPLE Help Topic 1 | Topic title |
K | SIMPLE Topics | Keyword text |
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 will be 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 like this:
Save the document. Save the document as \vcppnet\Ex19a\
Simple.rtf . Specify Rich Text Format as the file type.Write a help project file. Using Visual C++ .NET or another text editor, create the file \vcppnet\Ex19a\
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) utility (located by default in Program Files\Microsoft Visual Studio .NET\Common7\Tools). Open the file \vcppnet\Ex19a\
Simple.hpj , and then compile the help file by choosing Compile from the File menu.The Windows Help Compiler will run with the project file Simple.hpj . The output will be the help file Simple.hlp in the same directory.Run WinHelp with the new help file. In Windows Explorer, double-click on the file \vcppnet\Ex19a\
Simple.hlp . The Table Of Contents screen should look like this:
Now move the 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:
The HID_TOPIC1 text on the Table Of Contents screen links to the corresponding context ID (the # footnote) on the topic page. This link is known as a jump.The link to Topic 2 is coded as a pop-up jump. When you click on Topic 2, here's what you'll see:
Click the WinHelp Contents button. Clicking this button should take you to the Table Of Contents screen, as shown at the beginning of step 9. WinHelp knows the ID of the Table Of Contents window because you specified it in the HPJ file.
Click the WinHelp Index button. When you click the Index button, WinHelp opens its Index dialog box, 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'll see all associated topic titles (the $ footnotes), as shown here:
What we 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.
An Improved Table of Contents
You've been looking at an "old-style" help table of contents. The latest Win32 version of WinHelp can give you a modern, tree-view table of contents. All you need is a text file with a CNT extension. Add a new file,
Simple.cnt , in the \vcppnet\Ex19a directory, containing this text::Base Simple.hlp
1 Help topics
2 Topic 1=HID_TOPIC1
2 Topic 2=HID_TOPIC2
2 Topic 3=HID_TOPIC3
Notice the context IDs that match the help file. The next time you run WinHelp with the
Simple.hlp file, you'll see a new contents screen similar to the one shown here:
You can also use HCRTF to edit CNT files. The CNT file is independent of the HPJ file and the RTF files. If you update your RTF files, you must make corresponding changes in your CNT file.
