Special Edition Using Visual FoxPro 6
You can use Microsoft's HTML Help Workshop to create really slick online help for your applications. The HTML Help Workshop is new as of Visual FoxPro 6 and replaces the very capable but more mundane Help Workshop 4.0. Each help page can resemble a Web page, complete with graphics, colors, and fancy formatting. You can easily link to other help pages, and even to Web sites. Your help system can have a much more polished look than you could easily achieve with Workshop 4.0. And, as an increasing number of applications migrate to the HTML Help Workshop, older help systems will begin to look dated.
If you have legacy applications, the Workshop includes a converter to transform earlier help files to the new standard. For brand-new applications, the Workshop includes a complete help authoring tool as well as an online tool for creating and editing images to make it easier to create attractive graphical help files.
The HTML Help Workshop provides you with all the tools you need to create help files that have some, or even all, of the following features:
The HTML Help Workshop is included with Visual Studio 6 and with Visual FoxPro 6. But, be sure to check for the very latest version at http://www.microsoft.com/workshop/author/htmlhelp.
Be sure to read the Readme file that comes with the HTML Help Workshop. There are still a few problems with Version 1.1 and these are thoroughly explained in the Readme. You can also find this information in the Workshop's Help Index under New Features.
The Microsoft HTML Help Workshop is a separate program from Visual FoxPro 6. It uses components of Microsoft Internet Explorer (IE) to display help content. You use the HTML Help Workshop to develop graphical help pages and menus to support the users of applications that you develop. After you develop your help pages and menus, use the Workshop to compile the elements that you've created into a Help file. The compiled help file has the file extension .CHM. The FoxPro command
SET HELP TO FILENAME.CHM
links your application to the help file that you've developed.
FoxPro with the HTML Help Workshop provides four ways to deliver help to the users of your applications:
These methods are described in the following sections.
You should have an item on the main menu bar of your application to give users access to your help system. By clicking this item, you should get an Index/Contents/Search screen like that shown in Figure 26.1, which contains Contents/Index/Search information that is pertinent to your application.
One technique for delivering context-sensitive help is to put a Help command button on the form. This lets the user acquire help that is pertinent to the current form. Individual objects on the form can be described as subtopics on the help page. An example of this level of context-sensitive help is shown in Figure 26.2.
| NOTE |
Notice that the complete help system pops up, but with the context-sensitive help page already displayed. This makes it possible for the user to quickly move to another help topic in case the context-sensitive help that is displayed turns out to be incorrect or insufficient for her current needs. |
Context-sensitive help with greater granularity is provided by linking the F1 key to a help page. This is the kind of help that pops up when an object that has an associated help topic has focus and the user presses the F1 key. This lets you have individual help pages for each object on a form that requires help. Among the objects that can have context-sensitive help tied to the F1 key are the following:
| CheckBox | ComboBox |
| CommandButton | CommandGroup |
| EditBox | Form |
| Grid | Image |
| Label | Line |
| ListBox | OLE Bound Control |
| OLE Container Control | OptionButton |
| OptionGroup | Page |
| SCREEN | Server Object |
| Shape | Spinner |
| TextBox | ToolBar |
What's This? help is also context-sensitive help that a user can request about a particular object. This is similar to the What's This? help that was introduced with Windows 95. When a form has What's This? help, a question mark is displayed just to the left of the form's Close button. To activate the context-sensitive help for a screen object, the user clicks on the question mark. The cursor changes shape to indicate that it is ready. Subsequently clicking on any object that has an associated help topic produces a display similar to what you saw in Figure 26.2. A form designed to use What's This? help is shown in Figure 26.3.
It is not at all difficult to use the HTML Help Workshop to create custom help files for your FoxPro applications. The following sections step you through the basics of the Workshop. You'll find that the addition of HTML help to your applications will give the applications a more polished, professional appearance.
Your first step in using the HTML Help Workshop is to install it on your computer. The Workshop is not part of the standard FoxPro installation, so you'll need to install it separately. You'll find it on your Visual Studio CD #1 as a compressed executable named HTMLHELP.EXE. If, for some reason, you can't locate it on the CD, you can find it at http://www.microsoft.com/workshop/author/htmlhelp.
All you need to do to install the HTML Help Workshop is to double-click on HTMLHELP.EXE and follow the resulting wizard's instructions.
The first step in developing your help system is to bring up the HTML Help Workshop and choose File, New. This activates a wizard that collects the necessary information to create new elements of your help system, and brings you to the screen shown in Figure 26.4.
Figure 26.4 : This is the Help Workshop screen for creating new project elements.
The help system essentially consists of a number of HTML files that provide the help information associated with an item in the table of contents, the index, or context-sensitive help. The help project is the wrapper that puts all of these elements together. Start by selecting Project from the New Items menu. This selection starts a wizard that collects the information for a new help project.
| TIP |
The Project Wizard is the vehicle for converting an existing WinHelp project to the new HTML help. It will convert .RTF files to HTML, convert the .CNT file to an .HHC file (a new table of contents), and transform the WinHelp project file into an HTML Help project file (.HHP). |
The Project Wizard also determines the location of your new help project. It seems reasonable to place the project in the Help folder of your FoxPro project. FoxPro 6 automatically creates a Help folder for each new FoxPro project.
If you have already created a table of contents, an index, or HTML topic files, you can choose to have the Project Wizard incorporate these existing elements into the new project with the help of the Existing Files screen shown in Figure 26.5.
When you're finished with the Help Wizard, you have a new, empty project and your Help Workshop screen will look something like Figure 26.6.
Figure 26.6 : Here's a screen for a new HTML Workshop project.
Notice that the Project window has four tabs: Project, Contents, Index, and Help.
| CAUTION |
Be cautious with the Help tab, because it can lock up the Workshop. In fact, you should be cautious about clicking on any Help tab except the one on the main menu. |
Down the side of the window, you'll find seven speed buttons.
The Project's table of contents is similar to that found in the help system of every Windows program, except that it contains only those items that you put there. It can contain as little or as much as you think necessary for your particular FoxPro project. To add a table of contents to your new project, either click on File, New and select Table of Contents from the menu (refer to Figure 26.4), or click on the Project's Contents tab (refer to Figure 26.6). You'll need to supply a name for the new contents file, and you can use whatever name you like, but stick with the file extension .HHC. A table of contents page in process will look like that shown in Figure 26.7.
Figure 26.7 : Table of Contents under development.
Notice that there are eleven speed buttons down the left side of the Contents window.
Inserting a heading adds a line that begins with an icon. The choice of icons (book or folder) is set by a check box in the Contents Properties form. The heading doesn't need to be associated with an HTML file or with a URL, although it can be. If you don't explicitly specify a link to the heading, the Workshop will automatically link the heading to the project's default topic. The default topic must be specified using the Add/Remove topic files button on the Project tab. If you forget to specify this default, the program will generate a runtime error when it is launched.
Inserting a page adds a line that begins with the icon that looks like a page. Page lines are normally offset from the left edge of the window. When you insert a page, as shown in Figure 26.7, you provide the Workshop with the Page title and then specify a help file or a Web URL. The file or URL that you specify doesn't have to exist at this time. However, if the file/URL doesn't exist when you run the compiled Help file, you'll get a cosmetic error when you click on the page title. The file can be either a text file or an HTML file.
The project's index is also similar to that found in the help system of every Windows program, except that you must define the items for the index. As with the table of contents, the index can contain as little or as much as you think necessary for your particular FoxPro project. To add an index to your new project, either choose File, New and select Index from the menu (refer to Figure 26.4), or click on the Project's Index tab (refer to Figure 26.6). You'll need to supply a name for the new index file; you can use whatever name you like, but stick with the file extension .HHK. An index page in progress will look like that shown in Figure 26.8.
Figure 26.8 : This is how an index under development looks.
There are eleven speed buttons down the left side of the Index window:
Inserting a keyword adds a line in the Index window. The keyword itself is the text that appears in the Index window, but you also need to supply the file or URL that is to be linked to the keyword. You can also supply an optional title with each file/URL that is linked to the keyword. This optional title is used when you have multiple links for a particular keyword, as is shown in Figure 26.8 and the application (see Figure 26.9). As with the table of contents, the system won't complain if the linked file/URL doesn't exist. It will produce a cosmetic error when you run the compiled Help program, however.
Figure 26.9 : This illustrates a keyword with multiple linkages.
You need to create one HTML file for every help page that can be displayed for items in the table of contents, keywords in the index, and as context-sensitive help. To add HTML files, choose File, New and select HTML from the list of options. The HTML Help Workshop has a simple text editor that you can use to edit the files created with this option. However, you'll be better served to create and edit these files using a good HTML editor for your HTML files. When the Workshop creates a new HTML file, it provides some of the HTML structure as shown in Figure 26.10.
Figure 26.10: This is a basic HTML file created by the HTML Help Workshop.
Another option that you shouldn't overlook is to use the Save As HTML feature in Microsoft Word. That way, you can use MS Word to develop all the HTML topic files that you need. In addition, there are quite a number of free-or almost free-design tools that you can make good use of in your page design. Finally, there are several commercial authoring tools that work with the HTML Help Workshop to produce stunning output with far less work on your part.
If you're going to need a substantial number of HTML topic files, you might consider putting these files into an HTML subdirectory of your Help folder. This will keep them separated from the other files used by your help project.
Links to Topic Files and URLs You can create links between HTML topic files and between a topic file and URLs on the World Wide Web. To create a link between one HTML file and another, use the following syntax:
<a href="relative pathname">topic string </a>
where relative pathname is the name of the file that you want to link to, and topic string is the character sequence that will be displayed and underlined. For example:
<a href="html\payables.htm">See Also </a>
To create a link to a URL on the World Wide Web, use an HTML statement like the following:
<a href="http://www.microsoft.com">See Web Site</a>
Adding and Removing Topic Files After you create an HTML topic file, you must add it to the project. This is accomplished with the Add/Remove topic files speed button on the Project tab, which produces a screen similar to that shown in Figure 26.11.
Figure 26.11: This screen is used for adding and removing HTML topic files.
This is the list of HTML files that will be compiled into the project. Clicking on the Remove button will remove the reference to the selected file. It does not delete the file from the disk. Click on Add to bring up the Open dialog and select one or more of the displayed files to be added to the project, as shown in Figure 26.12. Click on Open to add the selected files.
Figure 26.12: Use the Open dialog box to add HTML topic files.
You should have a default topic file that says something to the effect of No matching topic was found. Be sure to add this default file to the list of topic files. You must also identify this file as the official default file. Click on Change Project Options to access the screen shown in Figure 26.13. Fill in the name of the default HTML Topic File and click OK.
Figure 26.13: Use this dialog box to specify the default HTML topic file.
At this point in the process, you have everything you need to provide the basic system level help when the user clicks on the Help selection of your application's main menu. To get the optional working model, select File, Compile. If you've done everything correctly, you will have a compiled help file that has the file extension .CHM. To connect this help file to your Visual FoxPro application, add this statement:
SET HELP TO filename.CHM
The next step in developing your help system is to add context-specific help. The first step is to add an optional Help command button to a form as seen in Figure 26.14. This button provides context-sensitive help at the form level, and the F1 function key will provide the same help.
Figure 26.14: Here's the setup for a Help command button on a form in Visual FoxPro 6.
Next, complete these steps:
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
This.SetAll("HelpContextID",11)
Help ID This.HelpContextID
At this point, you've set up the Visual FoxPro end. Now you need to tell your help project how to handle this Help event.
Using the MAP File as a Connecting Link You need to create a new file that's going to provide the connecting link between your FoxPro application and the HTML help project. This link comes from the MAP file. You can call this file HelpDemo.h. The filename doesn't matter, but the extension must be .h. This is just a standard C header file. Add the following line to the MAP file:
#define IDH_DateButton 11 //this is the date help button
IDH_DateButton is the symbolic name for HelpContextID 11. You'll need additional lines like this in your MAP file, one for each HelpContextID in your Visual FoxPro application. You can add additional lines at any time, as long as you recompile the help project after each new set of lines.
Adding the Map to the Help Project In the HTML Help Workshop, click on the Project tab and then click on the HtmlHelp API information button. This will give you the screen shown in Figure 26.15. Use the Header File button to add the Map file to the project.
Figure 26.15: Use this dialog box to add map information to the help project.
Linking the HelpContextID to an HTML Topic File Your next step is to tell the project which HTML topic file is to be used for this HelpContextID. This is accomplished with the Alias tab in the HtmlHelp API Information dialog. Click on the HtmlHelp API information button to access a list of existing aliases. Click on the Add button to move to the dialog box shown in Figure 26.16.
Figure 26.16: Use this dialog box to add alias information to the help project.
In the top line of the Alias dialog, enter the symbolic name that you assigned the HelpContextID. On the second line, enter the name of the HTML topic file that you want this HelpContextID to call. The Comment line is just for your future reference; it doesn't get compiled into the .CHM file.
You can now compile your help project. It will produce context-sensitive help in your FoxPro application. The specified HTML topic file will be displayed when users click on the Help button or press the F1 key.
What's This? help was first introduced with Windows 95. This is the help that's available when you a see a question mark displayed just to the left of a form's Close button. What's This? help is activated by clicking on the question mark and then clicking on the form itself, on a control, or on a toolbar. What's This? help is not available when a form has either Minimize or Maximize buttons on the form's title bar.
To have your form use What's This? help, you need to set certain properties of the form as follows:
A Visual FoxPro 6 form that has been set up to make use of What's This? help is shown in Figure 26.17.
Figure 26.17: This Visual FoxPro 6 form has been set up to use What's This? help.
Setting up the Header File Add lines like those shown below to your project's MAP file (this is the C header file that was introduced in the discussion on context-sensitive help):
#define HIDH_DateForm 211 //this is the date form #define HIDH_DateField 212 // this is the date field
| TIP |
If your project doesn't yet have a MAP file, see the section "Using the MAP File as a Connecting Link" earlier in this chapter. |
Incidentally, you can have multiple header files to map names to HelpContextID and WhatsThisHelpID values. You might find it more convenient to manage the assignment of unique names and numbers by using multiple header files, particularly if you have a large number of help topics. However, don't use the same value for a HelpContextID and a WhatsThisHelpID, even if the duplicates will be in different header files.
Setting the Aliases Your next step is to tell the project which HTML topic file is to be used for this WhatsThisHelpID. This is accomplished with the Alias tab in the HtmlHelp API Information dialog box just as it was with context-sensitive help. Click on the HtmlHelp API information button to access a list of existing aliases. Click on the Add button to move to the dialog you saw in Figure 26.16.
In the top line of this dialog, enter the symbolic name that you assigned the WhatsThisHelpID. On the second line, enter the name of the HTML topic file that you want this value to call. The Comment line is just for your future reference; it doesn't get compiled into the .CHM file.
You can now compile your help project. It produces What's This? help in your Visual FoxPro application. The specified HTML topic file is displayed whenever users click on the question mark and then click on a control or field that has an associated WhatsThisHelpID.
You can distribute your compiled help system along with your FoxPro application. The HTML Help Workshop includes a setup program named HHUPD.EXE that you can redistribute. This program installs and registers the HTML help runtime components. Internet Explorer must be installed on the user's machine. And, don't forget to include your compiled help file.
The following components are installed by the setup program:
| Component Name | Description |
| Hhctrl.ocx | HTML help ActiveX control |
| Itss.dll | Dynamic link library for compiled HTML |
| Itircl.dll | Full-text search dynamic link library |
| Hh.exe | HTML help viewer |
The setup program can be called from other setup programs and will run in the quiet mode so that it doesn't interfere with existing setup programs. To obtain a list of the program's command line options, run HHUPD.EXE/?.
© Copyright, Sams Publishing. All rights reserved.
){kind=link}
){kind=link}
){kind=link}