Almost every Windows application provides its own Help system. If you think that adding custom Help to your application is as hard as creating your application, you are wrong. In fact, most applications use the built-in Windows Help system and provide only a Help file (.HLP) that the Windows system can use. Deciding what to put into the Help file is the hardest part of the process.
While this chapter cannot answer the question of what should be in the Help file, it will show you how to build, compile, and test the Help files you need to add to your Visual Basic application. In addition, you will see the different techniques you can use to include Help in your application.
Included on the Visual Basic 5 Product CD-ROM is the Microsoft Windows 95 Help Workshop. This workshop comes with the tools and information that you need to create professional looking Help files for Windows 95- and Windows NT-based applications. To install the Help Workshop from your CD-ROM drive, run \tools\hcw\setup.exe and respond to the wizard's prompts. Before this workshop was available, programmers were required not only to create the text documents that are needed to build the Help file, but also to understand how to create the Help project file that contains the commands for the Help compiler.
The Help Workshop is an easy-to-use interface that assists the programmer to create and maintain the Help project files. Included with the Workshop are the following tools:
If you've used WinHelp before, the good news is that your previous Help files will still work; the bad news is that there are more features to learn. You may have noticed that the initial Help Contents dialog box that is displayed has been changed. Prior to WinHelp 4.0, the Contents box for a Help file looked like the one shown in Figure 21.1.
FIG. 21.1
Help files use a standard Contents display that has become very familiar to
most Windows users.
Now the Help files show a more sophisticated look for the Contents display called the Help Topics dialog box (see Figure 21.2).
FIG. 21.2
The Help Topics dialog box displays the main Help topics in a new way.
This change and many other new features and improvements have been added to the WinHelp system to enhance how the Help system is used. The Help Workshop enables you to author Help files that take full advantage of all these new features.
The new Help Topics dialog box is the "way in" to your application's Help information. It provides three tabs to aid the user in finding the information needed. The information that is displayed on these tabs fully depends on how you build your Help topic files and the content file. In the section "Creating and Testing a Help System," you will learn how to create the required files to make full use of the Help Topics dialog box. Each tab has its own unique features, which are discussed next.
Contents Tab The Contents tab lets you display the Help topics by title in the categories that you set up (see Figure 21.3). Jumps to topics in other Help files can be created, as well as the capability of running macros. In addition, the topics of the Contents tab can be updated automatically whenever a newer release of the application is installed on the user's PC. On the display, headings are displayed as book icons, while jumps to topics or macros are displayed as page icons.
Index Tab The old WinHelp 3.1 Search dialog box has been revamped and replaced by the Index tab. The Index tab gives users the capability to look for topics based on keywords that you add to your Help file (see Figure 21.4). These keywords then are automatically sorted from A to Z, and any second-level entries are indented.
Find Tab The Find tab is used to search the Help file for topics that contain a specific word or phrase that the user specifies in the top input box on the tab (see Figure 21.5). The unique feature of the Find tab is that the word list required for the Find tab to work is created when the user clicks the Find tab. This means that you don't have to build and then ship large word list files on your program disks for this to work.
FIG. 21.3
The Contents tab gives users access to the Table of Contents for a Help system.
FIG. 21.4
The new Index tab gives users an easier way to look for specific topics.
Besides the new interface for the user, WinHelp 4.0 has many other features included that enable you to enhance the look and interaction for the user with the Help System. Some of these features are:
FIG. 21.5
Using the Find tab is a three-step process to find exactly what is needed
to answer a question.
The Help Workshop is a Windows-based tool that enables you to compile, test, and view your working Help files. It can be used to create the project file, which is required to compile your Help file, and the contents file, which is used to create the information displayed in the Contents tab. The Microsoft Help Workshop has a user interface that makes for an easy way of creating and compiling your Help files. When working with a Help file, the main display shows the project file for the Help system that you are creating (see Figure 21.6).
FIG. 21.6
The Help Workshop shows an existing Help project file.
Besides showing the project file, the buttons on the right side of the display enable you to modify any section of the project file. Each section of the project file are represented by one of the buttons. These sections are as follows:
Button | Descripton |
Options | Displays a multi-tabbed dialog box that enables you to modify any of the compile options for your Help system. |
Files | Specifies the locations of all the Topics files used in the Help system. |
Windows | Defines the size, location, and properties of all windows that are used by the Help system. |
Bitmaps | Specifies the search path for any bitmaps used in the Help system. |
Map | Associates topic IDs with context numbers for context-sensitive Help. |
Alias | Associates one set of topic IDs with an alternative set of topic IDs. |
Config | Defines one or more WinHelp macros that are run when WinHelp opens the Help file. |
Data Files | Defines the Baggage section that lists the files that Help Workshop stores within the Help file's internal file system. The files may then be read by a Help DLL. |
CAUTION: You cannot directly modify any text that is displayed in the main project file listing.
Another important feature of the Help workshop is the capability to help you create the Contents file needed to drive the Contents tab. The Contents File Editor helps you build the category headings with their related topic jumps and macros (see Figure 21.7). For each line in this file, you can set the Title, Topic Id, the Help file to use if it is not the main Help file, and finally the Windows type to use when displaying the information.
FIG. 21.7
Creating the Help Contents file is easy when using the Contents File Editor.
The best way to learn how to use these tools is to use them. In the next section, you will see how to create a small Topics file that includes jumps, pop-ups, and macros. You use the workshop to create the project file and the contents file. Then, when you are finished creating the Help system, you will see how to use the workshop to test the completed Help files.
A Help file is made up of several different files that are created by you. Some of these files will contain the text or graphics that appear in your finished Help topics. Other files will contain the information that controls how your Help windows will look and act. In the compile process, the Help Workshop takes all these files and turns them into a finished Help file. The best part of this process is that if you do not like any part of the finished file, you can quickly change it and recompile.
By using the Help Contents tab, the user can select an item to view, and from there, jump from one topic to another based on what the user needs to find out. In addition to topic jumping, application Help systems usually provide pop-up windows that give detailed information about a particular word, phrase, or picture, without actually jumping to another Help page. The steps needed to create your own custom Help file are the following:
When you're finished, only two files need to be distributed with your application. These are the actual Help file (.HLP) and the Contents file (.CNT). Because WinHelp comes with Windows 95 and Windows NT, your users can open your Help file by double-clicking its icon or accessing it from the Help menu. If a Contents file was created, the Help Topics dialog box will be displayed. If not, then the topic specified will be displayed instead.
Help files can be as simple or as complex as you want them to be. To create a topic file, you need to know how to:
NOTE: In this chapter, Microsoft Word is used. If however, you are using WordPerfect, refer to its Help documentation on how to perform the preceding tasks.
The Help text or topic files contain topics that are linked together via hypertext jump words or special hypergraphics. 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 easiest way to link topics is to create hypertext that can either jump between topics or display a pop-up window. These topic-jumps serve the same purpose as cross-references in a book. These jumps consist of coded text or graphics that tell the WinHelp application to display another topic in the main Help window.
Topic files are nothing more than fancy word processing files. A completed Help file is a combination of topics that provide the user with information when needed. When designing and creating topic files, you will want to decide what the flow will be from one topic to another. By looking at the Visual Basic 5 Help topics, you can see how the Table of Contents and topics flow as the user follows a thought from the first topic to the last for a particular question. Figure 21.8 shows the topics diagram for a subset of the Visual Basic 5 Help system.
FIG. 21.8
A flow chart of how the topics relate to each other.
Each topic is directly related to a page in the document file that you create. In addition, because Help is an online facility, each topic can be as long as needed. To create a Help text file, you work with the following formatting commands: underlined, double-underlined, and hidden text. Therefore, it's not a bad idea to reveal all non-printing characters while you create your RTF file. A topic file contains the words and pictures that make up your Help file. To create most topic files, all you need to do is type text for the topics, separate topics with page breaks, add footnotes, add graphics, and use character formatting.
TIP: When working with topic files, it is easier to put the formatting command buttons on the toolbar. This makes it easy to use the commands without looking for them on the related options dialog boxes.
When entering text for a topic file, hypertext jumps are created by double-underlining the jump phrases; any pop-up phrases are formatted with single-underlining. Both jump phrases and pop-up phrases have the context string which is formatted as hidden text.
CAUTION: Be careful not to include spaces between the double-underlined text and the hidden text.
Getting the Text In Open your favorite word processing program to start the text entry process. For the examples in this chapter, small text files are used to demonstrate hyperlinks, pop-ups, and other features of the Help system. Figure 21.9 displays the Contents topic page for a completed Help file.
FIG. 21.9
The standard topics content page shows all hypertext formatting.
The first thing to take note of in Figure 21.9 is the use of double-underlining. Double- underlined words and phrases appear as green, single-underlined hypertext in your Help system. When the user clicks these words or phrases, WinHelp automatically jumps to the page referenced by the jump tag, which is the hidden text immediately following the jump phrase.
Your demo Help file will actually contain three topic pages, one pop-up page, and one secondary topic. As the first page of your topic file, enter three lines listing the three topics that will be covered in this file:
Next, enter the text shown in Listing 21.1 as the second page of your topic file.
The Constitution of the United States has been the supreme law of the nation since 1789. Drafted at the Constitutional Convention in Philadephia, it calls for a government of limited and delegated powers. Fifty-five delegates representing twelve states drafted the document; all 13 states had ratified it by May 29, 1790. The First U.S. Congress drafted 12 amendments, from which the states ratified 10. Those 10 amendments became known as the Bill of Rights.
Now, insert a page break into the file and then enter the text shown in Listing 21.2. Repeat this process for the remaining text in Listings 21.3, 21.4, and 21.5.
We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.
The Declaration of Independence is the document in which American colonists proclaimed their freedom from British rule. The Second Continental Congress, with representatives of the 13 British colonies in America, adopted the declaration on July 4, 1776. The document included an expression of the colonists' grievances and their reasons for declaring freedom from Britain. The Declaration of Independence's eloquent rhetoric and political significance rank it as one of the great historical documents.
When in the Course of human events, it becomes necessary for one people to dissolve the political bands which have connected them with another, and to assume among the Powers of the earth, the separate and equal station to which the Laws of Nature and of Nature's God entitle them, a decent respect to the opinions of mankind requires that they should declare the causes which impel them to the separation.
The American flag contains 13 stripes to signify the original 13 colonies and the stars on the blue background represents the states of the union.
When completed, your document should look like the one displayed in Figure 21.10. These separate pages of text will become your final Help file, with a little formatting.
FIG. 21.10
The Word document shows the text that was entered onto different pages.
Labeling the Different Topics ow that you have five topics, you need to identify each one by assigning a topic ID, which makes it possible for WinHelp to find them. Footnotes are used to create these topic IDs. You will use three symbols in the footnote area to set up the important features of the Help system. Table 21.1 lists each of these symbols and their functions.
Symbol | Description |
# | Connects a jump page to its jump word or phrase by referencing the jump tag |
$ | References the jump page title, which will appear in the Help system's Search list box |
K | Defines a keyword that the user can then search for in the Index tab |
In the footnote section, the # symbol is used to connect a topic page with its jump tag. This identifies each topic in the Help system. Each tag must be unique within the Help system. Although the compiler can successfully compile topics that do not have jump tags, the user of the Help system will be unable to view these topics unless they contain keywords for which to search.
The $ is used to define the title for each Help topic in the file. Titles usually appear at the beginning of the topic, and in the Bookmark menu and Search list box, if the topic contains keywords.
The final symbol, K, is used to specify the topic keywords that may be used to search for related topics. The WinHelp system lists matching topics by their titles in the Search dialog box. This symbol is the only one of the three that allows listing of multiple words or phrases. The following footnote example shows a keyword list for the topic titled "aligning," which is found in the Microsoft Word Help system.
K drawing object;graphics;tables;text
The custom footnote symbol(s) must be the first items that appear on the jump page, followed by the Help topic title, if any, and then by any text that you want in the topic. To insert a footnote in Word, position the cursor at the beginning of the page and then select Footnote from the Insert menu. This displays the Footnote and Endnote dialog box (see Figure 21.11). You want to use the Custom Mark selection on the form.
FIG. 21.11
Inserting footnotes is easy by using the Footnote and Endnote dialog box.
Click the Custom Mark option button and then enter one of the three symbols previously described. When you click the OK button, the screen splits into two windows, one showing the jump page, and the other showing the footnotes (see Figure 21.12).
FIG. 21.12
The Word document shows the footnotes that were added.
Set the footnotes in Table 21.2 for each of the pages in the topic file. The custom footnote symbol that you should use is the #.
Page | Footnote Text |
1 | Contents |
2 | Constitution |
3 | Preamble |
4 | Declaration |
5 | Main |
6 | Flag |
By setting these footnotes, you can now set the hyperlinks within each topic to allow the user to jump between topics. To set a link on a topic, you need to format the word or phrases that you want as the links. On the first page of the Help topic file, place the cursor at the end of the word Constitution and enter the topic ID phrase Preamble. Now, select the word Constitution and single-underline it. Next, select the word Preamble following the period and format it as Hidden text. This instructs the WinHelp system to display a pop-up window showing the text on the Preamble topic page. Notice that the hidden text that was entered matches the topic ID for the page to jump to.
Now, perform the same tasks for the first occurrence of Declaration on page two, having it jump to the topic ID of Main by using a double-underline to create a jump instead of a pop-up. Finally, don't forget to set the three topics listed on page one of the file. All three of these jumps should be double-underlined. The Topics file should now look like the one displayed in Figure 21.13.
FIG. 21.13
The topics file shows the hyperlinks and footnotes for each topic in the file.
The last thing to add to this initial demo is a picture. To keep it simple, a picture of an American flag is used. This bitmap is found on this book's companion CD as file FLAG.BMP. The best way to insert a picture is to use the bitmap statement. The syntax of this statement is as follows:
{bmx[t] filename.ext}
For x, substitute a value from the list in Table 21.3.
Value | Description |
C | Aligns the graphic as a text character in the exact same place in the paragraph where the statement occurs |
L | Aligns the graphic along the left margin |
R | Aligns the graphic along the right margin |
Insert the name of your bitmap in place of filename.ext. You can also specify t if you want the graphic to be transparent, meaning that any white pixels in the graphic will be replaced with the background color of the topic.
Save your Help topics file and close your word processor. You are now ready to create the project file that you will use to compile the Help topics file into a working Help system.
As described earlier in this chapter, the project file contains all the instructions to compile your Help topic files into a working Help file that WinHelp will be able to use. When you use the Help Workshop to create the project file, the minimum settings you need are specified when you select New from the File menu. The remaining settings that you need to specify depend on the size and complexity of the Help file that you are creating. First, you need to start the Help Workshop. From the Start menu, choose Programs, Microsoft Help Workshop, Help Workshop.
Creating a New Help Project After the workshop starts, choose File, New, select Help Project from the New dialog box, and then click OK. This displays the Project File Name selection dialog box. Enter the name USDemo as the project name and click Save. Don't worry about the Save as Type box; you can leave it blank. The workshop screen should now display the default options for your project (see Figure 21.14).
FIG. 21.14
When creating a new Project file, default options are displayed to you.
The next most important thing you need to do is to tell the project file the names and locations of your topic files. To do this, click the Files button on the right side of the screen. This displays the Topic Files dialog box where you can Add or Remove file references from the project (see Figure 21.15).
FIG. 21.15
Add the Topic files to your project by using the Workshop Dialog boxes.
Now, click the Add button to display the Open dialog box, locate the RTF topic file you created in the previous section, and select it. Then, click the Open button, followed by the OK button to add this file to the project. Next, you need to tell the project where to find the bitmap that you added to the topic file. Click the Bitmaps button to display the Bitmaps dialog box and then locate the folder containing the bitmap and click OK. The project file now has enough information (see Figure 21.16) to compile your Topic file into a working Help file.
FIG. 21.16
The completed project file is displayed in the Help Workshop.
The workshop toolbar, shown in Figure 21.16, contains two buttons that you use to compile and then test your Help file. To compile your Help project, click the Compile button. The Compile to a Help File dialog box then appears (see Figure 21.17). This form lets you set the Help project file name to compile. In addition, you can minimize the workshop windows while the project is compiling and automatically have WinHelp display the Help file when the compile is complete.
FIG. 21.17
The Compile Help File dialog box prompts for the Project to compile.
If you do not want to watch the progress of the compile, you can minimize the window during the compile; however, when you create the Help project for the first time, it is useful to watch the process. If you did not select the option to have WinHelp automatically display the Help file when completed, you need to click the Run WinHelp button. This will display the View Help File dialog box (see Figure 21.18).
FIG. 21.18
The View Help File dialog box enables you to test the Help file by opening
it the same way the user would.
By using this dialog box, you can open your new Help file as a program opens it, as a user opens it by double-clicking its file icon, or as a pop-up by using a Mapped Topic ID to select a given topic. Select the option, A Double-Clicked File Icon, and click View Help. This displays the Table of Contents topic from the new Help file (see Figure 21.19).
FIG. 21.19
This is how the Finished Help file appears to users.
Mapping Topics in the Help File You may have noticed that the workshop fills in the names of the Help project and finished Help files for you in the appropriate boxes. When testing your new Help file, you will find that there are no Mapped Topic IDs because you have not added any to the project yet. First, close the Help file if it is still open, and then click the Map button on the workshop screen to display the Map dialog box. This form lists the Topic IDs that have been mapped and their related values. To add a new Topic ID to this list, click Add to display the Add dialog box (see Figure 21.20).
FIG. 21.20
Add Mapped Topic IDs by entering the Topic ID, a value you select, and an
optional comment.
Using numeric values to reference Help topics makes it easier to use the Help file when adding it to your Visual Basic application. The mapped numbers are used in the calls to WinHelp. On the Add dialog box, you can enter only three values: the Topic ID that was defined in the .rtf file, a numeric value, and an optional comment. To see how this option works, enter the Topic ID, Preamble, and the numeric value of 2. Then, if you want, enter a comment describing this topic. After you are finished, click OK to add this topic to the mapped list. Then click OK again to return to the main workshop window.
Your project file should now have a new section in it called MAP. Recompile the Help file and then click the Run WinHelp button. When the View Help File dialog box opens, you should have the new mapped topic ID listed in the Mapped Topic IDs drop-down box. Select the mapped value, select a Pop-up as the way to display the Help file, and then click View Help. The topic that you selected will display as a pop-up immediately (see Figure 21.21).
FIG. 21.21
Displaying Help information as a pop-up is done by simply asking for it that
way.
Well, now you have a working Help file; however, it doesn't look any different than the old non-Windows 95 Help files. The reason is that the new Help Topics dialog box is missing. The next section discusses how and why the Help Topic dialog box is used.
The easier it is for your users to find Help, the less frustrated they will be when they run into a problem in your application. A complete Help system increases user satisfaction when using the application. Users will be accessing the Help file from several different locations within your application and, in addition, will be able to display the Help file by double-clicking the icon for the Help file. In the Help file that you have created, notice that the Index button at the top of the Help dialog box is grayed out. This is because no keywords were defined in the Topic files. Adding keywords is discussed later in this chapter.
When the Help Topics dialog box displays, you can determine which of three default tabs appear. You can also determine the information that appears on two of those tabs. If you want a Contents tab to appear, you must provide a contents file with the Help file you created. If you want the Index tab to appear, you must define keywords in your topics. Finally, the Find tab always appears, unless you specify that you don't want it to display.
The items listed on the Contents tab are defined in the contents file that you create with the Help Workshop. The Contents tab is dynamic--you can add or remove items from the list independently of the Help file. This means that as your application in enhanced, you do not have to change the original Help file; you just add a second Help file to your application and include the topics in the contents file.
Creating a contents file is really easy with the Help Workshop. As you create the contents file, the Help Workshop displays each item with a book or page icon, depending on the position of the item. This allows you to see the finished list as you create it.
Creating the Contents File In the Help Workshop, choose File, New, select Help Contents from the new list, and then click OK. A new window displays in the Help Workshop (see Figure 21.22). You use this window to create the contents file. When the contents file is first created, you need to specify default information that WinHelp will use to locate the entries in the contents file, display the correct title at the top of the Help Topics dialog box, and display the Help information in the correct window type. To set this default information, click the Edit button located at the top-right of the window. This displays the Default Help Information dialog box. In the Default Help Filename box, enter the name of your Help file. Then, in the Default Window box, enter the window type you want to use to display the topics in your Help file. Finally, in the Default Title box, you can, optionally, enter the Title you want to display in the Help Topics dialog box (see Figure 21.23).
FIG. 21.22
The contents file creation window displays the finished Contents list as you
work.
CAUTION: The window type that you specify must be defined in your project file.
FIG. 21.23
The Default Help Infor-mation dialog box for the Help Topics helps WinHelp
display your Help file correctly.
Any of these default settings can be changed when entering the actual items in the contents list.
Before going any further, click Save in the File menu to save the contents file. The name that you give it does not have to be the same name as the Help file as long as you specify the contents file name in the project file. When adding items, remember that headings are identified by book icons that can be double-clicked to display the subheadings or topics that they contain. To add the first entry to the list, click either the Add Above or Add Below button; it doesn't matter. The Edit Contents Tab Entry dialog box will display (see Figure 21.24).
FIG. 21.24
Adding items to the Contents tab is done by using the Edit Contents Tab Entry
dialog box.
For every item that you enter in the Contents tab, you can specify:
This is where you can override the default settings for the contents file. For the first item, select the Heading option at the top of the form. Then enter American Documents as the Title and click OK. You should see a book icon appear with the title you entered next to it. Next, add the remaining topics and headings as listed in Table 21.4.
Entry Type | Title | Topic ID |
Topic | The Constitution | Constitution |
Topic | The Declaration of Independence | Declaration |
Heading | The American Flag | |
Topic | Explaining the American Flag | Flag |
After you add these entries, the Contents dialog box should look like the one shown in Figure 21.25.
FIG. 21.25
The finished Contents tab list is shown in the Help Workshop.
After saving the changes to the contents file, you can test it. One neat thing about the contents file is that if the name of the file is the same as the name of the Help file, you do not have to recompile the Help file to test it. If you have named it differently, you must specify the contents file name on the File tab of the Options dialog box in the Help Workshop for your project. To test the contents file, click the Run WinHelp button, select the Invoked by a Program option, and click View Help. This displays the Help Topics dialog box, shown in Figure 21.26.
FIG. 21.26
This is the Finished Help Topics dialog box as the user sees it.
Try clicking the book icons and then the item icons to see what happens.
Adding Keywords to the Index Tab The Index tab appears only if you have K footnotes and keywords defined in your topic files. Then, by double-clicking a keyword that is displayed in the Index tab, the user can display the related topic. In the topic files, you add a K footnote to the topics that you want to add keywords to. For each K footnote, you can define as many keywords as you need for the topic page. If you assign the same keyword to more than one topic, the keyword appears only once in the index. However, when the user double-clicks that keyword, the Topics Found dialog box displays (see Figure 21.27).
FIG. 21.27
If more than one Topic is defined for a keyword, the Topics Found dialog displays
to select the correct topic from.
Add some keywords to the demo Help file by using the techniques and syntax described earlier in this chapter. Remember that the K footnote must be an uppercase K and each keyword(s) is separated by a semicolon (;). Unlike the Contents tab, you must recompile the Help file for the keywords to be included on the Help Topics dialog box. After recompiling, test your Help file again to see how the Index tab works.
Indexes sometimes can contain several levels of entries, just like the Contents tab. Second-level entries are indented under first-level entries and they list specific information within that category. You can create the same effect in your Help Index by defining first- and second-level keywords. The Windows 95 Help Index is a good example of this technique (see Figure 21.28).
FIG. 21.28
The Windows 95 Help Index uses second-level index listing to group related
keywords together.
Creating first- and second-level keywords requires only a slight change in how you define the keywords in the footnote. To add a first-level keyword to your Help file, add a K footnote and then type the first-level keyword, followed by a comma (,) and a semicolon (;), as shown here:
K Constitution,;
Don't worry; neither the comma nor the semicolon appear in the Index text. Next, immediately following the semicolon, type the first-level keyword again, followed by a comma, a space, the second-level keyword, and another semicolon, as shown here:
K Constitution,;Constitution, The Constitution of the United States;
CAUTION: If you use the same first-level keyword in multiple topics, you must specify it identically in each of those topics.
Add a few first- and second-level keywords to your Help file, recompile it, and see what it looks like.
Using the Find Tab The Find tab enables the user to perform a full-text search through every word in a Help file. As an example, if the user enters the word open on the Find tab in the Windows 95 Help Topics dialog box, every topic that contains the word open is listed. When a user clicks the Find tab for the first time, the Find Setup Wizard displays. The Wizard will assist the user to set up the full-text search index. Users will have to do this only once, unless they deleted the index file (.fts) that contains the index information.
CAUTION: The only topics included in the Find tab search are the ones that have Titles defined as $ footnotes.
If you want a full-text search index to be available to your users immediately, you can have it created when you create the Help file by specifying it on the FTS tab of the Options button. You then will need to include this new file .fts, along with the contents file .cnt and the Help file .hlp, when you create the distribution disks for your application.
The Difference Between the Index Tab and the Find Tab The Index tab contains the keywords that you define in the Help file. They can be terms for beginners or terms for advanced users. The keywords can be synonyms for terms used in the topic or words that describe the topic. The index provides the user with many different ways of getting to the information. The more ways you provide the user, the easier it will be for them to find what they are looking for. The Find tab lists only words that appear within the Help topics. To find a topic, the user must use a word exactly as it appears in the text. By using the Find tab, the user can easily list every topic that contains a specific word.
TIP: The Find Tab can be very useful to you as the developer. If the name of a program element changes, you can use the Find tab to locate each occurrence of it in your Help file.
You now have a Windows 95 Help system that contains the new Help Topics dialog box and makes use of the full-text search capabilities of WinHelp. In the next section, you will see how to add a few more advanced features to your Help file.
Although many additional features can be added to the Help file, this section focuses on a few common ones to give you a solid introduction to enhancing your Help file. The following list includes features that you can add to your Help file:
In this section, you add to your new Help file several single-line topics that are used as context-sensitive help descriptions. You also change the style of the Help window and its appearance. Finally, you see how to add a macro to the Help project to enhance the way the Help file can be used.
If you have been using Windows for any length of time, you are already familiar with the concept of context-sensitive help. Accessing context-sensitive help is as easy as selecting an object in a Windows application and pressing the F1 key. Of course, the application must be designed to make use of this feature. You will see how to do this in the next section of this chapter.
Besides the F1 key, the user has several other ways to access context-sensitive help in an application. These other options are the following:
All these methods make use of context references that you must set in the Help project file. To create context-sensitive help, you first create the topics in the topic files and then, in the project file, map each Topic ID to a specific numeric value. Next, in the program code, each of these values are used to display the correct Help topic when the user accesses Help for a specific object. For example, if the user clicks the question mark button and then clicks an item in a dialog box, the program sends the value for that topic to WinHelp, which then displays the topic whose Topic ID is mapped to that value.
The actual process of creating the context-sensitive help topics is the same as any other topic in the Help file. You need to create new topic pages to be used by the application program. The second part of the process is to establish a set of context references so that WinHelp and your application can exchange the correct information between them. In Visual Basic applications, the context reference is a unique number that is placed in the HelpContextID property, which relates to a particular object. You can assign any number to a context ID; however, each context ID must be unique.
The process of relating the context IDs to the related Topic IDs by using the Help Workshop was covered earlier in this chapter. This is accomplished by using the Map dialog box, which lets you assign the unique values.
In your topic file, enter two to three single-line topics and then set the # footnote to an appropriate Topic ID. Don't worry about the content of the text; it doesn't really matter at the moment. If you want, you can use a variation of the following text:
This is the context-sensitive help for topic 1
After you finish entering the topics and setting the # footnote, the Help Workshop is used to assign each Topic ID in the Help file to values 1 through 8 by using the techniques you learned previously in this chapter. Do not recompile the Help file yet. Because these context IDs are used by the Visual Basic program, you would not yet see any difference in your Help file.
You can use two types of windows in your Help files: main and secondary. The main window has a menu bar and a button bar and cannot be sized automatically. There is only one of this type of window in a Help file. The menu bar in the main window provides the Display History option, which allows the user to display a list of topics that have been looked at during this session. The Bookmark menu is the other option that enables the user to mark a topic to return to later.
A secondary window does not have a menu bar, so these features are not available. However, the secondary window can include a button bar and can be sized automatically. There can be up to 255 secondary windows defined in a Help file, with up to 9 displayed at any one time. To see how this works, you need to define a main window and a secondary window to your Help project. You do this by using the Windows button in the Help Workshop. When you click this button, the Windows Properties dialog box displays (see Figure 21.29). This dialog box enables you to define new windows to your project, as well as customize the position, color, buttons, and macros that appear in the window. You can also set the default title that is used at the top of each window.
FIG. 21.29
Add windows in the Help Workshop by using the Windows Properties dialog box.
To create a secondary window, all you need to do is name it. You can then use this name in your project, contents, and topic files to specify in which window you want the topic displayed.
NOTE: The steps for customizing the main window are the same as customizing a secondary window.
On the Help Properties dialog box, click the Add button to display the Add a New Window Type dialog box. To create a main window, use Main as the new window name. Otherwise, enter the name that you want to use, which can include up to eight characters. Then, as a starting point, select one of the three standard window types that are listed in the drop-down box. These are the window types that are used in Windows 95 Help. Think of these as templates to get you started, and then you can modify them to fit your needs for each new window you define. The three standard types are as follows:
Type | Description |
Procedure | This window type normally is used to display procedures. It has auto-sizing, contains three buttons on the button bar, and is positioned in the upper-right corner of the screen. |
Reference | This window type normally is used to display reference material. It has auto-sizing, contains three buttons on the button bar, and is positioned on the left side of the screen, taking up approximately two thirds of the width of the screen. |
Error message | This window type normally is used to display error messages. It has auto-sizing, contains no buttons, and lets WinHelp determine the position (the upper-right corner of the screen is the default, unless the user changes the position). |
Select one of these types and click OK. Now, you have a new window defined and have to change a reference in a topic to use this new window. In the Topic with the ID of "Declaration," change the hyperlink jump tag to the following:
DeclarationMain>window2
where window2 is the name of the secondary window that you just defined. Recompile the Help project and open the Help file. Navigate to the Declaration of Independence topic and then click the Declaration Jump phrase. You see that rather than change the content of the main window, a new secondary window is displayed (see Figure 21.30).
FIG. 21.30
Secondary windows enable you to give the user information in a separate controllable
window.
Help macros enable you to add more functionality to your Help system, which can be used to customize the way WinHelp works with your Help files. You can use more than 50 available macros.
TIP: For more information about Help macros, search for "Macro Quick Reference" in the Help index for the Help Workshop.
Help macros are routines built into the WinHelp program that give you the capability to add and remove custom buttons and menus, change the functions for buttons and menu items, and execute applications from within Help. In this demo, you will see how to add a macro that will execute Notepad so that users can take notes about what they are reading in the Help file.
The macro that you will use is the ExecProgram macro. This macro launches a Windows-based application from within your custom Help system. The syntax of this macro is as follows:
ExecProgram("CommandLine", DisplayState)
The "Commandline" is the command line for the application that you want to execute. This command must appear in quotes. WinHelp searches for this application in the following paths:
The DisplayState parameter is a value that indicates how the application is to display when it is executed. The values of this parameter are:
Value | Description |
0 | Normal window |
1 | Minimized window |
2 | Maximized window |
To add this macro as a button on each of the windows that you have defined, you need to use a second macro called CreateButton. The CreateButton macro is used to define a new button and to display it in your Help system's button bar. The syntax of this macro is as follows:
CreateButton(ButtonId, Caption, Macro)
The ButtonId is a name that WinHelp uses to identify the button. This is a string and must be enclosed in quotes. This is also the value that you use in a DisableButton or DestroyButton macro to remove or disable the button.
The second parameter, Caption, is the text that appears to the user on the Button. To give the user Alt Key access, place an ampersand (&) before the correct letter in the string.
The last parameter, Macro, is the macro string that you want to execute when this button is clicked. This information must also be enclosed in quotes. The final macro that you add to your Help windows is:
CreateButton("Take_Note", "&Take Notes", "ExecProgram(`notepad.exe', 0)")
Single quotes in the ExecProgram macro distinguish between the quotes for the CreateButton and the ExecProgram strings. Add the above macro to the macro tab of each window that is defined in your Help project.
To complete the process, recompile the Help file and then open it. You should see a new button on the button bar (see Figure 21.31). When you click this button, Windows Notepad should open.
FIG. 21.31
The demo Help system shows a new button that opens the Notepad application.
In this section, you will learn how to access the Help system from within a Visual Basic application. There are several different methods for accessing the WinHelp system in Visual Basic. To learn how to use these methods, you will create a small Visual Basic application and add the different functions to the program. In this application, you will include a single form that will have several objects on it.
On this one form, you will add the different control objects and the program code to execute the various commands needed to display different topics from your Help file. From within Visual Basic, there are only three unique methods of calling Help. These methods are the following:
The CommonDialog control provides a standard set of dialog boxes for operations such as opening and saving files. For the purposes of this chapter, the important function of the common dialog is the capability to display Help by running WinHelp.
See "Using Controls," Chapter 4
To see how to use the CommonDialog control, start Visual Basic and create a new project. Add the controls shown in Table 21.5 to the default form and set their properties as shown.
Control | Property | Value |
CommandButton | Name Caption | cmdClose Close |
CommandButton | Name Caption | cmdHelp Help |
CommonDialog | Name HelpFile | CommonDlg <path/filename> |
TROUBLESHOOTING: I cannot find the CommonDialog control in the Toolbox. Why? If the CommonDialog control is not shown in your Toolbox, you need to add it by using the Components manager in the Project menu.
The common dialog properties can be changed by using its Properties Pages, as shown in Figure 21.32.
FIG. 21.32
Right-click the CommonDialog control to open its Property Pages and change
the control's properties.
When you place the CommonDialog on the form, it is displayed only as an icon. Only when you access this control in you running application will the control be displayed. Once you have added these controls, the next step is to add the code to execute when the command buttons are clicked. Copy the code in Listing 21.6 into the general area of the form's code area.
Const HelpFinder = &h00B Private Sub cmdClose_Click() End End Sub Private Sub cmdHelp_Click() CommonDlg.HelpCommand = HelpFinder CommonDlg.ShowHelp End Sub
The preceding code calls the Help system and displays the Help topics dialog box.
NOTE: Applications that have used the HELP_CONTENTS and HELP_INDEX commands to display the Contents topic and keyword index of the Help file will no longer work properly. These commands are no longer recommended. Instead, the HELP_FINDER command should be used.
CAUTION: Visual Basic 5.0 does not provide a CommonDialog control constant for the HELP_FINDER command. To access the Contents topic in a Help file, declare the WinHelp command as a constant in your application's general area as follows:
Const HelpFinder = &h00B
Execute your application and then click the Help command button to see your Help file. The same coding logic can be used to display specific topics by simply adding one line of code to the button's Click event and then changing the command. In the cmdHelp_Click event, change the variable from Help_Finder to cdlHelpContext. Then add the following line of code to specify the topic you want to display:
CommandDlg.HelpContext = 3
This line of code accesses the mapped value that you defined in the Help file project. Now, when you execute the program and click the Help button, the specified topic is displayed.
Every Windows 95 application has a well-defined Help menu (see Figure 21.33).
By using the CommonDialog control, you can add the same functionality to your application. The CommonDialog can perform many different actions by using WinHelp. The commands available are contained in the Visual Basic constants listed in Table 21.6.
FIG. 21.33
Standard windows Help Menu.
Constant | Value | Description |
cdlHelpCommand | &H102& | Executes a Help macro. |
cdlHelpContents | &H3& | Displays the Help contents topic as defined by the Contents option in the [OPTION] section of the project file. |
cdlHelpContext | &H1& | Displays Help for a particular context. When using this setting, you must also specify a context by using the HelpContext property. |
cdlHelpContextPopup | &H8& | Displays the Help topic identified by a context number defined in the [MAP] section of the project file in a pop-up window. |
cdlHelpForceFile | &H9& | Ensures WinHelp displays the correct Help file. |
cdlHelpHelpOnHelp | &H4& | Displays Help for using the Help application itself. |
cdlHelpIndex | &H3& | Displays the index of the specified Help file. |
cdlHelpKey | &H101& | Displays Help for a particular keyword. When using this setting, you must also specify a keyword by using the HelpKey property. |
cdlHelpPartialKey | &H105& | Displays the topic found in the keyword list that matches the keyword passed if there is an exact match. If more than one match exists, the Search dialog box with the topics found listed in the Go To list box is displayed. If no match exists, the Search dialog box is displayed. To bring up the Search dialog box without passing a keyword, use an empty string. |
cdlHelpQuit | &H2& | Notifies the Help application that the specified Help file is no longer in use. |
cdlHelpSetContents | &H5& | Determines which contents topic is displayed when a user presses the F1 key. |
cdlHelpSetIndex | &H5& | Sets the context specified by the HelpContext property as the current index for the Help file specified by the HelpFile property. |
The next step in the process is to add the menu items shown in Figure 21.34. Then add the code in Listing 21.7 to your application.
FIG. 21.34
The Demo application's Help Menu shown in the Menu Editor.
Private Sub mnuContents_Click() CommonDlg.HelpCommand = cdlHelpContents CommonDlg.ShowHelp End Sub Private Sub mnuDemo_Click() CommonDlg.HelpCommand = HelpFinder CommonDlg.ShowHelp End Sub
You will see that the code calls the different functions of the Help system simply by using the different commands available.
See "Controlling a Program with a Menu Bar," Chapter 5
Another method of calling WinHelp directly is by using the Windows API interface. To display Help when the Help button is clicked without using the CommonDialog control, you need to declare the Help API function and then call that function, passing the appropriate parameters as shown here:
Declare Function WinHelp& Lib "user32" Alias "WinHelpA" _ (ByVal hWnd As Long, ByVal lpHelpFile As String, ByVal wCommand As Long, ByVal dwData As Long)
When you want to call the Help file, you would execute the following code:
Dim temp As Integer temp = WinHelp(FLMAIN40.hWnd, HelpFile, cdlHelpIndex, _ ByVal helpkey)
Although this is more efficient, you can see that the common dialog is easier to use.
After using the common dialog, context-sensitive help will be easy to implement. To see how it works, add a text box to your form and name it txtInput. Each object that you place on a form has two properties that enable you to set up context-sensitive help. These properties are:
Property | Description |
HelpContextID | When the user presses the F1 key, Visual Basic automatically calls Help and searches for the topic identified by the value in this property. |
WhatsThisHelpID | When the user clicks the WhatsThis button and then clicks an object, the value in this property is used to display a Help topic. |
If the WhatsThis button is active, the F1 key will not work. To use this function, set the WhatsThisHelpID to a topic value from your Help file. Then, the only other thing you need to do is set both the WhatsThisButton and WhatsThisHelp properties of the form to True. The WhatsThisHelp property determines whether context-sensitive help uses the What's This pop-up provided by the Windows 95 Help system. This property must be used with the WhatsThisButton property. This property determines whether the What's This button will appear in the title bar of the form.
NOTE: The WhatsThisHelp property must be True for the WhatsThisButton property to be True. For these buttons to be shown on the form, the following properties must also be set as shown:ControlBox property = True
BorderStyle property = Fixed Single or Sizable
MinButton and MaxButton = False
or
BorderStyle property = Fixed Dialog
Set these properties to True and set the forms border style to Fixed Dialog. Now, when you run your application, you will see a new button with a question mark in it at the top right of the title bar (see Figure 21.35). When you click this button, the mouse pointer will change. When you click an object that has the WhatsThisHelpID set, the specified Help topic appears.
FIG. 21.35
The main application form shows how to use the What's This Help button.
Whenever a message box is displayed, it is a good idea to give the user some way of displaying the Help topic associated with the message. It is really quite simple to add a Help button to a message box. The message box syntax, shown next, has parameters that enable you to pass the Help file information to it:
MsgBox(prompt[, buttons][, title][, helpfile, context])
The button's value determines which buttons and icons are displayed on the message box. Add the constant vbMsgBoxHelpButton to the other constants in the buttons parameter. Then, you need to set the helpfile and context values. The following code will display a message box that displays the Help button, which, when clicked, displays the Help topic that is mapped to the context ID of 4:
MsgBox "this is a help demo", vbCritical + vbMsgBoxHelpButton, _ "Demo", "c:\temp\usdemo.hlp", 3
Add a new command button to your form and place the preceding line of code in its Click event routine. Run your application and then click the command button you just added. The message box that is displayed has a Help button on it (see Figure 21.36). Clicking this Help button displays the topic specified by the context Id.
FIG. 21.36
The message box, which shows a Help button on it.
In this chapter, you learned to create a Help file to compliment your Visual Basic application. In addition, you used the Help Workshop to aid in the building of the project and contents files, as well as the compile and testing process for the Help file. Finally, you saw how to connect the Help file to your Visual Basic applications by using properties and methods of several different controls and features included with Visual Basic 5. For more information related to this chapter, see the following:
© Copyright, Macmillan Computer Publishing. All rights reserved.