Visual C++ 6 Unleashed

Visual C++ 6 Unleashed

By MICKEY WILLIAMS and David Bennett

Managing Help Projects

As mentioned previously, Microsoft doesn't provide any integrated tools for developing your own RTF files that go into a help project. However, Visual C++ 6.0 does include a tool that is very useful for managing all the other tasks involved in developing help projects. This tool is the Help Workshop.

You won't find the Help Workshop in any of the menus in Developer Studio, although you can add it to your Tools menu as you saw in Chapter 1. The executable for Help Workshop is found in ...\vc\bin\hcw.exe under whichever directory you have installed Developer Studio.

Help Workshop allows you to do many different things associated with help project development, including the following:

The next few sections cover each of these items.

Help Project Files

The help project (.hpj) file controls how the various pieces of your help project are assembled to create the .hlp file that is actually used by your applications. This file contains several sections, similar to those that you might have seen in .ini files. You may edit the .hpj file for your project with any text editor or you can edit it from within the Help Workshop, as shown in Figure 33.11.

33fig11.gif

Figure 33.11 Help Project Files in Help Workshop.

Help project files contain the following sections:

You may edit the help project file directly, using a text editor, although it is generally easier to use Help Workshop, which provides a nice graphical interface for filling in all the relevant settings, including additional help on what each of the settings means. For example, a portion of the dialog for setting project options is shown in Figure 33.12.

33fig12.gif

Figure 33.12 Help Workshop Options settings.

Contents Files

The contents (.cnt) file specifies the help page that will be displayed to the user when he or she chooses the Contents tab of WinHelp. Once again, you can edit the .cnt file directly with a text editor, although it is easier to use the graphical interface provided by Help Workshop. To do this, simply open your .cnt file in Help Workshop, which will present a dialog like the one shown in Figure 33.13.

33fig13.gif

Figure 33.13 Editing Contents files.

This dialog allows you to use the buttons on the left to edit or remove existing entries, as well as add new entries to your table of contents.

Compiling Help Projects

Before your applications can make use of your help projects, all the components previously discussed must be compiled to create a single Windows help file, which is given an .hlp extension. You may compile your help project from within Help Workshop by selecting the Compile command from the File menu. This is useful for when you are developing your help project.

However, if you created your application with AppWizard, you will notice that a batch file named MakeHelp.bat has been added to your project directory. This file is called whenever you build your Visual C++ project and is responsible for creating the help file for your project. An example of MakeHelp.bat is shown here:

@echo off
REM -- First make map file from Microsoft Visual C++ generated resource.h
echo // MAKEHELP.BAT generated Help Map file.  Used by HELPSDI.HPJ. >"hlp\HelpSdi.hm"
echo. >>"hlp\HelpSdi.hm"
echo // Commands (ID_* and IDM_*) >>"hlp\HelpSdi.hm"
makehm ID_,HID_,0x10000 IDM_,HIDM_,0x10000 resource.h >>"hlp\HelpSdi.hm"
echo. >>"hlp\HelpSdi.hm"
echo // Prompts (IDP_*) >>"hlp\HelpSdi.hm"
makehm IDP_,HIDP_,0x30000 resource.h >>"hlp\HelpSdi.hm"
echo. >>"hlp\HelpSdi.hm"
echo // Resources (IDR_*) >>"hlp\HelpSdi.hm"
makehm IDR_,HIDR_,0x20000 resource.h >>"hlp\HelpSdi.hm"
echo. >>"hlp\HelpSdi.hm"
echo // Dialogs (IDD_*) >>"hlp\HelpSdi.hm"
makehm IDD_,HIDD_,0x20000 resource.h >>"hlp\HelpSdi.hm"
echo. >>"hlp\HelpSdi.hm"
echo // Frame Controls (IDW_*) >>"hlp\HelpSdi.hm"
makehm IDW_,HIDW_,0x50000 resource.h >>"hlp\HelpSdi.hm"
REM -- Make help for Project HELPSDI


echo Building Win32 Help files
start /wait hcw /C /E /M "hlp\HelpSdi.hpj"
if errorlevel 1 goto :Error
if not exist "hlp\HelpSdi.hlp" goto :Error
if not exist "hlp\HelpSdi.cnt" goto :Error
echo.
if exist Debug\nul copy "hlp\HelpSdi.hlp" Debug
if exist Debug\nul copy "hlp\HelpSdi.cnt" Debug
if exist Release\nul copy "hlp\HelpSdi.hlp" Release
if exist Release\nul copy "hlp\HelpSdi.cnt" Release
echo.
goto :done

:Error
echo hlp\HelpSdi.hpj(1) : error: Problem encountered creating help file

:done
echo.

The first half of MakeHelp.bat is devoted to generating the help mapping (.hm) file that is used to associate help contexts with the resource identifiers used within your C++ project. You will look at help mapping files and the makehm utility in more detail later.

The most important part of MakeHelp.bat is the line that actually compiles your help project. This is done by calling hcw.exe, as in the following line:

start /wait hcw /C /E /M "hlp\HelpSdi.hpj"

The /C switch tells hcw to compile the help project file that is specified, and the /E switch tells hcw to exit when it finishes. The /M option is used to minimize the window for hcw so that it is out of the way while it is compiling.

TIP

When compiling your help project from the command line or from within Developer Studio, you see only basic error messages, like the one shown here:

hlp\HelpSdi.hpj(1) : error: Problem encountered creating help file

Obviously, this doesn't give you much help on what went wrong. You can see more detailed error messages if you try to compile the help project from within the Help Workshop GUI.

If your help project compiles successfully, you will be the proud owner of a bouncing baby help file with a .hlp extension. The remainder of MakeHelp.bat simply copies this file (and your contents file) to the appropriate target directories. Be sure that you distribute these files with your application.

Testing Help Projects

The next section shows how to call on the Windows help system from your applications. However, it is often useful to be sure that your help file is behaving as expected before you integrate it with your application.

Help Workshop can be a great help when you test your help file, and you don't need to change the source code in your application and rebuild each time.

From the Test menu of the Help Workshop, you can test the contents file for your help project, send a macro to WinHelp, or use a graphical interface to make calls to the WinHelp API directly. In addition, you can close all of the help windows that are left hanging around with a single menu command.

Share ThisShare This

Informit Network