Programming WinHelp Features

Article
11/14/2006

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 Help with the SET HELP TO and SET TOPIC TO commands or with the WinHelp function described later in this topic. 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 section.
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

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