Copyright: Portions ® 1994 Big Dog Software


Specifying the Source Project

The source project field is used to specify the name of a Visual Basic project file.  Click on this field or on the File menu selection called Select source project.  When you do this, a standard file selection window is opened.  Use the controls in this dialog box to select a Visual Basic project file.  Visual Basic project file names end with the file extension ".MAK"

In order for the help file helper to use a Visual Basic project, that projects form (.FRM) files must have been saved as text files.


Specifying the Help File source name

The help file name field is calculated by the Helpfile Helper based on the HelpFile property assigned to the Visual Basic project.  The help file name gets assigned by using the Options/Project Options menu during your Visual Basic editing session.

The file name that goes in this field is the name of the rich text format (RTF) file that will be generated as part of the output of the help file helper.  The RTF file will be generated in the same directory as the Visual Basic project file.

The help file helper uses the Microsoft Word 2.0 word processor to generate the rich text output file.


Specifying the Help Project file source name

The help project file name is calculated by the Helpfile Helper based on the HelpFile property assigned to the Visual Basic project.  The help file name gets assigned by using the Options/Project Options menu during your Visual Basic editing session.

The file name that goes in this field is the name of the help project (HPJ) file that is required by the help compiler.  This project file will be generated by the Helpfile Helper in the same directory as the Visual Basic project file.

To generate the output that is used by the Helpfile compiler, use the File/Generate Help File Skeletons menu selection.


The Help Context display list

The help context display list is extracted from the form (FRM) files that are referenced by the visual basic project that was specified in the Source Project field.  This list contains an entry for each control in the project that has a value in its HelpContextID property.

You can tell from this list whether you have assigned help context identifiers to all of the controls you want before generating the skeletons for the help file that will provide context sensitive help for your Visual Basic project.


Generate Helpfile Skeletons

This menu selection will create the help project and rich text files that are required by the help compiler (HC31.EXE).  The skeletons generated are intended to be further modified by the developer or technical writer so that the context entries contain more than "put your documentation here" tags.

The most error prone part of creating context sensitive help files is in the coordination of context identifiers between the source code, help project file and the rich text format document.  The Helpfile Helper completely automates this step.

Be sure to have all of the context identifiers assigned prior to generating the skeletons.  The Helpfile Helper will not overwrite the rich text format document, and will prompt before overwriting the project control file.


Print context ID report

This menu selection (File/Print) prints the contents of the context identifier list to the default printer.  The default printer must be capable of landscape output.  Some problems could occur if the default printer driver reports landscape capabilities and then does not support them via the standard Windows 3.1 escape operations.


Exit

To exit the Helpfile Helper application, use this menu selection. (File/Exit)


Overview of the Helpfile Helper

The Helpfile Helper is another freeware product from Big Dog Software.  Big Dog Software is dedicated to providing high quality tools at a fair price (free until venture capital is obtained).  If you find Big Dog Software products useful and would like to make a contribution (no amount is too small), feel free to do so.  All contributions will be put into the "startup account" so that one day, we will be able to open our doors as a paying employer.

The Helpfile Helper is a tool that should make it easy for Visual Basic programmers to generate context sensitive help files.  This difficult task is often managed by teams of developers, designers and writers, with the cross member coordination done by spreadsheet or other document..  With the Helpfile Helper, the coordination of help context identifiers between the application, help project control file (.HPJ) and the rich text document is automated.

To do this, the Helpfile Helper analyzes your Visual Basic project source files and maps out a list of help context identifiers that have been assigned to the controls and menus that make up your application.  This map is projected into the help file helpers main context ID map.  Using the map (which may be printed) you can determine if you have assigned context identifiers to the controls that require help support.

The Helpfile Helper requires Microsoft Word version 2.x  and the Microsoft Help Compiler (HC31.EXE).

For more information, select one of the following:

Preparing the Visual Basic Project Code

Opening the Visual Basic Project file with the Helpfile Helper

Generating the Help Compiler Source files

Activating the contents page in your application

Closing help when your application terminates

This help file was created using the Helpfile Helper.


Preparing your project source code for context sensitive help

Before the Helpfile Helper can analyze your source code, you must save each form file as text and assign the project help file name.

All versions of Visual Basic to date have provided the means to save forms in textual form.  If you need to, open your project and save each form as a text file (using the File menu, Save as selection, click on the save as text checkbox so that an X appears).  Be sure that the name of the file is not changed.  Saving as text is a good default option for all of your projects with only minor "edit session" performance penalties.

Assigning the project help file name is done by clicking on the options menu (in the VB editor), selecting Project, and filling in the help file name (e.g. name.hlp) and clicking the OK button.  Be sure to save your project after assigning a help file name.


Opening the Visual Basic Project file with the Helpfile Helper

Once your projects are prepared (in text form and with a project help file name), run the help file helper.  Click on the field labeled "VB Source Project".  This causes a standard "file opener" to be displayed.  Using the controls provided, set the drive, directory and file name to the project (.MAK) to be analyzed and then click the OK button.  The project will be analyzed and the context map will be displayed.  If no report is displayed in the context list, you need to assign context identifiers to your controls.

