Chapter 23 -- Creating Graphical Help | Microsoft Visual FoxPro 6. 0 Programmer's Guide 1998

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
WinHelp 4.0

HTML Help

HTML Help provides many of the features of Winhelp, and adds the following features:

Support for HTML.
Support for ActiveX, Java, and scripting (Javascript and Microsoft Visual Basic Script).
Support for HTML image formats (.jpg, .gif, .png).
Capability to jump from a Help topic to a site on the Internet.
Capability to view the HTML code for a Help topic.

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.

Planning Access to Online HTML Help

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:

A Help menu a menu that appears on the main menu bar of your application.
Context-sensitive Help Help that appears when a user presses F1 (or another key that you specify) while a particular object, control, or menu option is selected.
"What's This?" Help Help that appears when a user calls for help on a particular object or control.

Implementing HTML Help is similar to implementing WinHelp. The following sections describe how you can implement HTML Help for your application.

Planning a Help Menu

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.

Adding Context Sensitivity

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

Specify a Help file for your application.
Assign a Help topic to each object for which you plan to provide context-sensitive Help.

Specifying a Help File

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.

Assigning Help Topics

You can assign a Help topic to specific objects in your Visual FoxPro application.

To assign a Help topic to an object

In Design mode, open the object a form, control, or toolbar, for example that you want to assign context-sensitive Help to.
View the object's properties.
Set the HelpContextID property to the number representing a specific topic in your HTML Help file.

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.

Implementing "What's This?" Help

"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

In design mode, open the form you want to enable "What's This?" Help for.
Set the form's WhatsThisHelp property to true (.T.).
To display a "What's This?" Help button in the form's title bar, set the form's WhatsThisButton property to true (.T.).
To associate a "What's This?" Help topic with the form, set the form's WhatsThisHelpID property to an ID number corresponding to a topic in your HTML Help file.
To associate a "What's This?" Help topic with a specific control on the form, select the control and set its WhatsThisHelpID property to an ID number corresponding to a topic in your HTML Help file.

Programming Help Features

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.

Reserving F1

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.

Including Help Buttons on Forms

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

In the Init event for your form, set the HelpContextID property for all the form's objects to the same value you assigned to the Help topic. For example, if the value is 7, you can use the following command:
```
THIS.SetAll("HelpContextID", 7) 
```
Add a command button to your form.
Set the Caption property of the command button to Help.
In the Click event of the command button, add the following command:
```
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.

Distributing a Compiled HTML Help System

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/?.

WinHelp 4.0

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.

Choosing Help Features

WinHelp systems can have some or all of the following features:

A contents page that provides a hierarchical view of the topics in your Help system.
An index, based on keywords you provide, that guides a user to specific information.
Full-text search capabilities that allow users to search for information in Help based on specific words and phrases.
Text with multiple fonts, font sizes, and colors.
Graphics, including bitmaps with multiple resolutions.
Macros that automate or extend the operation of the Help system.
Hot spots mouse-sensitive areas you create to give users jumps that link topics; pop-up windows that display additional text; and macro commands that you add to the Help system.
Segmented hypergraphics: graphics with one or more hot spots.
Secondary windows.
Customizable menus.
Graphics in Windows metafile format.
.DLLs.

Planning Access to Online Help

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 a menu that appears on the main menu bar of your application.
Context-sensitive Help Help that appears when a user presses F1 (or another key that you specify) while a particular object, control, or menu option is selected.
"What's This" Help Help that appears as a brief pop-up tip when a user calls for help on a particular object or control.

Planning a Help Menu

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.

Adding Context Sensitivity to Help

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

Specify a Help file for your application.
Assign a Help topic to each object for which you plan to provide context-sensitive Help.

Specifying a Help File

SET HELP TO MYHELP.HLP

This command is typically included in the setup code for the main program of your application.

Assigning Help Topics

You can assign a Help topic to specific objects in your Visual FoxPro application.

To assign a Help topic to an object

In Design mode, open the object a form, control, or toolbar, for example that you want to assign context-sensitive Help to.
View the object's properties.
Set the HelpContextID property to the number representing a specific topic in your Help file.

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.

Implementing "What's This?" Help

"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

In design mode, open the form you want to enable "What's This?" Help for.
Set the form's WhatsThisHelp property to true (.T.).
To display a "What's This?" Help button in the form's title bar, set the form's WhatsThisButton property to true (.T.).
To associate a "What's This?" Help topic with the form, set the form's WhatsThisHelpID property to an ID number corresponding to a topic in your Help file.
To associate a "What's This?" Help topic with a specific control on the form, select the control and set its WhatsThisHelpID property to an ID number corresponding to a topic in your Help file.

Programming Help Features

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.

Using the WinHelp Function

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

Define the command parameters that you'll pass in your application.
For a description of these parameters, see "The wCmd Parameter" later in this chapter.
Set the library with SET LIBRARY TO and define the variables to be used, typically in the initialization code for your application's main file.
```
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.
Use CallFn( ) to call the function.
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.

Specifying WinHelp Parameters

The following parameters specify options for the WinHelp function.

The hWnd Parameter

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

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

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

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.

Reserving F1 for Help

Note F1 is enabled for context-sensitive Help by default. Because this is a recognized standard for Help, redefining this key is not recommended.

Including Help Buttons on Forms

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

In the Init event for your form, set the HelpContextID property for all the form's objects to the same value you assigned to the Help topic. For example, if the value is 7, you can use the following command:
```
THIS.SetAll("HelpContextID", 7) 
```
Add a command button to your form.
Set the Caption property of the command button to Help.
In the Click event of the command button, add the following command:
```
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.

Quitting Help

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.