Most commercially viable Windows Applications provide their own Help Systems. Adding custom help to your applications might seem a tall order, almost like writing another whole program. In fact, however, most applications use the built-in Windows help
system and only provide a Help file (HLP) which that system can use. In this chapter, you'll see how to create such a Help file.
You'll also gain an understanding of context-sensitive help in this chapter, and see how to incorporate it into your Visual Basic applications. You'll learn how to add to your Help system a secondary window, which may be used to display glossaries,
lists, sample code, or other information to be viewed concurrently with the main Help text.
In addition, this chapter examines different ways of adding graphic images to your Help files. You'll come to understand what is meant by "hot spots," and see how they may be used to jump between related Help topics. You'll also get a chance
to create some hypergraphics, a special kind of graphics which may contain multiple hot spots, each of which may be used to jump between topics, pop-up windows, or execute Help macros.
The last topic covered in this chapter is Help Macros. You'll receive a brief introduction to the more than 50 macros available in the WinHelp application, and see how many of them may be invoked to customize the way WinHelp works in conjunction with
your own Help files.
A Windows Help File is a specially compiled file with the HLP extension; it may be used with the built-in Windows help system to display help information pertaining to your Visual Basic application. The user may select an item from the Help Contents,
then view, search, and navigate the various Help screens by jumping from one topic to another. In addition to "topic-jumping," custom Help Systems often provide pop-up windows that give more detailed information about a particular keyword,
without actually jumping to another help page.
The process of creating your own custom help file can be broken down into four distinct steps. Here they are:
Each of these steps is discussed and demonstrated in this chapter.
The Help Text or Topic File is created with an editor, such as Microsoft Word, that is capable of saving text in the RTF format; it contains topics that are linked together via hypertext "jump phrases" or special hypergraphics (discussed later
in this chapter). Without linking, the topics in a Help file would be isolated islands of information; a user could not move from one topic to another. The most convenient way of linking topics is to create hypertext that enables users to jump between
topics or display a pop-up window. Such topic-jumps serve a purpose similar to cross-references in a book. These jumps consist of specially coded text or graphics that cause the WinHelp application to display another topic in the main Help window.
The Project File is a simple ASCII text file, with an extension of HPJ. The project file is used to pass information regarding the current Help project to the Help Compiler. This information includes the name and location of the RTF Topic file or files,
the directory location of any required bitmaps, errorlog specifications and warning levels, context-sensitive help information, and the location, size, and color of the Help System window.
To create the Help text file you must use an editor that is capable of saving files in the Rich Text Format (RTF). Microsoft Word is such a program, and will be used here. You're going to be working with underlined (Ctrl+U), double-underlined
(Ctrl+Shift+D), and hidden text (Ctrl+Shift+H), so it's not a bad idea to reveal all formatting codes while you create your RTF file.
In the Topic file, jump phrases (hypertext jumps) are double-underlined; they are followed immediately by a "tag" phrase (or context string), which is formatted as hidden text. In the Help window, hypertext jumps appear underlined and on color
monitors appear green. For example, a double-underlined phrase Export A File appears as Export A File in green text to the user.
Here, in general, are the steps required to establish a word or phrase as a jump in the topic file:
Caution
Now it's time to start Word and create your new help system's topic file. For the examples in this chapter, a Contact Manager system will be used. Figure 34.1 presents the Contact Manager Help Contents screen, the first page of Contacts.Rtf:
Figure 34.1. The Help Text File: Contents screen.
The first thing to notice here is the use of double-underlining. As already mentioned, words or phrases that are double-underlined here will appear as green, single-underlined jump phrases (or hypertext) in your Help System. When the user clicks on
them, control will jump to the page represented by the "jump tag," which is the hidden label immediately following the double-underlined jump phrase. (All codes are revealed here, so hidden text shows up with a light, dotted underline, as you can
see in Figure 34.1.) This is important: the jump tag must follow the jump phrase immediately, no spaces, and it must be hidden. In the example seen previously, "Import A File" is the jump phrase, "FILE_IMPORT" is the hidden tag;
"Export A File" is the phrase, "FILE_EXPORT" is the tag, and so on.
Once your Help Contents screen is completed, start a new page (in Word press Ctrl+Enter). The text for each jump page must be written on a separate word processing page. You connect the jump page text to the jump phrase by using the jump tag with a
custom footnote symbol. In fact there are three custom footnote symbols you may use, each invoking a different Help System feature. They are summarized here, in Table 34.1, and discussed in detail immediately afterward:
Symbol |
Description |
|
# |
Connects a jump page to its jump phrase by referencing the jump tag. |
|
$ |
References the jump page title, which will then appear in the Help System's Search list box. |
|
K |
References a keyword with which the user may search for a topic. |
The (#) footnote symbol is used to connect a help topic page with its related jump tag. In this way, jump tags identify each topic in the Help system. Each tag must be unique—you can assign it to only one topic in the Topic File. Assigning a jump
tag gives a topic an identifier that you can use to create jumps to that topic or to display it in a pop-up window. Although the Help Compiler can successfully compile topics that don't have a jump tag, the user of the Help system can't display them unless
they contain keywords (see next section). Although a jump tag has a practical limitation of 255 characters, you should keep the tags short so they are easier to enter into your Topic Files.
The ($) footnote symbol is used to identify a Help Topic Title. In your custom Help System, the title of a topic usually appears at the beginning of the topic, and in the Bookmark menu and Search list box, if the topic contains keywords. To place the
title at the beginning of the topic, type it as the first paragraph. You must define code for the title in a footnote for the title to appear correctly in the Bookmark menu and the Search dialog. Although the Help Compiler doesn't require that a topic have
a title footnote, only those topics in the main Help window or a secondary window that do have a title footnote appear correctly in the Bookmark menu.
The (K) footnote symbol specifies topic keywords, which may be used to search for related topics. The WinHelp application lists matching topics by their titles (as defined in the title footnote) in the Search dialog box. The keyword search facility
serves the same purpose as the index in a book. Because a keyword search is often the fastest way for users to access Help topics, you'll probably want to assign keywords to most topics in your Help system. You may specify more than one keyword per topic
by separating them with semi-colons in the topic footnote. Here's how a keyword footnote for a topic entitled Opening Text Files might appear:
K open;opening;text file;ASCII;existing;text only;documents
Tip
Take a look at Figure 34.2, which shows the primary jump pages and associated footnote symbolism you should add to Contacts.Rtf.
Figure 34.2. The Help Text File: Jump screens.
As you can see, the custom footnote symbol(s) must be the first item(s) on the jump page, followed by the Help Topic Title, and any other help text. To place a footnote using Word, you select Footnote from the Insert menu, which brings up the Footnote
and Endnote dialog box. You want to use a Custom symbol here, so click the Custom Mark option button and enter one of the three symbols described previously in Table 34.1 (the # is required to connect a tag to a jump phrase, and should be entered first).
When OK is clicked, the screen will split into two windows, with the jump page above, and footnotes below. You may then enter the appropriate jump tag, if you're inserting the # footnote, or any other text reference, such as a title or search keyword.
Here's Figure 34.3 for comparison.
Figure 34.3. The Help Text File: inserting custom footnotes.
Here, the arrow is pointing to the first of three footnotes associated with the Program Setup help screen. Notice the actual footnote symbols, side by side, in the Program Setup text page in the upper window. This is a valid jump page; its title will
appear in the Help Search list box; and Setup will serve as a search keyword.
There's something else to notice in Figure 34.3. In the Contact Manager: Program Setup help page, the phrase "Program Setup" is single-underlined, and there's a hidden tag "SETUP_DEF" associated with it. When a phrase is
single-underlined in your RTF file, the phrase will appear in green, with a light dotted underline, in your running Help System. Rather than jumping to another page, a click to this phrase will pop up a small window displaying a definition or additional
information. The phrase's hidden tag must still be referenced in a footnote on a separate page containing the pop-up window's text. (You can see this clearly in Figure 34.3).
Note
Okay, that's it for the first version of your Help Text file (you'll add much more to this file over the rest of this chapter). If you're working along with this chapter, you should save the file as Contacts.RTF (again, it must be saved in the RTF
format). The next step, Step 2, is to create the Help Project file.
The Help Project file is a simple text file that contains information to be passed to the Help Compiler. You may use your favorite text editor to create it. Figure 34.4 shows what it looks like for the first version of your new Help System.
Figure 34.4. The Help Project File: Contacts.HPJ.
All you're doing in the [OPTIONS] section is specifying an error log for any help compiler errors that may be generated; and you're setting an associated warning level. You're setting the Help System's title bar, and indicating that no special file
compression should take place.
The [FILES] section contains the fully qualified path to your Help Text file. If you're working along with the book, provide your own path here. The last section, [WINDOWS], contains a single line that sets the Help Window's size, position, and color.
That's it for Step 2. Save the file as Contacts.Hpj. Now it's compile time.
The third step is the easiest. To create your Contacts.HLP file, you use the Windows Help Compiler, a copy of which is included with Visual Basic's Professional Edition. The Help Compiler is located in the HC sub-directory of your VB installation
directory. Open a DOS Window and locate the HC directory. At the prompt type:
HC Contacts.HPJ
and press Enter. (Be sure to pass the correct name and location of your Help Project file. This example assumes the file is in the HC directory). You may get some error messages or warnings during the compile process. If so, they will most likely be due
to problems with your RTF file, such as improperly hidden or referenced tags. There's no penalty for compiling more than once, so fix the RTF source and try again.
Tip
The fourth and final step in setting up your own Custom Help System is to attach Contacts.HLP to your Visual Basic application, in this case the Contact Manager program.
This next step is where the rubber meets the road. If you're working along with the book, start a new project and add the form Contacts.FRM to it. You'll find this form, along with its associated database, CONTACTS.MDB, in the Chapter 34 section of the
CD.
Note
The first place to attach your new Help file is in the Project's Options dialog box, which may be accessed by selecting Tools | Options from the Visual Basic menu. Locate the Help File text box by clicking the Project tab and enter the full path to
Contacts.HLP. This will allow the user to get Help by pressing F1, in addition to accessing it through the Help Menu. (While you're here, you might want to make sure that frmContacts is the Startup Form.)
Next, create a standard code module called VBU_CH34. You need to add one DECLARE (for the API WinHelp() function), and a few helpful constants, to your VBU_CH34 module's general declarations section. Feel free to use the API Text Viewer, if you find it
easier than typing. Here's what must be added to VBU_CH34's general declarations section:
' Help engine declaration — All on one line. Declare Function WinHelp Lib "user32" Alias "WinHelpA" (ByVal hwnd As Long, ByVal lpHelpFile As String, ByVal wCommand As Long, ByVal dwData As Long) As Long ' Useful Constants which may be passed to WinHelp() Public Const HELP_CONTEXT = &H1 'Display topic identified by number in dwData Public Const HELP_QUIT = &H2 ' Terminate help Public Const HELP_INDEX = &H3 ' Display index Public Const HELP_HELPONHELP = &H4 ' Display help on using help Public Const HELP_SETINDEX = &H5 ' Set an alternate Index, if needed Public Const HELP_KEY = &H101 ' Display topic for keyword in dwData Public Const HELP_MULTIKEY = &H201 ' Lookup keyword in alternate table
Now use the Menu Editor to add a Help menu to the Contact Manager form. The Help menu will contain just two items, as seen in Table 34.2.
Visual Basic Object |
Property |
Design Time Setting |
|
Form |
Name |
frmContacts |
|
Menu Control |
Name |
mnuHelp |
|
|
Caption |
&Help |
|
Sub-Menu Item |
Name |
mnuContents |
|
|
Caption |
&Contents |
|
Sub-Menu Item |
Name |
mnuAbout |
|
|
Caption |
&About Contact Manager... |
Now here's the code to be added to mnuContent's Click event; it consists of a call to the API function WinHelp():
Private Sub mnuContents_Click() RV = WinHelp(frmContacts.hWnd,"c:\vb40\hc\contacts.hlp", HELP_INDEX,CLng(0)) End Sub
Here the first argument is the main form's Windows handle, which is just frmContact's hWnd property. The second argument points to the precise location of the compiled Help file. The third argument indicates that the Help contents (or Index) screen is
to be displayed; and the fourth may be used to provide context-sensitive help based on which program object the user was focused on when F1 was pressed (context-sensitive help is covered later in this chapter).
That's all there is to it. Now when you run your Contact Manager program, and select Contents from the Help menu (or Press F1), this is what you'll see (see Figure 34.5).
Figure 34.5. The Help File In Action: Help Contents.
When you click on the green, single-underlined keyword "Program Setup," and click on the dotted underlined keyword, you'll see this (see Figure 34.6).
Figure 34.6. The Help File In Action: Program Setup Jump screen.
Once you're in the Help System, you may use all the features you're familiar with, such as searching, stepping back, printing, or jumping to the top-level contents screen. When you're done with Help, exit in any of the usual ways.
In your testing, you may have noticed that it's possible to quit your program and still leave the Help System on the screen. This is because the WinHelp application is a stand-alone, shared resource available to all Windows programs. As a result, your
program's Help System has limited control over the WinHelp application. You may, however, force WinHelp to quit at the same time your own program is shut down. To do this, add the following line to frmContact's Unload event procedure:
Private Sub Form_Unload(Cancel As Integer) RetVal = WinHelp(hWnd, dummy$, HELP_QUIT, 0) End Sub
Here you make another call to WinHelp, except, this time, the third argument is a constant, which politely informs WinHelp that its services are no longer needed (the second argument is just a "dummy" place-holder).
That's it. You now have the beginnings of a full-blown Custom Help System. More importantly, you've acquired the skills to add simple custom help to all of your Visual Basic applications. In the next part of this chapter, you'll see how to enhance your
Help System by adding context-sensitivity and a secondary window.
In this section you'll add context-sensitive Help to your Contact Manager program. You'll also see how to redirect Help information to a second window, one that operates independently of the main help screen. In the process, you'll learn how to work
with the [MAP] and [WINDOWS] sections of the Help project file.
You're probably already familiar with the notion of context-sensitive help. If you've ever selected a Windows application object and then pressed F1 to find out more about it, you've used the application's context-sensitive help feature. The application
is smart enough to determine which object has the focus, read the object's context reference (see the next section), and send it to WinHelp, which in turn displays the appropriate help topic.
In developing context-sensitive Help, you're required to establish a set of context references so that WinHelp and your application pass the correct information back and forth. In Visual Basic applications, the context reference is a unique number,
stored in the HelpContextID property, which corresponds to a particular object—for example, to a menu item, form, control, or screen region. You can assign HelpContextIDs arbitrarily, but they must be unique for each object and you should not change
them afterward.
You then use these HelpContextIDs (or context numbers) to create links between your application and the corresponding Help topics. This is done by listing your topic file's jump tags, along with the associated object's HelpContextID, in the [MAP]
section of the Help project file (HPJ). When writing the [MAP] section, you can use either decimal or hexadecimal numbers to specify context numbers, but be sure to separate jump tags and context numbers by an arbitrary amount of white space, using either
space characters or tabs.
The following example illustrates two formats you can use in your project file's [MAP] section.
[MAP] dcmb_scr 30 ; Jump tags and decimal numbers representing dmxi_scr 31 ; unique HelpContextIDs... dmni_scr 32 dri_scr 33 dtb_scr 34 Edit_Window 0x0001 ; Or work a little harder and use Hex, Control_Menu 0x0002 ; if there's a good reason... Maximize_Icon 0x0003 Minimize_Icon 0x0004 Split_Bar 0x0005 Scroll_Bar 0x0006 Title_Bar 0x0007 Window_Border 0x0008
Caution
A secondary help window is one that operates independently of the main help screen. It may be sized, moved, scrolled through, or closed at the user's discretion. Secondary windows may display any help topic defined in the RTF Topic file, and are often
used to show a list, such as a help glossary, or examples of code, or any other topic the user might like to view simultaneously with the main help text.
As you saw earlier in this chapter, the [WINDOWS] section of the Help project file defines the size, location, and colors for the primary Help window. It's also where you may specify the dimensions and other attributes of any secondary window types you
might want to use.
Window characteristics are defined using the following syntax:
typename = caption, (hpos, vpos, width, height), sizing, (rgb), (ns_rgb), top
Here's a list describing each parameter:
|
typename |
Specifies the type of window that uses the defined attributes. For the primary Help window, this parameter is main. For a secondary window type, this parameter can be any unique name up to eight characters other than main. Any jumps that display a topic in a secondary window give this unique type name as part of the jump. |
|
caption |
The caption that appears on the title bar of different types of secondary windows. For the main Help window, this caption is given by the Help TITLE option in the [OPTIONS] section of the Help project file. |
|
hpos, vpos |
Horizontal and vertical position, respectively, of the window's upper-left corner. WinHelp uses a 1024 x 1024 coordinate system (starting at 0,0) and maps this coordinate system onto the resolution of the video card displaying the Help file. |
|
width, height |
Gives the default width and height of a secondary window. The width and height, like the x and y positions, are based on the resolution of the video adapter (as indicated for the hpos and vpos parameters in the preceding description). |
|
sizing |
Specifies how a secondary window is sized when WinHelp first opens it. This parameter is 0 for normal size and 1 for maximized. If the value is 1, WinHelp ignores the hpos, vpos, width, and height parameters given in the type definition. |
|
rgb,ns_rgb |
Three comma-delimited, three-digit values giving the background colors for the window and nonscrolling region (if any) in the window. The three digits represent the red, green, and blue (RGB) components of the color. If these colors are not given, the scrolling and nonscrolling areas are displayed with the normal system colors in the background. |
|
top |
Specifies whether a secondary window always remains on top of all other windows. This parameter is optional. If not specified, the secondary window normally moves behind other windows. If the value is 1, WinHelp keeps the secondary window on top of other windows. |
The following example shows the format of the [WINDOWS] section in a sample Help project file:
[WINDOWS] main = "Sample Help System", (0,0,1023,1023),,, (192,192,192) glossary = "Sample Glossary", (222,206,725,486),,, (192,192,192), 1
This section sets the color of the nonscrolling region of the main Help window to gray. It also defines a type of secondary window named glossary with the following characteristics:
Later in this chapter, you'll set up a secondary help window for your Contact Manager program, and see how to send information to it.
The first step in adding context-sensitive Help to your Visual Basic application is to open your project's Options Dialog Box (select Options from the Tools menu, and click the Project tab). Enter the name of your Help file in the Help File text box, or
click the ellipsis to browse for it. This setting can be a file name or a full path and file name; it indicates the file to be started when the user presses F1 from within your VB application. For now, during the development phase, use the full path.
Here's how the project Options Dialog Box might look (see Figure 34.7).
Figure 34.7. Adding context-sensitive help to your VB project.
Tip
The next step is to set the HelpContextID Property for any forms or controls you wish to be context-sensitive. This property is available for Visual Basic forms and for controls that can get focus (for example, text boxes, option groups, combo boxes,
and frames). It is not available for controls that can't get focus, such as lines, labels, and graphs. The HelpContextID Property sets the identifying number for a topic in the custom Help file specified in the project's Help File option. The setting for
the HelpContextID Property must be a Long integer between 0 and 2,147,483,647.
Table 34.3 displays the HelpContextID settings for significant controls on your Contact Manager's main form.
Visual Basic Object |
Property |
Design Time Setting |
|
Form |
Name |
frmContacts |
|
|
HelpContextID |
0 |
|
Menu Item |
Name |
mnuImport |
|
|
HelpContextID |
1 |
|
Menu Item |
Name |
mnuExport |
|
|
HelpContextID |
2 |
|
Menu Item |
Name |
mnuSetup |
|
|
HelpContextID |
3 |
|
TextBox |
Name |
txtCode |
|
|
HelpContextID |
4 |
|
DBCombo |
Name |
dbcContacts |
|
|
HelpContextID |
5 |
|
Frame Control |
Name |
fraCompany |
|
|
HelpContextID |
6 |
|
Frame Control |
Name |
fraContact |
|
|
HelpContextID |
7 |
|
Command Button |
Name |
cmdAdd |
|
|
HelpContextID |
8 |
|
Command Button |
Name |
cmdSave |
|
|
HelpContextID |
9 |
|
Command Button |
Name |
cmdCancel |
|
|
HelpContextID |
10 |
|
Command Button |
Name |
cmdDelete |
|
|
HelpContextID |
11 |
|
Command Button |
Name |
cmdQuery |
|
|
HelpContextID |
12 |
|
Command Button |
Name |
cmdReport |
|
|
HelpContextID |
13 |
Notice that you're giving a HelpContextID to the frames surrounding the company and contact information fields, rather than to each field individually. The idea is to have a single Help Topic for each of the field groups. The containership hierarchy
comes into play here: When a user presses F1 for help, Visual Basic checks to see if the current object has a HelpContextID; if it doesn't, VB looks for a HelpContextID in the object's container, and so on, back to form level. In this way, a user may be
focused on any field within the company frame, for example, and the proper help topic will be displayed when he or she presses F1.
Note
You must now modify your help project's HPJ file. Here's how it should look at this point:
[OPTIONS] errorlog = contacts.err title = Contact Manager Help compress = false warning = 3 [FILES] c:\vb40\hc\contacts.rtf [WINDOWS] Main = "Contact Manager Help", (0,0,750,1023),,,(192,192,192) Second = "Secondary Window", (512,512,511,511),,,(192,192,192),1 [MAP] FILE_IMPORT 1 FILE_EXPORT 2 PROG_SETUP 3 CODE_FIELD 4 CONTACTS_DD 5 COMPANY_FRAME 6 CONTACT_FRAME 7 ADD_BTN 8 SAVE_BTN 9 CANCEL_BTN 10 DELETE_BTN 11 QUERY_BTN 12 REPORT_BTN 13
You must also add the new topics shown in Figures 34.8 and 34.9 to your Contacts.RTF file; and each new topic must be appropriately footnoted to link it with the corresponding jump tag. Remember, in the RTF topic file, each topic must appear on a
separate page. The jump tag is shown in parentheses. Figure 34.10 shows the results for comparison.
Figure 34.8. Help Topics to add to Contacts.RTF.
Figure 34.9. Help Topics to add to Contacts.RTF (continued).
Figure 34.10. Contact Manager Context-Sensitive Help Topics.
Notice the double-underlining in the Add and Save button topics. In the Add topic, the word "Contact" is double-underlined, as is "Add Button" in the Save topic. In both cases, topic jumps are indicated, but the jump tags associated
with these hypertext phrases are formatted as hidden, remember, so you don't see them in the topics listed previously. Figure 34.11 presents how they'll look when formatting codes are revealed in Microsoft Word.
Figure 34.11. More Hidden Jump Tags.
When you create a jump to another topic, the WinHelp application assumes you want to display the topic in the main Help window. But you can code the jump to display the new topic in a secondary window. Use this syntax to code a jump that displays a
topic in a secondary window:
JumpTag>windowname
Immediately following the jump tag of the new topic is a greater than (>) sign followed by the name of the secondary window.
Now look again at Figure 34.11. The jump to the ADD_BTN topic is nothing new, but notice the jump tag for the double-underlined phrase "Contact" in the Add topic. Here, you're jumping to a new topic, CONTACT_DEF, but you're displaying it in
your secondary window, rather than the main help screen.
Now it's time to re-compile your Help file, then run the Contact Manager program. You should thoroughly test your new context-sensitive help feature. Notice that you may click on a field and press F1 to get related help information. Rather than clicking
command buttons (thereby executing their code), it might be better to test their context-sensitivity by using the Tab key to cycle through them, pressing F1 as you go. Be sure to see your secondary window in action by clicking the "Contact"
hypertext in the Add Button topic. Here, in Figure 34.12, is a sample session:
Figure 34.12. The secondary Help window in action.
You can increase clarity and add interest to a Help system by using graphics. There are some easy ways to add graphic images to your Help files. In this section, you'll receive a brief review of graphics types, and you'll be introduced to a special kind
of graphics called hypergraphics, which may be used like hypertext to jump between help topics.
You can include four types of graphics in your Help system. Table 34.4 describes each of the four types.
Graphic Type |
Description |
|
Bitmap |
A bitmap defines an image as a pattern of dots (pixels). A bitmap has the extensions .BMP or .DIB. Also called paint-type or raster graphics. |
|
Metafile |
A metafile defines an image as coded lines and shapes. A metafile has the extension .WMF. Only files that are compatible with Microsoft Windows version 3.0 or later can be included in the Help file. Also called draw-type or vector graphics. |
|
Hypergraphic |
A bitmap or metafile that contains at least one "hot spot." Hot spots are areas on the graphic that may be used to jump to Help topics or execute Help macros (covered later in this chapter), just like hypertext. An entire graphic may be used as a single hot spot. If a hypergraphic is to contain more than one hot spot, or if only part of the graphic is to be "hot," you must edit it using the Hotspot Editor (SHED.EXE). A hypergraphic usually has the extension .SHG. |
|
MRB |
A multiple-resoultion-bitmap (MRB) is compiled from several bitmaps with different screen resolutions by the Multiple-Resolution Bitmap Compiler (MRBC.EXE). A multiple-resolution bitmap has the extension .MRB. |
Note
There are two methods for including graphics in a Help file. You may place the bitmap or metafile directly in the topic file; or you may place a bitmap or metafile reference in the topic file. In this section you'll explore the advantages and
disadvantages of each method.
The easiest way to place a graphic into a Help topic file is to import the graphic or metafile directly from the Windows Clipboard into Word for Windows. You then simply paste the graphic where you want it to appear in the Help topic file. You may
format your text so it's positioned below or beside the graphic. When you save the Help topic file in rich-text format (RTF), and re-compile your Help file, the pasted bitmaps and metafiles are automatically included.
There are a few advantages to this method: it's simple, requiring only basic word processing skills; you're able to see the graphic whenever you work in the Help topic file; and you don't have to enter the graphic's location in the Help project file.
The disadvantages of this method are many in comparison. Here's a list:
To insert a graphic into a Help topic by reference, you include special "embraced" text that tells the WinHelp application the name of the bitmap file or metafile and how to position it with respect to related Help topic text. There are many
advantages to including Help file graphics by reference:
There are really only two slight disadvantages to the reference method of including graphics in your Help files: You can't see the graphic when you work in the topic file, and you have to enter the locations of the graphic files in the Help project
file. Although entering graphic locations in the Help project file is a simple task, any mistakes will cause errors at compile time.
Because the advantages of the reference method far outweigh those of the direct paste method, and because importing and pasting is more a word processing issue than a programming one, the rest of this chapter will focus on including graphics by
reference.
Placing a graphic by reference is a two-step process. First, you enter the reference text in the topic file where you want the graphic to appear. Then you enter the location of the graphic file in the Help project (.HPJ) file. One advantage to moving
all your help graphics files to the same directory (as was suggested in a note at the beginning of this chapter) is that you may inform the compiler of their location by adding a single line to your Help project file. This line identifies the directory
where bitmaps and other help-related graphics will be stored. Here's the listing of CONTACTS.HPJ, with the new line formatted in bold:
[OPTIONS] errorlog = contacts.err title = Contact Manager Help compress = false warning = 3 BMROOT = C:\VB40\HC [FILES] c:\vb40\hc\contacts.rtf [WINDOWS] Main = "Contact Manager Help", (0,0,750,1023),,,(192,192,192) Second = "Secondary Window", (512,512,511,511),,,(192,192,192),1 [MAP] FILE_IMPORT 1 FILE_EXPORT 2 PROG_SETUP 3 CODE_FIELD 4 CONTACTS_DD 5 COMPANY_FRAME 6 CONTACT_FRAME 7 ADD_BTN 8 SAVE_BTN 9 CANCEL_BTN 10 DELETE_BTN 11 QUERY_BTN 12 REPORT_BTN 13
Now, here's the syntax for creating references to graphics not directly included in a topic file:
{Command FileName}
Notice the "squiggly" braces; they are required. FileName is the name of the graphic file, and you do not include a path. The following table (see Table 34.5) lists the three commands you can use in creating a graphic reference.
Command |
Description |
|
bmc |
Aligns the graphic as a character. This command is used when you'd like the graphic to appear as a single character in a line of text, as a bullet or an em-dash, for example. |
|
bml |
Aligns the graphic at the left margin, and allows text to wrap or flow along the graphic's right edge. |
|
bmr |
Aligns the graphic at the right margin; text wraps along the graphic's left edge. |
With all three commands, the compiled Help file contains a single copy of the graphic data separate from any related text. The FileName given in the graphic reference includes only the file name, not the file's full path. The Help project (.HPJ) file
contains all the path information for graphics included by reference.
The Help Compiler treats a graphic inserted with a bmc reference as a character. After compiling the Help file, graphics aligned as characters appear on the type baseline at the location of the reference command. The graphic actually becomes part of the
paragraph, so any formatting applied to the paragraph also applies to the graphic. Text appearing above and below doesn't wrap around the graphic, but the size of the graphic may increase the line space between the line containing the graphic and the
preceding line in the text.
Caution
A bullet or other special symbol is a good use of a graphic as a character. Here is how a bmc reference might appear in a Help topic file, using a small bitmap, BULLET.BMP, as the bullet in a bulleted list:
{bmc bullet.bmp} The Add Button is used to add a new contact.
{bmc bullet.bmp} The Cancel Button aborts the Add operation.
The Help Compiler places a bml graphic along the left margin. Text wraps automatically along the right edge of the image. Text is aligned with the graphic's upper-right corner, so any white space saved at the top of the image affects the way text
appears in relation to the graphic. Normally, a bml reference appears at the beginning of a paragraph, which ensures proper wrapping of text around the graphic's right edge. The following example shows a typical bml reference:
{bml bozo.bmp}This paragraph text follows the bitmap reference...
Unless you want the first line of text to appear indented, do not put any space characters between the bml reference and the paragraph text.
You can also put a bml reference at the end of a paragraph. When you code a bml reference this way, WinHelp wraps the text up to the end of the paragraph, and then displays the graphic. After you compile the Help file, the image appears under the text
and to the left. Here's an example usage:
This paragraph text precedes the bitmap reference.{bml bozo.bmp}
The Help Compiler places a bmr graphic along the right margin. Text automatically wraps along the image's left edge. Under normal circumstances, you would place bmr references at the beginning of a paragraph. This ensures proper wrapping of text around
the image's left edge. Here's an example of a valid bmr graphic reference:
{bmr smokes.shg}Click the part of the cigarette you want to know more about.
Here, in Figure 34.13, is how such a graphic reference might look in your Help system:
Figure 34.13. A right-aligned graphic and text.
You can also place a bmr reference at the end of a paragraph. In this case, the text is wrapped up to the end of the paragraph, and then the graphic is displayed beneath the text and to the right. Here's an example of such a reference:
This paragraph text precedes the right-aligned bitmap.{bmr name.bmp}
You can do much more with graphics in your Help file than simply display them. The WinHelp application allows you to use graphics as hot spots. This means you can use graphics, such as icons or buttons, as jumps to particular topics or as hot spots for
pop-up windows or to execute Help macros.
It's time to make some enhancements to your Contact Manager's Help system. You'll edit the first page of your CONTACTS.RTF file to include a list of command buttons, each preceded by an em-dash bitmap graphic. The em-dash and the accompanying text will
become a hot spot for jumping to the appropriate Help topic.
Figure 34.14 is a screen-shot of your modified Help topic file's first page, with the arrow pointing to the new hot spots.
Figure 34.14. Using graphics as hot spots.
Notice the double-underlining, which indicates that you're creating hot spots for jumping to a new topic page, rather than opening a pop-up window. Here are the steps to follow in coding a graphic reference as a jump-topic (or pop-up window) hot spot:
Now you'll follow these steps in adding a hot spot graphic to your Contact Information topic, which you created earlier in this chapter. Locate that topic in CONTACTS.RTF. Here, in Figure 34.15, is how it will look once you've added the phone.bmp
reference as a hot spot.
Figure 34.15. The phone bitmap hot spot.
You can see how the phone bitmap reference is double-underlined, and you can see the hidden jump tag "AUTO_DIAL." You'll need to create the AutoDial topic page, which is also visible in Figure 34.15, and be sure to register its jump tag as a #
symbol footnote. (See the arrow in the footnote pane of Figure 34.15 for reference.)
Once you have your new hot spots properly coded, re-compile your Help file and try it out. You should be able to jump to each button's Help topic by clicking either the em-dash bitmap or the associated hypertext. You'll also be able to click the phone
graphic in the Contact Information topic, and be transported to the AutoDial Help page.
The preceding section showed you how to create a single hot spot in a graphic. Multiple hot spots can make the graphics in your Help file even more useful. To create more than one hot spot within a single graphic, you must create a hypergraphic.
A hypergraphic is a graphic (bitmap or metafile) with embedded hot spots that users can click to:
You create hypergraphics with the Hotspot Editor (SHED.EXE). This tool is conveniently located in the \VB40\HC directory, where the rest of your help-related files are currently stored. You can use the Hotspot Editor to open a bitmap (.BMP), a
device-independent bitmap (.DIB), or a Windows metafile (.WMF), and add hot spots to the existing graphic image. It then saves the graphic as a hypergraphic (.SHG) file.
Caution
Follow these general steps to create a hypergraphic:
Once you define the hot spots, the graphic is ready to be included by reference in any RTF topic file, from where it may be compiled into your Help file.
You'll work with the Hotspot Editor in this section, but first you will add three new topic pages to your CONTACTS.RTF. One topic will have a jump tag of HOT_SPOTS and be titled "Hot Spots and Hypergraphics"; it will have a title $ footnote,
as well as a keyword K footnote containing the search words "Hotspots;Hypergraphics." The other two topic pages will have only jump tag footnotes, SMOKE_ONLY and FILTER_ONLY, which will allow them to be displayed, when called upon, in a pop-up
window. Here, in Figure 34.16, is what they'll look like in your RTF topic file.
Figure 34.16. The hotspot and hypergraphics topics.
There are a couple of new things to notice here. First, your left-aligned bitmap reference is to SMOKES.SHG, which indicates that you're using a hypergraphic file (you haven't created it yet, but you will soon). The second thing to note is that there is
no double-or single-underlining, and no hidden jump tags. This is because all of the jumping will be handled by setting hot spot attributes in the Hotspot Editor, which is what you'll do next.
Before you can add hot spots to a graphic, you must open it in the Hotspot Editor.
After opening a graphic in the Hotspot Editor, you can create hot spots that link to topics, pop-up windows, or macros. When you compile with the Help Compiler, the hot spots you define become part the completed Help file.
A hot spot can be any rectangular area within the graphic. You draw hot spots on the graphic as you would a rectangle in any Windows drawing or painting program.
Here are the general steps to follow in creating a hot spot:
After you release the mouse button, the hot-spot rectangle displays eight sizing handles, indicating the currently selected hot spot. You can use the sizing handles to resize the rectangle.
After creating a hot spot, you must define the attributes that determine what happens when a user clicks the hot spot. To define these attributes, you use the Attributes dialog box, which is discussed next.
Follow these general steps in defining hot spot attributes:
The attributes defined for the hot spot now appear in the Hotspot Editor status bar.
The Attributes dialog box allows you to maintain important binding information about each hot spot you create. Here in Table 34.6 is a summary of the information contained in the Attributes dialog box.
Field |
Description |
|
Context string |
Specifies binding information for the hot spot. Can be either a jump tag (context string) or a macro. |
|
Type |
Indicates the type of action taken when the user selects the hot spot. You can jump to another topic, display a topic in a pop-up window, or run a Help macro. |
|
Attribute |
Specifies whether the hot spot is visible or invisible in the Help window. Hot spots are always visible in the Hotspot Editor. |
|
Hotspot ID |
Specifies a unique identifier for the hot spot. The hot-spot name is used internally by the Hotspot Editor and helps you identify hot spots in the Select dialog box. The Hotspot Editor automatically assigns an incremental number to the hot-spot name; however, you can type in a unique name. |
|
Bounding Box |
Displays the coordinates for the hot-spot rectangle: left, right, top, and bottom. The coordinates are measured in pixels and are restricted to the size of the graphic image. |
Now it's time to create your first hypergraphic. Open the Hotspot Editor (SHED.EXE in \VB40\HC). Select File Open from the menu, then locate SMOKES.BMP, which should be in the same directory. Follow the preceding steps to define two hot spots, as you
see them in Figure 34.17:
Figure 34.17. Defining hotspots with the Hotspot Editor.
Figure 34.17 shows the bounding rectangles for Hotspot 1 and Hotspot 2. It also shows the Attribute dialog box for Hotspot 1, which is the rectangle surrounding the smoke from the cigarette. The attributes for Hotspot 2, the cigarette filter, will be
very similar. Obviously, the Bounding Box coordinates will be different, and the jump tag (or context string) will be FILTER_ONLY, rather than SMOKE_ONLY.
Once the hot spots are drawn, and their proper attributes defined, save it as SMOKES.SHG, to indicate that it's a hypergraphic containing multiple hot spots. (You'll also want to be sure to name it SMOKES.SHG because that's the filename you use as your
topic file reference.)
That's it for hypergraphics. Close the Hotspot Editor, if you like, to clear the decks a little. You'll now need to re-compile your Help file. When that's done, fire up your Contact Manager program and thoroughly test your new, improved, custom Help
system. Because you added keywords for the Hotspot and Hypergraphics topic, you'll be able to locate it easily by using WinHelp's search feature. You'll be able to click on your hypergraphic's smoke, or filter, and get a nice pop-up window, like that seen
in Figure 34.18.
Figure 34.18. Hypergraphic hot spots in action.
More functionality can be added to your Contact Manager Help system by calling on the Windows Help macros, which you can use to customize the way the WinHelp application works with your Help files. There are more than 50 available macros that can be
used.
Help macros are routines built into the WinHelp application that allow you to further customize your own Help systems. Using macros, you can add and remove custom buttons and menus, change the function of buttons and menu items, execute applications
from within Help, and even execute functions from external dynamic-link libraries (DLLs).
The following series of tables constitute a categorized list of WinHelp macros and their descriptions. If a particular macro may be called using an abbreviated form, the abbreviation is given in parentheses at the end of the description.
Use the following macros (see Table 34.7) to access standard Help buttons, to create new buttons, or to modify button functionality and appearance.
Macro |
Description |
|
Back |
Displays the previous topic in the Back list. |
|
ChangeButtonBinding |
Changes the current function of a Help button. (CBB) |
|
Contents |
Displays the Contents topic of the current Help file. |
|
CreateButton |
Creates a new button and adds it to the tool bar. (CB) |
|
DestroyButton |
Removes a button from the tool bar. |
|
DisableButton |
Disables a button on the tool bar. (DB) |
|
EnableButton |
Enables a disabled button. (EB) |
|
History |
Displays the history list. |
|
Next |
Moves to the next topic in a browse sequence. |
|
Prev |
Displays the previous topic in a browse sequence. |
|
Search |
Opens the Search dialog box. |
|
SetContents |
Designates a specific topic as the Contents topic. |
The following macros may be used to access standard Help menu items, to create new menus, or to modify the performance of existing menus and menu items.
Macro |
Description |
|
About |
Shows the About dialog box. |
|
Annotate |
Displays the Annotate dialog box. |
|
AppendItem |
Appends a menu item to the end of a custom menu. |
|
BookmarkDefine |
Displays the Bookmark Define dialog box. |
|
BookmarkMore |
Displays the Bookmark dialog box. |
|
ChangeItemBinding |
Changes the assigned function of a menu item. (CIB) |
|
CheckItem |
Displays a check mark next to a menu item. (CI) |
|
CopyDialog |
Opens the Copy dialog box. |
|
CopyTopic |
Copies the current topic to the Clipboard. |
|
DeleteItem |
Removes a menu item from a menu. |
|
DisableItem |
Disables a menu item. (DI) |
|
EnableItem |
Enables a disabled menu item. (EI) |
|
Exit |
Exits the WinHelp application. |
|
FileOpen |
Displays the Open dialog box. |
|
HelpOn |
Displays the How To Use Help file. |
|
InsertItem |
Inserts a menu item at a given position on a menu. |
|
InsertMenu |
Adds a new menu to the Help menu bar. |
|
|
Sends the current topic to the printer. |
|
PrinterSetup |
Displays the Print Setup dialog box. |
|
SetHelpOnFile |
Specifies a custom How To Use Help file. |
|
UncheckItem |
Removes a check mark from a menu item. (UI) |
It's often convenient to use macros in creating links between Help topics. You might, for example, decide to create a button which, when clicked, jumps to a Glossary or terms, or example code. You may use the following macros to create hypertext links
to specific Help topics.
Macro |
Description |
|
JumpContents |
Jumps to the Contents topic of a specific Help file. |
|
JumpContext |
Jumps to the topic with a specific context number. (JC) |
|
JumpHelpOn |
Jumps to the Contents of the How To Use Help file. |
|
JumpId |
Jumps to the topic with a specific jump tag. (JI) |
|
JumpKeyword |
Jumps to the first topic containing a specified keyword. |
|
PopupContext (PC) |
Displays the topic with a specific number in a pop-up window. |
|
PopupId (PI) |
Displays the topic with a specific jump tag in a pop-up window. |
The remaining auxiliary macros are used to control or modify the behavior and appearance of the Help windows; to add or remove keyboard accelerators; to run external applications; and to manage and manipulate bookmarks.
Macro |
Description |
|
CloseWindow |
Closes the main or secondary Help window. |
|
FocusWindow |
Changes the focus to a specific Help window. |
|
HelpOnTop |
Places all Help windows on top of other windows. |
|
PositionWindow |
Sets the size and position of a Help window. |
|
AddAccelerator |
Assigns an accelerator key to a Help macro. (AA) |
|
RemoveAccelerator |
Removes an accelerator key from a Help macro. (RA) |
|
ExecProgram |
Starts an application. (EP) |
|
RegisterRoutine |
Registers a function within a DLL as a Help macro. (RR) |
|
DeleteMark |
Removes a marker added by SaveMark. |
|
GotoMark |
Jumps to a marker set by SaveMark. |
|
IfThen |
Executes a Help macro if a given marker exists. |
|
IfThenElse |
Executes one of two macros if a given marker exists. |
|
IsMark |
Tests whether a marker set by SaveMark exists. |
|
Not |
Reverses the result returned by IsMark. |
|
SaveMark |
Saves a marker for the current topic and Help file. |
In this section you'll get a closer look at several of the macros listed in the tables above, many of which you'll be using in the "How To Run Help Macros" section of this chapter. The look will include complete definitions, parameters, and
usage examples.
The CreateButton macro (or CB) is used to define a new button and display it in your Help system's button or tool bar. Here's how it's used:
CreateButton(ButtonId, Caption, Macro)
The ButtonId argument is a name that WinHelp uses to identify the button. This name must appear in quotation marks, and may be referred to in the DisableButton or DestroyButton macro, if you want to remove or disable the button, or in the
ChangeButtonBinding macro if you want to change the macro that the button runs in certain topics.
The second argument, Caption, is the text that appears on the button. This name must appear in quotation marks. To designate a letter for Alt Key access, place an ampersand (&) before it.
The Macro argument is the Help macro or macro string that is run when the user chooses the button. The macro must appear in quotation marks. Multiple macros in a macro string must be separated by semicolons (;).
Here's an example of the CreateButton macro. This call creates a new button labeled Clowns that jumps to a topic with the jump tag LIST_CLOWNS in the CIRCUS.HLP file when the button is chosen:
CreateButton("CLOWNS_BTN", "&Clowns", "JumpId(`circus.hlp', `LIST_CLOWNS')")
Notice the use of single quotes within double-quoted strings here. The third argument is a double-quoted string representing another macro. In fact, you're calling one macro from within another. This is perfectly legal as long as you don't mismatch
quotes and double-quotes.
Caution
The DisableButton macro (or DB) is used to dim or "gray out" a particular button when it is unavailable to the user. The syntax is simple, and here it is:
DisableButton(ButtonId)
The ButtonId is the identifier assigned to the button in the CreateButton macro. The button identifier must appear in quotation marks. A button disabled by the DisableButton macro cannot be used in the topic until an EnableButton macro is run.
This macro, abbreviated EB, re-enables a button disabled with the DisableButton macro.
Here's its simple syntax:
EnableButton("ButtonId")
Here, as with all button-manipulation macros, ButtonId is the identifier assigned to the button in the CreateButton macro. Again, ButtonId must appear in quotation marks.
This macro removes a button added with the CreateButton macro, causing it to disappear from your Help system's button bar. Here's how you call it:
DestroyButton(ButtonId)
Again, ButtonId is the identifier assigned to the button in the CreateButton macro. The button identifier must appear in quotation marks. The button identifier cannot duplicate an identifier used for one of the standard Help buttons.
The InsertMenu macro adds a new menu to the Windows Help menu bar. Here's its syntax:
InsertMenu("MenuId", "Caption", MenuPosition)
MenuId is the name that WinHelp uses to identify the menu; it must be enclosed in quotation marks. You'll use this identifier in the AppendItem macro (see next) to add menu items (commands) to the menu.
The Caption argument is the name for the menu that WinHelp displays on the menu bar. This name is case sensitive and must be enclosed in quotation marks. Within the quotation marks, place an ampersand (&) before the character you want to use for the
menu's accelerator key.
MenuPosition is a number specifying the position on the menu bar that the new menu name will have. This number must be an integer. Positions are numbered from left to right, with position 0 being the leftmost menu. WinHelp's default menu contains File,
Edit, Bookmark, Options, and Help, numbered 0 through 4, respectively.
The following example uses the InsertMenu macro to add a menu named Utilities to WinHelp's default menu:
InsertMenu("Menu_Utils", "&Utilities", 3)
Now Utilities will appear as the fourth menu on the Windows Help menu bar, between the Bookmark and Options menus. In this case, the user may press Alt+U to access the menu.
Caution
This macro is used to add menu items to the end of a menu created with the InsertMenu macro. Here's how it looks:
AppendItem("MenuId", "ItemId", "Caption", "Macro")
MenuId is the name used in the InsertMenu macro to create the menu. This name must be enclosed in quotation marks. The new item is added to the end of this menu.
The ItemId is the name that WinHelp uses to identify the menu item. This name is case sensitive and must be enclosed in quotation marks.
Caption is the name that is displayed on the menu for the item. This name is case sensitive and must be enclosed in quotation marks. As usual, you may use an ampersand (&) before the letter you want to use for the item's accelerator key.
Macro is Help macro or macro string that executes when the user chooses the menu item. The macro must be enclosed in quotation marks. Separate multiple macros in a string with semicolons (;).
Here's an example of how the AppendItem macro might be used to add an item to the Utilities menu created in the previous example:
AppendItem("Menu_Utils", "New_Item", "E&xample", "JI(`sample.hlp',`eg_012_topic')")
Choosing the menu item causes a jump to a topic with the eg_012_topic jump tag in the SAMPLE.HLP file. Note that the letter x serves as the accelerator key for this menu item.
This macro jumps to the topic with the specified jump tag in the specified Help file. Here's how it's used:
JumpId("FileName", "JumpTag")
FileName is the name of the Help file (.HLP) containing the jump tag. The file name must appear in quotation marks. If WinHelp does not find this file, it displays an error message and does not perform the jump.
JumpTag is the jump tag of the topic in the destination file. The jump tag must appear in quotation marks. If the tag does not exist, WinHelp jumps to the contents topic for that file instead.
The following example is the JumpId macro to jump to a topic with GLOSSARY as its jump tag in the Help file named CONTACTS.HLP:
JumpId("CONTACTS.HLP", "GLOSSARY")
Tip
This macro, abbreviated EP, launches a Windows-based application from within your custom Help system. Here's the syntax:
ExecProgram("CommandLine", DisplayState)
Here, CommandLine is the command line for the application to be executed. The command line must appear in quotation marks. WinHelp searches for this application in the current directory, followed by the Windows directory, the user's path, and the
directory of the currently displayed Help file.
The DisplayState argument is a value indicating how the application is displayed when executed. A value of 0 indicates normal, 1 indicates minimized, and 2 indicates maximized.
Here's an example of the ExecProgram macro in action; it runs the Windows NotePad program in its normal window size:
ExecProgram("notepad.exe", 0)
This macro closes the specified window, which is either the main WinHelp window or a secondary window. Its syntax is simple:
CloseWindow(WinName)
Here, WinName is the name of the window to close. The name main is reserved for the primary Help window. For secondary windows, the window name is defined in the [WINDOWS] section of the .HPJ file. This name must appear in quotation marks.
The following macro closes the secondary window named Glossary:
CloseWindow("Glossary")
This simple macro displays the Using Help file for the WinHelp application (same as the Using Help command on the Help menu). It requires no arguments and is called directly, like this:
HelpOn()
Help macros can be run when WinHelp first opens a Help file; when the user selects a particular topic in the Help file; and when the user chooses a button, menu item, or hot spot containing a macro. In this section you'll explore all three ways to run
macros while adding extra functionality to your Contact Manager's Help system.
If a macro appears in the [CONFIG] section of your Help project file (.HPJ), WinHelp runs that macro when it first opens the Help file. If more than one macro is listed in the [CONFIG] section, they are executed in their listed order.
Open CONTACTS.HPJ and add the following lines at the bottom of the file, beneath the [MAP] section:
[CONFIG]
InsertMenu("Menu_Tools", "&Tools", 4)
AppendItem("Menu_Tools","Calc_Item","&Calculator", "EP(`calc.exe',0)")
AppendItem("Menu_Tools","Note_Item","&NotePad","EP(`notepad.exe',0)")
CB("Glos_Btn","&Glossary","JumpId(`Contacts.hlp>Second',`GLOSSARY')")
CB("Help_Btn","&Help","HelpOn()")
CB("Exit_Btn","E&xit","Exit()")
You're accomplishing a lot here, in very few lines. The first macro creates a new menu called Tools in the fifth position of the default Help menu, that is, after Options but before Help. The next two macros add items to the new Tools menu, and specify
what should happen when the items are selected. In this case, you'll run the Windows calculator or notebook programs by calling the ExecProgram macros, shortened to EP here. (Again, pay close attention when entering the single quotes.)
The next three macros add buttons to WinHelp's default button bar. The first CB macro (remember, CB is short for CreateButton) creates a Glossary button which, when chosen, will cause a jump to the topic tagged GLOSSARY (which you'll define in the next
section) in your Help file named CONTACTS.HLP. But that's not all that happens here. Notice that the first argument contains a > symbol, which redirects the topic output to your secondary help window. This way the user will have the glossary displayed
in its own independent window.
The last two macros are much simpler. You're creating a button that will launch WinHelp's own Help On Help search window; and you're giving the user a button that will provide an alternate way of exiting your Help system. Macros that control Help
buttons, menus, or menu items remain in effect until the user quits WinHelp or opens a new Help file.
If a Help macro is called in a topic footnote, WinHelp runs that macro automatically whenever the user jumps to the topic. A user can jump to a topic by clicking a hypertext label or graphic hot spot; by clicking the Back button or a browse button; and
by selecting the topic from the history list or keyword search list.
To call a macro from a topic footnote, you use the special footnote symbol (!), an exclamation mark. Now open CONTACTS.RTF, and add a new page at the bottom. This is where you'll define your Glossary topic. Refer to Figure 34.19 for the topic text
(which is obviously not a complete glossary at this point), and for the associated footnotes.
Figure 34.19. The glossary topic and footnotes.
Almost everything here will be familiar to you (you've worked with such displays many times in this chapter). But there is something new to notice: the topic's last footnote, indicated by the arrow, is set with the ! symbol and identifies the macro to
run when this GLOSSARY topic is first displayed. In this case, you've anticipated that the user might appreciate having a place to jot down notes, so you'll open the Windows Notepad automatically.
Help macros can also be run from hot spots within a topic. WinHelp runs a hot-spot macro whenever the user chooses the hot spot containing that macro. A hot spot containing a macro is formatted like any other hot spot. The text or bitmap reference used
for the macro is double-underlined, and the macro (preceded by an exclamation point) is formatted as hidden text.
In CONTACTS.RTF, move to the first page, the Help Contents. What you'll do here is add a new bit of hypertext that, instead of jumping to a topic, will execute the About() macro, which simply displays your Help system's own About dialog box. Here, in
Figure 34.20, is how the Contents page will look.
Figure 34.20. Running the About() macro from hypertext.
Notice the arrow pointing to the new hot spot, in this case a hypertext label. The text is double-underlined, and the About() macro is called immediately after it. Don't forget to precede the macro with an exclamation point, and format the call as
hidden text.
That's it for running Help macros from your custom Help system. You should now re-compile and start up the Contact Manager program for testing. Be sure to admire and test all your new buttons and menu items, and notice that the NotePad starts up
whenever you switch to the Glossary topic. Here's Figure 34.21, showing your enhanced Help system in action.
Figure 34.21. The Macro-Enhanced Help System.
In this chapter, you created a custom help system for a Contact Manager application. You saw that it isn't necessary to write a help program of your own, that you may instead compile a Windows-compatible HLP file containing help text (including
hypertext "jumps") specific to your application. The information in this file is then presented to the user through Windows' own WinHelp application.
You also acquired an understanding of context-sensitive help, and saw how it may be added to your Visual Basic applications. You learned how to redirect Help text to a secondary window, one that operates independently of the main help screen, and which
may be used to display glossaries, lists, sample code, or any other information the user may wish to view concurrently with the main help text.
This chapter also examined different ways of adding graphic images to your Help files. You saw that you may set up references to your images, so that they may be used as hot spots for jumping between related Help topics. In addition, you were introduced
to a special kind of graphics called hypergraphics, which may contain multiple hot spots, each of which may be used to jump between topics, or pop up windows, or execute Help macros.
Finally, you received a brief introduction to the more than 50 Help macros available in the WinHelp application. You were given a detailed look at several of the more commonly used macros, and saw how they may be invoked to customize the way WinHelp
works in conjunction with your own Help files.