When the context identifier report is displayed, you can print the report to a landscape capable printer or generate help control and help file skeletons.  Help files are created using the Windows help compiler (not included).  This help compiler requires at least two special files as input before you can create your help file.  The Helpfile Helper will create these special files for you (in the same directory as your project).  The names used (e.g. HELPNAME.HPJ, HELPNAME.RTF) are displayed in the appropriate fields in the upper right portion of the Helpfile Helper screen.  You may change these names before generating help compiler source files (the skeletons).


Generating the Help Compiler Source files

The Helpfile Helper utilizes Microsoft Word (version 2.x) to create the rich text portion of the help file.  If Word is properly installed on your computer, the Helpfile Helper should be able to start it automatically to generate the rich text file (.RTF).  To start generating the help compiler source files, make sure you have opened a project, then click on the File menu and select Generate Helpfile Skeletons.  This causes the Helpfile Helper to generate the help compiler project file (the HPJ file) and if it has not been created before, the rich text file (using Microsoft Word 2.x).

Rich text is a special format required by the help compiler.  Microsoft Word is used to generate this special file because A). It can, and B). It is in wide usage.  Once the rich text is generated, you can open the file with word and replace the "place holder" text that was inserted by the Helpfile Helper with words of your choosing.  There will be a placeholder (e.g. "Place the help text for controlname , formname, here.") for each control that had a unique help context identifier in your visual basic source code.  Duplicate context identifiers and control arrays with nonduplicate context identifiers are handled properly.

Once you have completed filling in all of the place holders, you will need to compile the help source files using the help compiler.  Type the command:

HC31 HELPNAME.HPJ

Substitute HELPNAME above with the name of the help project control file (HPJ) that was generated by the Helpfile Helper.  You may need to supply a full path name to the HC31 program if your computer is unable to locate the help compiler.  The help compiler (HC31) is provided with many language products sold today, including Visual Basic, Professional edition.


Activating the contents page from your application

It is common for the application to provide a standard entry point into the help file at the contents page.  Unlike context sensitive help, this action is supported only if the programmer adds code to the application.  To facilitate this type of entry, the Helpfile Helper adds an extra context identifier to the rich text file that is created by Word.  This extra context entry is named "main_contents" (do not name any of your controls "main_contents").

To bring up the help window with the page at the contents text, you need to declare an external function that is provided with Windows.  The following declaration should be added to the form that will be calling the contents page.  Put the declaration in the "GENERAL DECLARATIONS" section of the form.

Declare Function WinHelp% Lib "USER" (ByVal hWnd%, ByVal lpzfname$, ByVal wcmd%, dwdata As Any)

The declaration should appear on a single line.  Then, to call the help contents page into view, add the following code to your application in the appropriate event processing subroutine:

Dim i%

i = WinHelp((Me.hWnd), (app.HelpFile), 3, ByVal "main_contents")

See Also:

Closing help when your application terminates


Closing help when your application terminates

Proper application behavior includes closing your application help file as an application terminates.  Unlike context sensitive help support, this behavior requires the programmer to add code to the application.

The following declaration should be added to the form that will be calling the contents page.  Put the declaration in the "GENERAL DECLARATIONS" section of the form.  If it is already there, there is no need to declare it twice.

Declare Function WinHelp% Lib "USER" (ByVal hWnd%, ByVal lpzfname$, ByVal wcmd%, dwdata As Any)

The declaration should appear on a single line.  Then, to call the help contents page into view, add the following code to your application in the FORM_UNLOAD subroutine:

Dim i%

i = WinHelp((Me.hWnd), (app.HelpFile), 2, ByVal 0&)

See Also:

Activating the contents page in your application


About Big Dog Software

Big Dog Software is a basement enterprise run by Dan Rogers in Piscataway, NJ.  The company is the remains of an underfunded company named Secure-Soft, Inc.  Secure-Soft had a single software product that was of benefit to the small Burglar alarm installation shop, but due to limited capital went under six years after it was founded.  The freeware policy is an outlet for a profuse stream of high quality and useful tools that would otherwise fade into obscurity if the products had to be marketed and taxes paid.

If you are a venture capitalist with a highly experienced management team looking for high quality software products ready to market, feel welcome to contact Dan at:

Big Dog Software

25 Shirley Parkway

Piscataway, NJ 08854

The name Big Dog is a remembrance of an old friend that passed away in her 15th year of faithful companionship and houndness.


Assigning help context identifiers to your controls

A context identifier is a number that is used to link your applications visual components to individual topics within a help file.  Visual Basic controls that are capable of accepting input focus (becoming the active control) usually supply a HelpContextID property.

From the Visual Basic programming mode, click on each control that you want to provide help for, open the properties window and assign a value to the HelpContextID property.  A good practice is to use a range of numbers for all of the controls on a given form, skipping a few values between numbers for later changes.