Help, SET HELP, Set(“Help”), SET HELPFILTER, SET TOPIC, SET TOPIC ID

Visual FoxPro is unusual in having not one, not two, but three help engines built in: one for cross-platform-compatible DBF-based help, one for interfacing to the native “legacy” Windows HLP engine, and one for compressed HTML Help CHM files. These flexible commands allow you to use the best features of each.

Usage

SET HELP ON | OFF | TO cHelpFileName
cOnOrOff = SET( "HELP" )
cHelpFileName = SET( "HELP", 1 )
HELP [ cTopic | ID nHelpContextID ] [ NOWAIT ]
   [ IN [ WINDOW ] winName | IN [ WINDOW ] SCREEN ]

Three help engines! What pandemonium! What to do? Here’s our take.

The DBF Help is “included for backward compatibility” and produces the world’s ugliest help screens. We think it could be the basis for an awesome tool for generating help, but we wouldn’t consider actually showing an application with DBF-based help to a client. The “classic” WinHelp engine is a pretty decent help engine, and if you already have substantial investment in tools to create HLP files, don’t abandon them just yet. While Microsoft will be shipping the WinHelp engine as part of the operating system for some time yet, it’s time to plan a transition to HTML Help soon, if you haven’t already.

Finally HTML Help. We think this is a pretty cool tool. You will notice that in the Developer Downloads available at www.hentzenwerke.com, the entire Hacker’s Guide is available in HTML Help format (as it was for the previous version of the Hacker’s Guide). We’re impressed with what we can do with this, and we like it. HTML Help provides all of the capabilities of WinHelp (except one) and is easier to write (HTML is much prettier than RTF, in our opinion) and test.

The one gotcha that might keep you using WinHelp for a while is that HTML Help does not work with the “WhatsThisHelp” feature of dialogs. Since there are other ways of presenting that information, such as having a Help button on the form, or using ToolTips to pass information to the client, we don’t think this is a big loss.

Most of the Help commands and optional clauses are based on Fox Software’s original DOS Help engine, and don’t apply to, or don’t make sense in most VFP applications. For applications using either of the newer Windows engines, SET HELP TO your help file, set the HelpContextIDs of the forms and controls that can supply help, and sit back and let the engine do its thing.

If you’re using the original DOS Help engine, you may want to SET HELP OFF if you are allowing the user to edit or modify the DBF form of the file, to avoid a “File is in use” error. Otherwise, plan to leave Help ON the rest of the time.

SET HELP TO accepts a path and file name. If the filename specified has an HLP extension, FoxPro uses the WinHelp engine; with a DBF extension it attempts to use the built-in DBF engine. A file with a CHM extension runs the HTML Help engine. If you try something completely different, different versions react in different ways, but you usually end up with an error message. In VFP 6 and 7, the DBF engine fires first and reports “Not a table.” In VFP 3 and 5, we got “Not a Windows Help file.” In the next version, we’re betting we get an HTML Help engine error, just so they keep firing differently. Sheesh.

For DOS-based Help, the WINDOW | IN WINDOW clauses are the same as those described in the MODIFY MEMO topic, so we won’t drag you through the syntax again.

Pass the cTopic string or numeric HelpContextID to bring up a specific topic. Items in the Visual FoxPro interface have HelpContextIDs assigned—use SYS(1023) to sniff them out. You will need to assign HelpContextIDs to the controls and forms you create. Pass nothing to get the main contents screen.

HELP NOWAIT really is only applicable for the DBF form of help, as the WinHelp HLP format is by nature NOWAIT. DBF Help could be a pain to manage inside a Foundation Read in 2.x, but allowing it to NOWAIT while other processing goes on seems more natural in VFP.

DBF Help needs a character field for the topic name and a memo field for the details as the first two fields in the table. SET HELP to any table that lacks the proper structure and kablooie! Fatal Errors or Invalid Page Faults left and right! How rude! We would expect an "I'm sorry, this is not a valid Help file format," not a crash-and-burn scene! Unsatisfactory.

If your DBF Help has the right structure but no records, VFP 6 and later displays an error—2036—with the message "The current Help file is empty" with an OK and a Help button—think about that one. Versions of VFP before 6.0 would crash, so this is an improvement.

Many people seem to be unaware of it, but there is a another method of invoking help, besides pressing F1 or issuing the Help command, and that's Shift+F1. Similar to the "What's This?" option introduced in the Windows 95 interface, Shift+F1 turns the cursor to a combined question mark and pointer arrow and provides the Help file with the ContextID of the item clicked on by the user, whether it is a form, a button or even a menu selection. This form of "safe" exploring of an interface lets users determine what actions will occur upon selection of unfamiliar options and is a great way for them to learn the product non-destructively. This is a technique that should be encouraged, we think! In addition, in combination with SYS(1023), it is a nice way of determining the HelpContextIDs of the built-in gadgets (like a GETFONT dialog) that your application's help file needs to support.

Example

SET HELP TO \VFP\HACKFOX.CHM
SET HELP ON
? SET("HELP") && "ON"
? SET("HELP",1) && "C:\VFP\HACKFOX.CHM"

HELP WhatsThisButton  && Brings up help on WhatsThisButton
HELP ID 30000079      && Brings up help on the Options
                      && dialog box

Usage

SET HELPFILTER [ AUTOMATIC ] TO lExpression
SET TOPIC TO [ cTopic ] | [ ID nHelpContextID ] [ lExpression ]

HELPFILTER is the equivalent of SET FILTER, and applies only to the DBF form of Help. lExpression can be any expression that evaluates to a logical true or false value for each record. The AUTOMATIC keyword causes the filter to be cleared after Help has been called up and closed. Several folks came up with clever schemes to add additional fields onto the basic ones supplied with the DBF-style help and use these fields to supply more screen-sensitive help than just a single entry. Pressing the Topics button in DBF-style help while a HELPFILTER is in effect shows only those records that pass the filter criteria.

SET TOPIC TO allows the Help file to be pointed to a particular entry before Help is invoked. SET TOPIC TO does not change the position of the Help file unless the Help command is executed again. Both forms, the character-based Topic and the numeric ContextID, can be used with any of the Help engines; however, there are some slight differences in behavior. For a specific topic to be displayed, Windows Help requires the entire topic title to be entered, whereas the DBF format will locate the first topic that matches the supplied string.

The logical expression makes sense only for DBF Help. You should also be able to supply a logical expression to SET TOPIC, similar to that used in SET HELPFILTER. It worked in 2.6. It doesn't in 3.0, nor does it work in 5.0. It is no longer documented in 6.0 and later.

In versions prior to VFP 7, SET TOPIC didn't work at all with HTML Help. It works in VFP 7.

With most controls and forms, you don’t need to set their topics programmatically. Use their HelpContextID property instead.

Example

* Using a custom DBF with fields cFIELD and cScreen.
* This should work in 3.0, but doesn't.
SET TOPIC TO cField = This.Name or cScreen = ThisForm.Name
* This form does work with FOXHELP.DBF, HLP and CHM.
SET TOPIC TO "Sample"
* But this doesn't work with CHM help files
SET TOPIC ID TO 1895825500

SET HELPFILTER TO HelpFile.Screen = WONTOP() or ;
                  HelpFile.Screen = "GENERAL"
* New topics in Help, not covered in the docs:
SET HELPFILTER TO TOPIC = "Changes"

See Also

HelpContextID, Modify Memo, Set Filter, Sys(1023)