You can add professional polish to your application by adding a graphical Help file in the form of HTML or WinHelp Help. Graphical Help can include graphics and formatted text; .dbf-style Help is limited to a single font without graphics. For information about creating .DBF-style Help, see Chapter 24, Creating .DBF-Style Help.
Note Microsoft Visual Studio 6.0 includes Microsoft HTML Help Workshop (Hhw.exe) for creating HTML Help files. It does not include Microsoft Help Workshop 4.0 (Hcw.exe) for creating Winhelp files. Previous versions of Microsoft Visual FoxPro include Microsoft Help Workshop 4.0.
This chapter discusses:
HTML Help provides many of the features of Winhelp, and adds the following features:
HTML Help is created with Microsoft HTML Help Workshop, which is included with Visual Studio and stand-alone Visual FoxPro. HTML Help Workshop provides a complete authoring system for HTML Help, and includes backwards compatibility that allows you to easily create HTML Help files from existing Winhelp projects. To create HTML Help files for your application, consult the online Help for the HTML Help Workshop.
A sample HTML Help project, part of the Solutions sample, is included in \Samples\Vfp98\Solution\Help. It includes the following files:
| File | Description |
| Solution.chm | Compiled Help file. |
| Solution.hhp | Project file - a text file that brings together all the elements of a help project and contains information about how a compiled help file will appear. |
| Solution.hhk | Index file - contains the index entries (keywords) for your index. |
| Solution.hhc | Table of Contents file. |
| Solution.ali | Alias file for context-sensitive Help support. Maps product Ids to Help topics. |
| Solution.hh | Header file for context-sensitive Help support. Includes product Ids. |
| Solution.chi | Index file used when you ship .chm files that are likely to remain on a CD-ROM, as in the case of the MSDN Library. The .chi file allows certain navigation information to be installed locally on a hard disk for quick access, while the main content lives on the CD-ROM. A .chi file should not be used in a non-CD-ROM scenario. When a .chi file is not used all the information that would be in it remains in the .chm itself. |
| MSDN_ie3.css | Cascading style sheet. |
| MSDN_ie4.css | Cascading style sheet. |
| FileName.htm | Source content files. |
| FileName.gif | Source graphics files. |
In addition to creating an HTML Help file that contains useful information, you need to provide a means for users of your application to access Help. There are three ways to deliver Help:
Implementing HTML Help is similar to implementing WinHelp. The following sections describe how you can implement HTML Help for your application.
A Help menu typically contains commands that provide access to the topics in your Help system. It is strongly recommended to have a single command on your Help menu that opens your HTML Help system. Beyond that, you can place additional commands on the Help menu that provide system information, or copyright and version information about your application.
Context-sensitive Help allows users to easily access Help topics relating to what they are doing or seeing in your application at any given time. For example, if a user is viewing a data entry form, context-sensitive Help could provide a topic relating specifically to that data entry form.
You decide the level of detail at which context-sensitive Help is implemented in your application. For example, you can associate a context-sensitive Help topic with a form, or you can associate more detailed Help topics with each control and field on your form.
Context-sensitive Help is typically accessed by pressing F1, but you can specify any key to activate context-sensitive Help with ON KEY LABEL.
Using Context-Sensitive Help on a Form
To implement context-sensitive Help, you must specify a Help file for your application, and then associate specific Help topics with different objects in your application.
To add context-sensitive Help
You determine the Help file that can be accessed in your application by including the command SET HELP TO file in your code, where file is the name of your Help file. For example, if your Help file is called Myhelp.chm, you can use the following command:
SET HELP TO MYHELP.CHM
This command is typically included in the setup code for the main program of your application.
You can assign a Help topic to specific objects in your Visual FoxPro application.
To assign a Help topic to an object
For more information about mapping HTML Help topics to context ID numbers, consult the online Help for the HTML Help Workshop.
Note To assign Help topics to menu titles or menu commands, you must include the SET TOPIC TO command in the procedure associated with the menu title or menu command.
"What's This?" Help is similar to context-sensitive Help because it provides Help related to the specific object or control that currently has focus.
For WinHelp, instead of invoking the Help file and displaying the Help topic in the full default-sized Help window, "What's This?" Help displays the topic in a small pop-up window that disappears as soon as the user clicks anywhere on the screen. "What's This?" Help is useful for providing brief tip-style descriptions or definitions for specific controls.
Unlike WinHelp, HTML "What's This?" Help is displayed in the full default-sized Help window.
You associate "What's This?" Help with a particular form, form control, or toolbar by setting its WhatsThisHelpID property to a number representing a specific topic in your Help file.
Use the following properties and methods to implement "What's This?" Help:
| Property | Description |
| WhatsThisHelp | Set this property to true (.T.) on a form to enable "What's This?" Help for the form and any controls on the form. |
| WhatsThisButton | Set this property to true (.T.) if you want a "What's This?" Help button to appear in the title bar of the form. |
| WhatsThisHelpID | For a form, control, or toolbar, set this property to an ID number corresponding to a topic in your HTML Help file. |
| WhatsThisMode | Use this method to display the "What's This?" Help question mark mouse pointer and enable "What's This?" Help mode. Clicking an object displays the "What's This?" Help topic specified by the WhatsThisHelpID property for the object. |
To implement "What's This?" Help
You can program your application so that users can access your HTML Help system. Although an HTML Help system can consist of one or more separate files, Help appears to users as part of your application.
You can program your Visual FoxPro application to use graphical and .dbf-style Help with the SET HELP TO and SET TOPIC TO commands. SET HELP TO specifies the name of a custom Help file for your application. SET TOPIC TO sets the identifying keyword for a topic in the custom Help file.
When a user presses F1 in your application, Visual FoxPro can display a context-sensitive Help topic. To do this, assign a Help context ID to a topic in your Help table and assign the same value to the HelpContextID property of your form or control. When the form or control has the focus and the user presses F1, Visual FoxPro displays the matching topic.
Note F1 is enabled for context-sensitive Help by default. Because this is a recognized standard for Help, redefining this key is not recommended.
If you add Help buttons to your forms, users can access Help more easily. You should especially consider adding a Help button if your user is a novice.
To set context sensitivity and add a Help button
THIS.SetAll("HelpContextID", 7)
HELP ID THIS.HelpContextID
Tip Save the Help button as a class so that you can easily add it to any form. For more information about saving objects as classes, see Chapter 9, Creating Forms.
In addition to the .chm file you create for your HTML Help system, you can use a free-distributable setup program, Hhupd.exe, that will install and register the HTML Help runtime components listed below. Internet Explorer or the Internet Explorer runtime engine must be installed on your users machines.
| Component Name | Description |
| Hhctrl.ocx | HTML Help ActiveX control |
| Itss.dll | Dynamic link library that handles compiled HTML |
| Itircl.dll | Full-text search Dynamic link library |
| Hh.exe | HTML Help viewer |
You will find this setup program in the Redist folder in the folder where HTML Help Workshop has been installed. This setup program can be called from other setup programs, and can be made to run in 'quiet' mode so that it does not interfere with the setup program you may have already created. For a complete list of command line options, run Hhupd.exe/?.
Use the Microsoft Help Workshop, provided with previous versions of Visual FoxPro, to create Winhelp files. The Microsoft Help Workshop includes a Help Authoring Guide. The Help Authoring Guide (Hcw.hlp) is a graphical Help file that contains much of the information you will need to author a robust Help system.
WinHelp systems can have some or all of the following features:
In addition to creating a WinHelp file that contains useful information, you need to provide a means for users of your application to access Help. There are three ways to deliver Help:
A Help menu typically contains commands that provide access to the topics in your Help system. WinHelp 4.0 features the Help Finder window, which is a single dialog box providing access to contents, index, and full-text searching.
The Help Finder Window
It is strongly recommended to have a single command on your Help menu that opens the Help Finder window. Beyond that, you can place additional commands on the Help menu that provide system information, or copyright and version information about your application.
You can call the Help Finder window programmatically using the WinHelp function with the HELP FINDER parameter. For more information, see "Using the WinHelp Function" later in this chapter, and the WinHelp topic in the Help Authoring Guide.
Context-sensitive Help allows users to easily access Help topics relating to what they are doing or seeing in your application at any given time. For example, if a user is viewing a data entry form, context-sensitive Help could provide a topic relating specifically to that data entry form.
You decide the level of detail at which context-sensitive Help is implemented in you application. For example, you can associate a context-sensitive Help topic with a form, or you can associate more detailed Help topics with each control and field on your form.
Context-sensitive Help is typically accessed by pressing F1, but you can specify any key to activate context-sensitive Help with ON KEY LABEL.
Using Context-Sensitive WinHelp on a Form
To implement context-sensitive Help, you must specify a Help file for your application, and then associate specific Help topics with different objects in your application.
To add context-sensitive Help
You determine the Help file that can be accessed in your application by including the command SET HELP TO file in your code, where file is the name of your Help file. For example, if your Help file is called Myhelp.hlp, you can use the following command:
SET HELP TO MYHELP.HLP
This command is typically included in the setup code for the main program of your application.
You can assign a Help topic to specific objects in your Visual FoxPro application.
To assign a Help topic to an object
For more information about mapping Help topics to context ID numbers, see the Help Authoring Guide.
Note To assign Help topics to menu titles or menu commands, you must include the SET TOPIC TO command in the procedure associated with the menu title or menu command.
"What's This?" Help is similar to context-sensitive Help because it provides Help related to the specific object or control that currently has focus. However, instead of invoking the Help file and displaying the Help topic in the full default-sized Help window, "What's This?" Help displays the topic in a small pop-up window that disappears as soon as the user clicks anywhere on the screen. "What's This?" Help is useful for providing brief tip-style descriptions or definitions for specific controls.
Tip Keep your "What's This?" Help topics brief and concise so that the window doesn't grow too large to obscure the feature you're describing.
"What's This?" Help
You associate "What's This?" Help with a particular form, form control, or toolbar by setting its WhatsThisHelpID property to a number representing a specific topic in your Help file.
Use the following properties and methods to implement "What's This?" Help:
| Property | Description |
| WhatsThisHelp | Set this property to true (.T.) on a form to enable "What's This?" Help for the form and any controls on the form. |
| WhatsThisButton | Set this property to true (.T.) if you want a "What's This?" Help button to appear in the title bar of the form. |
| WhatsThisHelpID | For a form, control, or toolbar, set this property to an ID number corresponding to a topic in your Help file. |
| WhatsThisMode | Use this method to display the "What's This?" Help question mark mouse pointer and enable "What's This?" Help mode. Clicking an object displays the "What's This?" Help topic specified by the WhatsThisHelpID property for the object. |
Using a "What's This?" button
To implement "What's This?" Help
You can program your application so that users can access your Help system in Microsoft Help. Although a Help system can consist of one or more separate files, Help appears to users as part of your application.
You can program your Visual FoxPro application to use graphical and .dbf-style Help with the SET HELP TO and SET TOPIC TO commands or with the WinHelp function described later in this chapter. SET HELP TO specifies the name of a custom Help file for your application. SET TOPIC TO sets the identifying keyword for a topic in the custom Help file.
Another way to program your application to use Help is to call the WinHelp function. The WinHelp function is part of the Windows application programming interface (API). The WinHelp function is only available on the Windows platform.
You can use the WinHelp function in addition to the HelpContextID property, especially to call a second Help file.
Tip If you use SET HELP TO, HELP ID, and SET TOPIC TO, you don't need to use the WinHelp function.
To use the WinHelp function
For a description of these parameters, see "The wCmd Parameter" later in this chapter.
SET LIBRARY TO SYS(2004) + "FOXTOOLS.FLL" ADDITIVE
Help = RegFn("Help", "LCIC", "I")
The library must be set to Foxtools.fll. SYS(2004) returns the Visual FoxPro root directory, where Foxtools.fll is installed.
If you want to open a Help topic by sending its K keyword, define a variable with RegFn( ), like the Help variable in the previous example. If you want to open a Help topic mapped with a number, define a variable with RegFn like the HelpI variable in the previous example and use a number instead of a string for dwData. If you pass numbers, you must map them in the [MAP] section of the .hpj file to unique context strings defined with the number sign (#) footnote.
For example, if your Help file is called Myhelpfile.hlp, use CallFn( ) to open a topic in Myhelpfile.hlp by including the topic's K keyword:
#define HELP_KEY 0x0101
wCmd = HELP_KEY
cFilename = Myhelpfile.hlp"
dwData = "Add Menu Items at Run Time"
CallFn(Help, MainHWND(), cFileName, wCmd, dwData)
For more information on FoxTools functions, see Foxtools.chm in the Vfp98\Tools directory.
The following parameters specify options for the WinHelp function.
The hWnd parameter identifies the window requesting Help. Help uses this identifier to track which applications have requested Help. In Visual FoxPro, use the MainHWND( ) function included in the Foxtools.fll library for the hWnd parameter.
The lpzFileName argument represents a text string designating a valid path and file name for the Help file containing the desired topic. It is passed by value.
The wCmd parameter specifies either the type of search that Help uses to locate the specified topic or that the application no longer requires Help. It can be set to any of the following values.
| Constant | Value | Meaning |
| HELP_FINDER | 0x000B | Displays the Help Finder window. |
| HELP_CONTEXT | 0x0001 | Displays Help for a particular topic identified by a context number. |
| HELP_HELPONHELP | 0x0004 | Loads Help.hlp and displays the Using Help index topic. |
| HELP_INDEX | 0x0003 | Displays the main Help index topic as defined in the [OPTIONS] section of the Help Project file (.hpj). |
| HELP_KEY | 0x0101 | Displays the first topic found in the keyword list that corresponds to the keyword in the dwData parameter. |
| HELP_QUIT | 0x0002 | Informs the Help application that Help is no longer needed. If no other applications have requested Help, Windows closes the Help application. |
| HELP_SETINDEX | 0x0005 | Sets a specific topic as the index topic. |
The dwData parameter represents the topic for which the application is requesting Help. Its content and format depend on the value of wCmd passed when your application calls the WinHelp function.
In most calls to Help you pass the dwData argument by value. This is the default in Visual FoxPro.
Depending on the circumstances, dwData in the preceding line can either represent a text string, indicating a keyword to look up, or a numeric value, indicating the context number that identifies a specific topic.
The following list describes the format of dwData for each value of wCmd.
| wCmd Value | dwData Format |
| HELP_CONTEXT | A numeric value containing the context number for the topic. Instead of using HELP_INDEX, HELP_CONTEXT can use the value 1. |
| HELP_HELPONHELP | Ignored. |
| HELP_INDEX | Ignored. |
| HELP_KEY | A long pointer to a string that contains a keyword for the desired topic. |
| HELP_QUIT | Ignored. |
| HELP_SETINDEX | A numeric value containing the context number for the topic you want as the index. |
Because the WinHelp function can specify either a context number or a keyword, it supports both context-sensitive Help and topical searches of the Help file.
Note If a Help file contains two or more indexes, the application must assign one as the default. To ensure that the correct index remains set, the application should call Help with wCmd set to help_setindex (with dwData specifying the corresponding context identifier). Each call to Help should be followed with a command set to help_context. You should never use HELP_index with help_setindex.
When a user presses F1 in your application, Visual FoxPro can display a context-sensitive Help topic. To do this, assign a Help context ID to a topic in your Help table and assign the same value to the HelpContextID property of your form or control. When the form or control has the focus and the user presses F1, Visual FoxPro displays the matching topic.
Note F1 is enabled for context-sensitive Help by default. Because this is a recognized standard for Help, redefining this key is not recommended.
If you add Help buttons to your forms, users can access Help more easily. You should especially consider adding a Help button if your user is a novice.
To set context sensitivity and add a Help button
THIS.SetAll("HelpContextID", 7)
HELP ID THIS.HelpContextID
Tip Save the Help button as a class so that you can easily add it to any form. For more information about saving objects as classes, see Chapter 9, Creating Forms.
The Help application is a shared resource available to all Windows applications. Because it is also a stand-alone application, the user can execute it like any other application. As a result, your application has limited control over the Help application.
While your application cannot directly close the Help application window, it can inform the Help application that Help is no longer needed. Before closing its main window, your application should call Help with the wCmd parameter set to help_quit, which informs Help that your application will not need it again.
An application that has called Help at some point during its execution must call Help with the wCmd parameter set to help_quit before the application terminates.
If an application opens more than one Help file, it must call the WinHelp function to quit the Help application for each file.
If an application or dynamic-link library (DLL) has opened a Help file but no longer wants the associated instance of the Help application to remain active, then the application or DLL should call Help with the wCmd parameter set to help_quit to quit that instance of the Help application.
Note Before terminating, an application or DLL should always call Help for any of the opened Help files. A Help file is opened if any other Help call has been made using the Help file name.
The Help application does not exit until all windows that have called Help have subsequently called it with wCmd set to help_quit. If an application fails to do so, then the Help application will continue running, even after all applications that requested Help have terminated.