Chapter 24 -- Creating .DBF-Style Help | Microsoft Visual FoxPro 6. 0 Programmer's Guide 1998

.DBF-style Help is simple to create and uses standard Visual FoxPro tables that port easily to other Visual FoxPro platforms. If you want a simple solution to providing help, if you're developing cross-platform applications, or if you prefer to maintain a backward-compatible help file, you can provide .DBF-style help for your users.

This chapter discusses:

Designing .DBF-Style Help
Viewing the Sample .DBF-Style Help File
Using .DBF-Style Help
Customizing .DBF-Style Help

Designing .DBF-Style Help

.DBF-style Help files, or Help tables, are free tables that are displayed in the Help window. With this style of Help, your users can:

Get context-sensitive Help for the current dialog box, menu command, or object by pressing F1.
Jump to related topics within the Help file by selecting a topic from the See Also drop-down list.
Select a keyword or phrase in the middle of a topic and jump to it by clicking the Look Up button.
Copy any selected text in the Help window to the clipboard.

A sample .DBF-style Help file, Ttrade.dbf, is included in Visual FoxPro and is located in the Visual Studio \Samples\Vfp98\Tastrade\Help directory. The following sections use the Ttrade.dbf sample to describe designing and navigating .DBF-style Help.

Viewing the Sample .DBF-Style Help File

To view the Ttrade.dbf sample Help file

In the Command window, with the default directory set to the directory containing Ttrade.dbf, type:
```
SET HELP TO TTRADE.DBF HELP 
```
Visual FoxPro displays the Ttrade .DBF-style Help in its own window.

The .DBF Help window has two modes, Topics and Details. The Topics mode displays a list of all the topics in the Help file. Note that the font for the .DBF Help window is MS Sans Serif and cannot be changed.

.DBF Help window in Topics mode

When you double-click a topic, the contents of that topic appear in Details mode.

.DBF Help window in Details mode

Help Table Requirements

Help tables hold a maximum of 32,767 records and must contain at least two fields. The table may have an optional first field for context sensitivity. The following example shows you the setup of a typical Help table:

TTRADE table in Browse mode

There are no requirements for the field names. The field types are, in order:

Numerical This field is optional and contains the Help context ID used with context-sensitive Help.

Character This is the topic name that appears in the Topics mode of the Help window.

Memo This field holds the information displayed in the Details mode of the Help window.

Beyond these requirements, you can add as many additional fields as you wish.

Understanding Ttrade.dbf

Ttrade.dbf is a small example of a .DBF-style Help file. You can pattern your Help file after Ttrade.dbf, or you can create your own design. Because a Help file is a table, you can create your own Help file by creating a new table or by copying and changing an existing one.

To view or edit the Ttrade.dbf table, open it and browse through it as you would any other table. If you've previously run the command SET HELP TO TTRADE.DBF, you must first use the SET HELP OFF command before opening Ttrade.dbf.

TTRADE Topics

Several kinds of topics are included in Ttrade.dbf, including:

Step-by-step instructions.
Interface topics for context-sensitive Help, including menu commands and dialog boxes.
General information.

You might consider these and other categories for your own Help file.

TTRADE Details

When a user selects a topic from the Topics mode, the Help window displays the contents of the memo field named Details.

TTRADE Cross-References

See Also cross-references appear at the end of the Details information for most Help topics. These references are displayed automatically in the See Also box and act as direct links to related topics.

To create a See Also cross-reference

At the end of the memo field, type See Also followed by a colon and optional spaces.
On the same line, type a comma-delimited list of the desired topics.
Enter a carriage return to signal the end of the list.

Case doesn't matter in the See Also list, and Visual FoxPro trims leading and trailing spaces from each referenced topic. For example, cross-references for the Overview topic appear in the following illustration.

Contents of the Overview topic s memo field

Tip Add lines above and below your See Also section at the end of your topic to separate it visually from the contents of the topic.

When locating a topic in the See Also box, Visual FoxPro tries to match the user s selection with the first Help topic that consists of or begins with the same text string. If Visual FoxPro cannot find a match, it displays No help found for topicname in the status bar.

Using .DBF-Style Help

Your user will be able to easily access Help if you include a Contents command on your Help menu that uses the HELP command. When a user chooses the Contents command, the Help window appears in Topics mode. The user can either scroll through the list to find the desired topic or type a letter to select the first topic starting with that letter. Once a topic is selected, there are three ways to display information about the topic:

Double-click the topic in the list.
Click the Help button.
Press ENTER.

Customizing .DBF-Style Help

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 Chapter 9, 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.