Customizing .DBF-Style Help

Article
10/23/2006

In your application code, you specify which Help file is used, which and when topics are displayed, and other optional settings. If you include context-sensitive Help, your users can easily get Help on demand from your application's dialog boxes and menu commands.

Specifying a Help Table

Specify your Help table by issuing the command SET HELP TO filename. This closes the current Help table if one is already open and opens filename as the new Help table.

In a typical programming scenario, save the name of the current Help file in a variable and specify the name of your Help file in your initialization code, as in the following example:

cUserHlp = SET("HELP", 1)
SET HELP TO MYHELP.DBF

When the application exits, you can restore the original Help file:

SET HELP TO (cUserHlp)

Displaying Topics in the Help Window

After specifying the Help table, you can specify which topics you want to display in these ways:

For topic selection by topic name, use either the HELP Topic or the SET TOPIC TO cHelpTopicName commands.
For context-sensitive topics, use the HelpContextID property.
To display a subset of topics, use the SET HELPFILTER command.

Selecting Topics by Topic Name

To select topics by name, use the HELP Topic command. When you use this command, Visual FoxPro searches the Help table to find the record whose topic field matches Topic. The search is case-insensitive.

When Visual FoxPro finds a match, it displays the contents of the Details memo field in the Details mode of the Help window. If Visual FoxPro cannot find a match, it displays all the topics in a list in the Help Topics dialog box with the closest match highlighted.

Enabling Context-Sensitive Help

You can design your application so that your user is able to get context-sensitive Help in two ways:

By pressing F1 at any time.
By clicking a Help button that you include in your forms and dialog boxes.

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 in 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 create a context-sensitive Help topic

In the first field of a record in your Help table, enter a numerical value.
Fill in the record's Topic and Details fields.

Now you're ready to map the Help topic to your form. It's a good idea to map a Help button, the form, and its objects to the same Help topic.

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. In the Form Designer, choose Save As Class from the File menu. For more information about saving objects as classes, see Creating Forms.

Controlling the Location of the Help Window

To specify a location for your Help, you must create your own window using the DEFINE WINDOW command. Use this command in your initialization code to specify the size and location of the window and then display the window by activating or showing it.

For example, the following commands define a window named test and display the current Help table within that window:

DEFINE WINDOW test FROM 1,1 TO 35,60 SYSTEM 
ACTIVATE WINDOW test 
HELP IN WINDOW test

Tailoring Help to Your Application

Because you can add any number of fields to a Help table and can use any logical expression to select Help topics, only your imagination limits the kind of Help system you can create.

For example, you can:

Define one or many program variables that control the behavior of your Help system and then assign values to these variables based on the operating mode of your program.
Provide more detail in Help files for novice users than you provide in files for experienced users.
Permit users to access Help only if they enter an appropriate password.