| Click here to support our advertisers

SOFTWARE FOR SALE
BOOKS FOR SALE
SEARCH CENTRAL
JOB BANK
CLASSIFIEDS
DIRECTORIES
REFERENCE Online Library
LEARNING CENTER
JOURNAL
NEWS CENTRAL
DOWNLOADS
COMMUNITY
CALENDAR
ABOUT US
Journal:
Get the weekly email highlights from the most popular journal for developers! Current issue
> developer.com developerdirect.com htmlgoodies.com javagoodies.com jars.com intranetjournal.com javascripts.com | All Categories : C/C++ vcg23.htm Understanding How Visual C++ and WinHelp Interact Using AppWizard's Automatic Help Facility Creating Rich Text Format Files for Help Systems Adding Instructions to the WinHelp Engine Including Graphic Objects in Your WinHelp File Compiling .RTF Files to Create WinHelp .HLP Files Creating a Project File Using Microsoft Help Workshop to Compile Your WinHelp .RTF File Using WinHelp Office 95 and RoboHELP 95 RoboHELP 95 SmartHelp OLE Control WinHelp Video Kit Moving to WinHelp '95 Kit WinHelp HyperViewer WinHelp Tool Kit Mastering WinHelp Creating Help Files from Your Application Manual Using Doc-To-Help to Create Help Files for Database Applications Organizing Your Manual to Optimize Help File Conversion Creating the Help File from the Source Document Help Project Files and the Compilation Process Including Graphic Images in Help Files Assigning Help File and Context ID Numbers to Objects Calling the WinHelp() Function with Visual C++ Code Summary # - 23 - Creating Help Files for Database Applications Users of Windows expect and deserve context-sensitive online help for all their Windows applications. All but the simplest Visual C++ applications need a custom Windows help file that lets users press F1 to obtain context-sensitive help for field entries, click a toolbar button to obtain help for a specific button, or choose Help | Contents to select a topic from the help system's opening window. No matter how much or how little written documentation you supply with your database application, few users will take the time to read the documentation before they begin to use the application. This is especially true for decision-support applications that you design for supervisory and management personnel. Your Visual C++ applications should be sufficiently intuitive in their operation such that all but the Windows neophyte can take full advantage of their features without employing online help. In reality, however, few Windows applications of any significance are fully comprehensible to the first-time user. Therefore, you need to create Windows help files to make sure that users employ all the features of your application and use the features in the way you intended. If you develop a database application to a written specification, the contract undoubtedly stipulates that comprehensive printed documentation is to accompany the production version of the application. Therefore, this chapter is oriented toward converting the text and graphics of your printed documentation to a help file for the application. Making your documentation do "double duty" as a help file saves time and expense. This chapter is designed to supplement, not replace, the "Creating Help Files: Help Compiler" chapter in the Programming Tools for Windows manual that comes with Visual C++ 1.5x, the Help Compiler Guide included with Visual C++ 2.x, or the Help Author's Guide included with Visual C++ 4's Help Workshop program. In addition, programmers who have access to the Office Developer's Kit can refer to the Help Compiler Guide supplied with that product. Chapter 22, "Documenting Your Database Applications," taught you how to document the objects in your database application and prepare a data dictionary. This chapter shows you how to use several commercial software products. The non-Microsoft products described are Blue Sky Software's WinHelp Office 95, which is a number of useful products packaged together, and WexTech Systems, Inc.'s Doc-To-Help, which is used to convert your Word for Windows documentation files into a full-fledged, professional Windows help system. Often help files are developed by people other than the programmer. This usually means that the programmer will be required to set up a system to assist the help file writers in creating the final help file. Visual C++ 4 automatically generates shell help files. This is fine if the programmer is the person who is developing the help files. If not, you might need to set up a system such as the one discussed in the following sections. NOTE It's usually better that someone other than the programmer write the documentation for an application. For example, I have a major Windows GIS application on the market for which I didn't write the documentation. Often the programmer isn't the best person to write the manuals and online help. Programmers often make too many assumptions about the user's ability. Furthermore, good programmers aren't always good writers. In some organizations, the responsibility for documentation is assigned to the customer support department. They work with the product and the customers and often know which areas are the weakest and need improvement. ### Understanding How Visual C++ and WinHelp Interact The help file display features of Windows are commonly referred to as the WinHelp engine. The Windows 95 help engine is quite powerful. NOTE Windows 95 has a very powerful and flexible help engine. This help engine has been migrated to other Windows platforms (Windows NT, for example) and will continue to be expanded upon in the future. WINHELP.EXE is the Windows application in your \WINDOWS directory that implements the help system. Under the 32-bit versions of Windows (Windows 95 and Windows NT), the file is named WINHLP32.EXE. Under Windows 95, WINHELP.EXE is a stub program that calls WINHLP32.EXE. Visual C++ includes features that let you assign individual help windows to forms and controls to create context-sensitive help. The interface between your Visual C++ application and your WinHelp .HLP file(s) is comprised of the following two basic elements: The APPNAME.HLP file is the master WinHelp file for your application. Most applications use a single help file, but you can specify different help files if necessary by calling the WinHelp engine directly. The context ID number (long) corresponds to a help context string embedded in your WinHelp file. You add entries to the [MAP] section of your help project (.HPJ) file to assign context ID numbers to the help context strings. Context ID numbers are the key to creating context-sensitive help. You assign context ID numbers as the HelpContextID property of forms and controls. You also can set the current context ID value with a [FormName]![ControlName].HelpContextID = lngContextID statement. The following sections describe how to create WinHelp files and how to assign context IDs to topics in order to create context-sensitive help. NOTE Making use of all the features that the WinHelp engine offers is beyond the scope of this book. Microsoft's Help Authoring Guide is available for downloading as HAG.ZIP in .HLP format from the Windows Users Group forum (GO WUGNET). The Help Authoring Guide also is included on the Microsoft Developer Network (MSDN) CD-ROMs. #### Using AppWizard's Automatic Help Facility Programmers who use AppWizard to create their applications have the option of including basic context-sensitive help. Figure 23.1 shows AppWizard's graphical programmer interface, which shows that when you add context-sensitive help, the Help menu is added automatically. Figure 23.1. Visual C++ 4's AppWizard, including context-sensitive help. NOTE Figure 23.1 shows Visual C++ 4's AppWizard, which is virtually identical to the one in Visual C++ 2.x. The programmer interface of Visual C++ 1.5x is different from the one in Visual C++ 2.x, but the help files that AppWizard creates are virtually identical to those created using later versions of Visual C++. NOTE It's easy to convert an application's help file that was created with the 16-bit versions of Visual C++ (1.5x in particular) to 32-bit versions of Visual C++ (2.x and 4.x in particular). The final help file is actually created as a separate step outside of Visual Workbench using a batch file supplied with Visual C++ when using versions prior to Visual C++ 4.0. With Visual C++ 4's Developer Studio, when a help file is added to the project, Developer Studio correctly calls the help compiler and creates the desired help file. When Visual C++ creates the shell for your application's help file, this shell resides in a subdirectory located in the project's directory. This subdirectory is called HLP and contains one or two .RTF files and a number of bitmap files (usually about 20 to 25) for such objects as toolbar buttons. Figure 23.2 shows a typical HLP directory. Figure 23.2. The files created by AppWizard in the HLP subdirectory. NOTE Visual C++ 4 automatically creates help files (by executing the MakeHelp.Bat file) as part of the project build. You don't need to manually execute MakeHelp.Bat if you're using Visual C++ 4 and have used AppWizard to create your application with help features. Of course, if you want to manually compile the help files using MakeHelp.Bat, you can do so. The two .RTF files are AfxCore.rtf, which contains the main help for the application. This file is always present and is the main file from which the application's .HLP file will be created. AfxPrint.rtf, which contains help that is specific to printing. If you don't include printing support (see Figure 23.1), AppWizard doesn't create this file. PROJECT.HPJ is the help project file. .HPJ files are discussed later in this chapter. Not all the help support is located in the HLP subdirectory. The project's main directory contains the batch file used to generate WinHelp files. MakeHelp.Bat, shown in Listing 23.1, actually calls the help compiler and generates the help file. This batch file is usually executed from a command-line prompt (in a DOS window), but you can create an icon or a menu shortcut from Visual C++'s Tools menu for MakeHelp.Bat. This filename never changes, so making a shortcut for Visual C++'s Tools menu would be effective for all AppWizard-created projects. NOTE Generally, if you delegate the help file authoring, whoever was doing the help file development would use the MakeHelp.Bat file to create the help files rather than Visual C++'s Developer Studio. Listing 23.1. A typical MakeHelp.Bat file.
>     @echo off

>     REM -- First make map file from Microsoft Visual C++ generated resource.h

>     echo // MakeHelp.Bat generated Help Map file.

>         Used by HELP FILE DEMO.HPJ. >"hlp\Help File Demo.hm"

>     echo. >>"hlp\Help File Demo.hm"

>     echo // Commands (ID_* and IDM_*) >>"hlp\Help File Demo.hm"

>     makehm ID_,HID_,0x10000 IDM_,HIDM_,0x10000 resource.h >>"hlp\Help File Demo.hm"

>     echo. >>"hlp\Help File Demo.hm"

>     echo // Prompts (IDP_*) >>"hlp\Help File Demo.hm"

>     makehm IDP_,HIDP_,0x30000 resource.h >>"hlp\Help File Demo.hm"

>     echo. >>"hlp\Help File Demo.hm"

>     echo // Resources (IDR_*) >>"hlp\Help File Demo.hm"

>     makehm IDR_,HIDR_,0x20000 resource.h >>"hlp\Help File Demo.hm"

>     echo. >>"hlp\Help File Demo.hm"

>     echo // Dialogs (IDD_*) >>"hlp\Help File Demo.hm"

>     makehm IDD_,HIDD_,0x20000 resource.h >>"hlp\Help File Demo.hm"

>     echo. >>"hlp\Help File Demo.hm"

>     echo // Frame Controls (IDW_*) >>"hlp\Help File Demo.hm"

>     makehm IDW_,HIDW_,0x50000 resource.h >>"hlp\Help File Demo.hm"

>     REM -- Make help for Project HELP FILE DEMO

>     echo Building Win32 Help files

>     start /wait hcrtf -x "hlp\Help File Demo.hpj"

>     echo.

>     if exist Debug\nul copy "hlp\Help File Demo.hlp" Debug

>     if exist Debug\nul copy "hlp\Help File Demo.cnt" Debug

>     if exist Release\nul copy "hlp\Help File Demo.hlp" Release

>     if exist Release\nul copy "hlp\Help File Demo.cnt" Release

>     echo.
> NOTE Visual C++ 2.x's AppWizard might add an EndLocal statement to the end of the MakeHelp.Bat file. This command should cause no problems (even though it isn't currently supported by DOS). Oddly, AppWizard doesn't include an opening SetLocal statement. Visual C++ 4 doesn't add the erroneous EndLocal statement. Instead, it adds an Echo command to the end of MakeHelp.Bat, as Listing 23.1 shows. After you've created your project, you will compile the initial help files when you first build your project. You don't need to make any changes in these files; however, you will find that as supplied by AppWizard, the help files don't provide much help! The AfxCore.rtf file has a number of place markers. These are marked with the characters << and >>. For example, you will need to substitute the application's name wherever the phrase <<AppName>> is found. To do this, simply use a global substitution command in Word for Windows or whichever RTF editor you're using. Any place markers that aren't listed in the help source file are verbose enough that you will readily understand what information needs to be substituted. WARNING The WordPad editor that is part of Windows 95 can't be used to create help files. This is because help file topics are linked to footnotes, and WordPad doesn't support footnotes. You must use a fully functional RTF-enabled editor, such as Word for Windows, to create or modify a help .RTF file. #### Creating Rich Text Format Files for Help Systems A WinHelp .HLP file is a compiled version of a word processing document file saved in Microsoft rich text format (RTF). Rich text format is a page description language used to exchange formatted text between document processing applications. For example, you use .RTF files to transfer Word for Windows files to the Macintosh version of Word. Most Windows word processing applications can save documents as .RTF files. Rich text format is similar in concept to Adobe's PostScript page description language, but .RTF isn't used to print documents. Figure 23.3 shows part of the .RTF version of AfxCore.rtf (the CHAPTR23\Help File Demo\hlp\AfxCore.rtf file) displayed in Notepad's window. Figure 23.4 shows the same file loaded into Word for Windows. Figure 23.3. Part of the AfxCore.rtf WinHelp file in Notepad. Figure 23.4. The same part of the AfxCore.rtf WinHelp file in Word for Windows. The .RTF files that you create include a header that describes the page format, fonts, and styles in use. PostScript files contain a header that serves a similar purpose. An escape character (\) precedes page and character formatting data in .RTF files, and French braces ({}) enclose groups of formatting data and text to which the formatting applies. Most of the header information in Word .RTF files is derived from the template (.DOT file) in use when you write the document. Only a small part of the .RTF file header appears in Figure 23.3; the first few words of the text are highlighted to identify the point where the paragraph starts. #### Adding Instructions to the WinHelp Engine Instructions to the WinHelp engine are embedded in the .RTF file in the form of footnotes designated by footnote symbols, such as $ and #, rather than conventional footnote numbers. Topic titles are designated by $ footnotes. The context strings that uniquely identify a topic to the WinHelp engine use the # symbol. A topic is a help window that is devoted to a single subject. Topics are separated from one another in your word processing document by hard page breaks (usually created using the Ctrl-Enter key combination). Figure 23.5 shows part of a simple help topic from the HELPEX example included with the Windows Help Authoring Guide on the Microsoft Developer's Network CD-ROM. Figure 23.5. Part of the second topic of the HELPEX.RTF file used to create HELPEX.HLP. In Figure 23.5, Help Example Index is the topic title and ctxContents is the help context string for the topic. Hotspots are individual words or blocks of text that are formatted with the double-underline or strikethrough attribute and are followed by a help context string formatted as hidden text. When you click a hotspot, WinHelp jumps to the topic identified by the context string that follows the hotspot text. Figure 23.6 shows the first two help topic windows of HELPEX.HLP. Hotspots appear in green in help windows, so you should avoid using the green color attribute in your help text. Figure 23.6. The first two help topic windows of HELPEX.HLP. #### Including Graphic Objects in Your WinHelp File You can embed or link graphic objects contained in bitmap (.BMP) or vector image (.WMF) files in your WinHelp files. The easiest way to add bitmapped images to your help files is to embed the image in .BMP format in your .DOC or .RTF file using Word. However, large bitmap files usually are handled more efficiently by linking the graphic file to the WinHelp file by using its filename as a reference. Figure 23.7 shows Microsoft's logo as an embedded bitmap. Figure 23.8 shows Microsoft's logo as it appears in the final help file. To embed the bitmap (a bitmap image captured from Word for Windows' toolbar) in the .RTF document, you choose Insert | Picture in Word to display the Picture dialog box and then double-click cmdialog.bmp in the File Name list box. The {bmc cmdialog.bmp} entry below the line of text causes the CMDIALOG.BMP bitmap file to be inserted at the position of the { character. Figure 23.7. A help topic with an embedded bitmap. Figure 23.8. An embedded bitmap of Microsoft's logo in WinHelp. NOTE When you use bitmapped graphics, you might need to include a version of the bitmap file for each type of display resolution that might be employed by users of the help system. The Microsoft multiple-resolution bitmap compiler, MRBC.EXE, lets you create a single bitmap file that supports VGA, SVGA, and 8514 resolutions. It's unlikely that any users of Visual C++ database applications will be using resolutions less than standard VGA, but MRBC.EXE is useful to provide scaleable bitmaps for 640x480 (VGA), 800x600 (SVGA), and 1,024x768 (8514, XGA, or UVGA) display resolutions. It won't be long before 1280x1024 resolutions become common. Your help files should take into account the trend toward higher resolution and more colors. Many Windows database applications still run on "plain vanilla" 16-color VGA systems, but more and more users are converting to 256-color or better systems. When you convert a .BMP file with MRBC.EXE, you substitute .MRB for the .BMP extension when you refer to the file. One of the advantages of using .WMF vector image files in help files is that the Windows metafiles are device-independent. NOTE The term link is used in this chapter to differentiate between embedding a graphics file in the .RTF file and creating a reference to a separate graphics file with {bm? filename.ext} entries in your .RTF file. The ? placeholder determines whether the graphic is placed as a character (bmc), at the left margin (bml), or at the right margin (bmr). When you compile the help file with the WinHelp compiler, the graphic that you link is embedded into the .HLP file you create. (You don't need to supply the .BMP file along with your .HLP file.) You can create hotspots in graphic images that you link to your WinHelp file by using the Hotspot Editor, SHED.EXE, which is included with Visual C++. (You can't add hotspots to bitmaps you embed in WinHelp .RTF files.) NOTE If there is no link to SHED in the Visual C++ 4 folder, you can add one. An alternative is to start SHED from a DOS command prompt window, but this really isn't efficient unless you frequently use a DOS window. The Hotspot Editor creates an .SHG (system hypergraphic) file from .BMP, .DIB (device-independent bitmap), or .WMF files. To add hotspots to a .BMP, .DIB, or .WMF file, follow the next steps. NOTE The bitmap file used in this example is setup.bmp, found in Windows 95's directory. It was copied to the help project folder and saved in SHED as setup.shg. Launch SHED.EXE and choose File | Open from the editor to display the File Open dialog box (which isn't a Windows 95 common dialog box). NOTE Because SHED isn't long-filename-compliant, you will have to select files using their short filenames. Select the directory and filename of the bitmap in the Directories and Files list boxes, and then click the OK button to close the File Open dialog box and display the image. Position the mouse pointer in the upper-left corner of the area that you want to make active as a hotspot. Click and hold the left mouse button, drag the enclosing rectangle to define the hotspot area, and then release the mouse button. With the frame for your hotspot selected (the one with the eight sizing handles), choose Edit | Attributes to display the Attributes dialog box. Alternatively, you can select Attributes by right-clicking in the hotspot area. Enter the context string corresponding to the topic for the hotspot item in the Context String text box. Select Pop-up to create a pop-up window or select Jump to jump to a new topic. Accept the default value, Visible, in the Attribute combo box and the Hotspot ID text box. You can manipulate the position of the enclosing rectangle by changing the entries in the text boxes within the Bounding Box frame. Figure 23.9 shows the typical entries that define the attributes of a hotspot. Figure 23.9. Defining the boundaries and attributes of a hotspot in a hypergraphic (.SHG) file. NOTE All the hotspots in this example were defined as pop-ups. You can also define hotspots as either jumps (which would jump to a certain topic) or as a WinHelp macro that would be run when the hotspot was selected. Click the OK button to assign the attributes to the hotspot. Add more hotspots as needed by repeating steps 3 and 4. When you've completed the definitions of the hotspots you want, choose File | Save As and save your file with the same name as the original bitmap but with an .SHG extension to indicate that the bitmap file is now a hypergraphic file. Close SHED.EXE. If you've used the .BMP extension to refer to the bitmap in your .RTF file, change the file extension to .SHG. (You also might need to change the reference in the [BITMAPS] section of the project file if the bitmaps are in folders other than the help file's project directory. This is discussed in the next section.) Add new topics to your WinHelp file for the pop-up or conventional help windows that appear when you click the hotspots. Each topic has a context string that corresponds to the context string you added during the editing process. Figure 23.10 shows entries for the pop-up window that opens when you click the mouse hotspot on the bitmap. Figure 23.10. Pop-up help window topics for hotspots of the set up bitmap image. After you compile your WinHelp .RTF file to a .HLP file, clicking the hotspot displays the pop-up window that has a context string that corresponds to the context string you assigned as the hotspot's attribute. (Compiling .RTF to .HLP files is the subject of the next section.) Figure 23.11 shows the pop-up window that appears when you click the area within the dashed lines surrounding the image of the Microsoft mouse. The dashed lines appear because Visible was selected as the attribute for the hotspot regions. (Normally you choose Invisible, so the dashed lines don't appear.) Figure 23.11. The pop-up window displayed when you click the picture of the mouse in the image. NOTE One of the advantages of using SHED.EXE is that the Hotspot Editor compresses .BMP files. For example, setup.bmp requires 38,462 bytes of storage, whereas setup.shg occupies only 36,959 bytes and has four jumps defined. #### Compiling .RTF Files to Create WinHelp .HLP Files Creating the final WinHelp .HLP file from your .RTF file and any graphics that are referenced in the .RTF file is a three-step process. Create a project file that provides information to the help compiler on the files that constitute your help file and assigns help context ID values to the help context string. If your help file was originally created with Visual C++, this file has already been created for you. Use the Microsoft Help Workshop program (there should be an icon for it in the Visual C++ program folder) and load the help project's .HPJ file. Click the compile button on the toolbar or select File | Compile to compile your help menu. Prior to the compilation process, the dialog box shown in Figure 23.12 is displayed to allow you to select options for the help file. Figure 23.12. Microsoft Help Workshop's compile options dialog box. Test your .HLP file to make sure it conforms to your expectations. If you select the Automatically display Help file option, your help file will be loaded into WinHelp when the compilation is complete. NOTE Even though the HELPEX sample help file that is supplied on the MSDN CD is intended to be compiled with the DOS-based help compilers, using Microsoft Help Workshop will work, with only minor warnings about improper labels. It will create a valid help file. The following three sections describe the preceding steps in detail. ##### Creating a Project File Help project files, which are usually named APPNAME.HPJ, are similar in concept to Visual C++ makefiles or project files. Listing 23.2 shows the contents of the project file for the Help Example help file, HELPEX.HPJ. Listing 23.2. Sections and entries in the HELPEX.HPJ help project file (after loading into Microsoft Help Workshop).
>     ; This file is maintained by HCW. Do not modify this file directly.

>     [OPTIONS]

>     HCW=0

>     ; error message:

>     ;

>     ;    R1023: Keyword(s) defined without title in page 59

>     ;           of file helpex.rtf

>     ;

>     ; This message indicates that a topic will be listed in

>     ; the Search Topics Found box as ">>Untitled Topic<<"

>     COMPRESS=60 Hall Zeck

>     LCID=0x409 0x0 0x0 ;English (United States)

>     REPORT=Yes

>     TITLE=Help Example

>     HLP=.\helpex.hlp

>     [FILES]

>     helpex.rtf  ; main topics

>     [MAP]

>     #include <helpids.h>
> CAUTION Once you've loaded an .HPJ file into Microsoft Help Workshop, you shouldn't edit the file by hand. Instead, use Microsoft Help Workshop to make changes to the help project file. Help project files are text files that are organized into sections and are similar in structure to Windows .INI files. Table 23.1 lists the most commonly used sections of a help project file, states whether the section is required in the file, and briefly describes the section's purpose. Keywords for entries in the [OPTIONS] section also appear. Table 23.1. The sections of a help project (.HPJ) file.
> Section of .HPJ File | Section Required? | Description
> [OPTIONS] | No (but usually present) | Defines the options that control the WinHelp compilation process. Some of the more common option entries include the following:
> |  | ROOT=d:\path | Defines the path to your help source files.
> |  | CONTENTS= | Sets the context
> |  | ContextString | string for the index topic with the Windows 3.1 Help compiler, HC31.EXE.
> |  | TITLE= | Sets the title for
> |  | AppName Help | the WinHelp file, which appears in the help window's title bar.
> |  | ICON= IconFile.ICO | Sets the icon that is displayed when the help window is minimized.
> |  | COMPRESS=0|FALSE | Controls file compression. 0, or FALSE, means "do not compress files." 1, or TRUE, compresses the file. Compressing .HLP files saves disk space at the expense of speed in displaying help windows (due to the time required to decompress the file). HC31.EXE supports varying degrees of compression.
> |  | WARNING=3 | Determines what errors are reported. 0 through 3 control the level of error reporting. 0 = no error reports, 1 = most-severe warnings, 2 = intermediate warning level, and 3 = report all warnings.
> |  | REPORT=1|ON | Determines whether progress reports of the compilation are provided. 1, or ON, = report progress of compile. 0, or OFF, = no report.
> [FILES] | Yes | Specifies the help source files included in the compilation.
> [BUILD] | No | Specifies topics to include in or exclude from the compiled file.
> [BUILDTAGS] | No (yes if [BUILD] is specified) | Names valid build tags, allowing the selection of topics to be compiled within a file.
> [CONFIG] | Only if DLL functions are called | Registers custom DLLs that have functions that are called by WinHelp RegisterRoutine macros.
> [BITMAPS] | No | Specifies bitmap or .WMF files that are used in the compilation and not embedded in your WinHelp document. This section isn't required if you used the ROOT= entry in the [OPTIONS] section to specify the path to the referenced bitmap files.
> [MAP] | No | Associates context strings with context ID numbers. You need a map section to use the Context ID property of Access forms and control objects.
> [ALIAS] | No | Lets you assign more than one context string to a subject.
> [WINDOWS] | No | Describes the main WinHelp window and any secondary window types in the help file.
> [BAGGAGE] | No | Names any additional data files that are to be incorporated within the WinHelp file.
> ##### Using Microsoft Help Workshop to Compile Your WinHelp .RTF File Microsoft Help Workshop is a DOS application that converts .RTF files to the format required by WinHelp .HLP files, incorporates graphics files, and creates the required look-up tables for help context strings and context IDs. Select the Windows 95 Help icon (or whatever icon is assigned to the help compiler) to start Microsoft Help Workshop. Load the help project file either by selecting File | Open or by selecting from the MRU file list if the project help file was previously opened. Figure 23.13 shows the results of compiling the Helpex.hpj file using Microsoft Help Workshop. A number of errors were flagged in the compilation stage, but the help file was generally usable for testing purposes. (However, you wouldn't want to distribute a help file with these errors.) Figure 23.13. Compiling HELPEX.HPJ in Microsoft Help Workshop. TIP You can find the cause of an error (and suggested fixes) by searching the Microsoft Help Workshop help file for the error number. In Figure 23.13, the help error message HC1003 is highlighted, and the appropriate Help Author's Guide topic is displayed. Microsoft Help Workshop can run in a noninteractive mode. This mode isn't documented by Microsoft, and programmers shouldn't need it directly. Microsoft Help Workshop is called in noninteractive mode by Visual C++ 4 when a project's help file is being rebuilt. ### Using WinHelp Office 95 and RoboHELP 95 One of the newest and most extensive products to assist programmers in developing help files is from Blue Sky Software. This section looks at this suite of products, which form a comprehensive tool for Windows software developers who are documenting their products. WinHelp Office 95 is available at an introductory price of $599. The core of WinHelp Office 95 is the RoboHELP help development engine. WinHelp Office 95 includes the following tools: RoboHELP 95, a product to help you develop help files SmartHelp OLE control, an OLE control to add help facilities to application dialog boxes WinHelp Video Kit, which provides facilities to add video to help files The Moving to WinHelp '95 Kit, a set of applications that eases the migration to WinHelp Office 95 WinHelp HyperViewer, a utility that gives your Windows 3.x files the look and feel of Windows 95 help files WinHelp Tool Kit, a set of helper utilities Mastering WinHelp, a videotape that helps you learn the basics of creating help files The following sections take a quick look at each of these tools. #### RoboHELP 95 RoboHELP 95 turns Microsoft Word 7 for Windows 95 and 32-bit Word 6.0 and 7.0 for Windows NT into hypertext authoring tools. RoboHELP 95 includes both 32-bit and 16-bit versions of RoboHELP, thereby providing support for all versions of Microsoft Word. RoboHELP includes an Enhanced Hotspot Editor, a screen capture utility, and much more. RoboHELP 95 is a 32-bit version of RoboHELP that turns Microsoft Word 7 for Windows 95 and Word 6 for Windows NT into high-performance hypertext authoring tools. A 16-bit version of RoboHELP is included with RoboHELP 95 to provide support for Microsoft Word 6 and Word 2 for Windows 3.x. RoboHELP guides you through the entire process of creating help systems and electronic Hypertext documents, from standard help features such as jumps, topics, and pop-ups to advanced features such as macros, secondary windows, and colors. RoboHELP 95 supports all the new Windows 95 help features. RoboHELP automatically converts existing documentation into a help system or vice versa. You also can import existing help systems, graphics, and documents. RoboHELP 95 includes a variety of new and improved features specifically designed to streamline the process of creating help systems for Windows 95 and Windows NT: An enhanced tool palette New Windows 95 templates A Contents tab composer Easy creation of a-links and k-links New help macro support More support for Visual Basic Multimedia support Advanced graphic support Authorable button support: shortcuts and see also buttons Easy creation of What's This? context-sensitive help SmartHelp OLE control #### SmartHelp OLE Control The new SmartHelp OLE control included in RoboHELP 95 eliminates the need to program context-sensitive help into any application developed with Visual Basic 4.0, Visual C++ 4.0, Access 95, Visual FoxPro 3.0, or other environments that support the OLE control standard. #### WinHelp Video Kit The WinHelp Video Kit provides everything you need to integrate video and sound into Windows help systems and to create "live" video product tutorials. The WinHelp Video Kit includes a Software Video Camera, a Video Wizard, a Video Tester, a Video Player, and Video for Windows Runtime. #### Moving to WinHelp '95 Kit The Moving to WinHelp '95 Kit provides you with the tools to quickly convert Windows 3.x help systems to Windows 95 help systems. It also comes with the first book solely dedicated to Windows 95 help. This kit is intended to make the transition to Windows 95 help fast and easy. #### WinHelp HyperViewer WinHelp HyperViewer lets you give Windows 3.x help systems the look and feel of Windows 95. WinHelp HyperViewer features a powerful full-text search, multiple-topic printing, and an expandable, collapsible hypertext view of the entire help system. #### WinHelp Tool Kit The WinHelp Tool Kit is a collection of powerful tools. It includes Help-To-Word, Help-To-Source, WinHelp Inspector, WinHelp BugHunter, WinHelp Graphics Locator, WinHelp Graphics Library, and WinHelp Internet Access. The following list describes some of these tools. WARNING The WinHelp Tool Kit includes tools that "decompile" Windows help files into Word for Windows .DOC and .RTF files. This functionality is quite valuable when you no longer have access to the original source files, for example. However, you should be careful not to violate copyright laws by decompiling help files for products for which you have no right to do so. Help-To-Word decompiles Windows 3.1x help files into Word for Windows .DOC files. The resulting files are formatted using the styles that WinHelp used. All jumps and pop-ups are marked in green so that they can be found easily. Help-To-Word doesn't convert Windows 95 or Windows NT help files; use Help-To-Source to convert these types of files. This process is useful when you need to create printed manuals from your help files using the formatting that WinHelp uses. Help-To-Source decompiles .HLP format help files (all versions of Windows, including Windows 95 and Windows NT) into .RTF and .HPJ files. The resulting files will contain all topics, jumps, pop-ups, graphics, hypertext links, and other characteristics that the original file had. WinHelp Inspector lets you quickly inspect any help system. Most of the information provided by the WinHelp Inspector normally isn't available without the source files. WinHelp Inspector displays information such as the startup macros, fonts, and DLLs used, the compression, the copyright notice, topic titles, search keywords, and the name, date, and size of the help system. WinHelp BugHunter is used to display all calls made by running applications to any Windows help system (either Windows 95 or Windows 3.x). WinHelp BugHunter is valuable in resolving any broken or incorrect context-sensitive help links between the application and its help system. WinHelp Graphics Locator assists you in searching for graphics (.SHG, .WMF, .MRB, .BMP, .ICO, and .CUR files) and other files in a specific directory, drive, or even across multiple drives. You can also preview these graphics and copy them to their help project directory. The WinHelp Graphics Locator displays information such as the number of colors in the selected graphic, the width and height of the graphic, and so on. WinHelp Graphics Library lets you select graphics such as bullets, buttons, and pictures from the WinHelp Graphics Library and easily integrate them into your help file. WinHelp Internet Access includes tools to integrate your help files with Internet access. Blue Sky Software is a Netscape development partner, and with the new WinHelp Internet Access, you can add Internet access to any Windows help system via Netscape, Mosaic, and Microsoft Internet Explorer. WinHelp Internet Access opens the door to interactive Windows help by integrating Windows help with the World Wide Web (WWW). Help users can jump from Windows help to any World Wide Web site via the Web Browser (Netscape, Mosaic, and Microsoft Internet Explorer) installed on their desktop. With a click of the mouse, help users can also download any file from the Internet or send e-mail. WinHelp Internet Access includes the following: Internet Access Wizard, which automatically adds the WinHelp Internet Access functionality to any Windows help project. The WinHelp Internet Access sample help file, which includes full source code for Internet access commands to many Internet locations and macro commands for downloading files from the Internet. These sample macro commands are available to help you add Internet access to your Windows help systems. #### Mastering WinHelp With the Mastering WinHelp video, you can become productive immediately and create professional help systems with a minimum amount of effort. Mastering WinHelp also includes advanced tips for experienced users and a WinHelp sample disk for Windows 95. ### Creating Help Files from Your Application Manual The process of manually creating help files for Visual C++ applications is thoroughly documented in Microsoft's Help Compiler User's Guide and the Help Author's Guide. Today, few help-file authors write help files in the manner described in the Help Compiler User's Guide. Third-party help-file authoring applications, such as Doc-To-Help by WexTech Systems Inc. (New York) and RoboHELP 95 by Blue Sky Software (San Diego), speed the organization and writing of help files. This book assumes that most database developers possess the writing skills that are needed to prepare a better-than-adequate manual for the application. Developers who aren't authors by nature usually employ technical writers to prepare the required written documentation. Therefore, this chapter is oriented toward the design and use of text from the application manual as the basis for your application's help file(s). Almost without exception, Word for Windows is the preferred application for creating the rich text format (.RTF) files needed by the help compiler that you use to create the final WinHelp (.HLP) file. All commercial help-file generation applications are based on Word for Windows. #### Using Doc-To-Help to Create Help Files for Database Applications Doc-To-Help 2.0, which works with Word for Windows 95, allows users to create and distribute commercial-quality printed documentation and sophisticated Windows 95, 3.1, and 3.0 help files from a single source without compromise in either medium or any platform. Doc-To-Help 2.0 includes the following: 32-bit architecture with long filename and UNC support Automatic and nearly instantaneous generation of contents (.CNT) files Authorable buttons Easy inclusion of multimedia elements in Help files Users will also find updated versions of the Doc-To-Help Hyperformance Tools, providing Doc-To-Help Navigator, video support, and watermark support for 32-bit WinHelp. The Microsoft Windows 95, 3.1, and 3.0 help compilers are included in this package. New to Doc-To-Help 2.0 are Topic Types. Using this feature, help authors can mark topics as conceptual, procedural, or context-sensitive. Doc-To-Help makes sure that the topics appear automatically in the correct Help window and with proper formatting. Doc-To-Help 2.0 also offers a "smart" contents tab feature, which allows the help author to place the Doc-To-Help Navigator in the Help topics contents tab. This gives help authors greater flexibility in creating and controlling the contents tab's hierarchical outline. Doc-To-Help consists of the following components: A collection of Word for Windows template (.DOT) files for producing manuals that will be copied to 8 1/2- by 11-inch or 7- by 9-inch paper, as well as a special template (D2H_HELP.DOT) that you use when you produce WinHelp files from the text of your manual. The templates make extensive use of Word Basic code to provide supplemental features, such as semiautomatic indexing. A DLL that is used to convert large bitmap files for incorporation into help files. Licensed copies of the Microsoft Help Compiler, HCP.EXE, the protected-mode version of HC31.EXE, which lets you compile larger help files than are possible with HC31.EXE. Generally, you will want to use the Microsoft Help Workshop program that was described earlier. A set of tutorial and sample files from which many of the figures in this section are derived. A 300-page application manual created with Doc-To-Help. Doc-To-Help has a preset collection of styles that are likely to meet your needs if your client or firm hasn't already established a set of graphic-design standards. You can alter these basic styles to suit others' requirements or your own taste in layout and typography. ##### Organizing Your Manual to Optimize Help File Conversion One of the advantages that authors of application manuals have over authors of developers' guides for software is that the application itself provides the organizational framework for your work. The structure of your application's manual is dictated by the relationship between the forms that constitute the user interface of your application. Thus, a database application manual consists of the following major sections or topics: A table of contents (TOC), which lays the groundwork for the window that appears when the user chooses Help | Contents. The level-1 heading, called the supertitle, appears as the heading of the Contents window. An overview of the application as a whole, including a brief description of the purpose of the application and the underlying database(s). The overview corresponds to the main switchboard form or the start-up form of your application. This window or series of windows appears when the user presses the F1 key or clicks the Help button of a toolbar with the opening form displayed. The overview is a level-2 heading. Instructions on installing the application from the distribution diskettes. You don't include this topic in the help file, because the user can't read the help file until he or she completes the installation. One chapter for each main form of your application. For example, an accounting package would have individual chapters for the General Ledger, Accounts Receivable, Accounts Payable, Payroll, Inventory, and Job Cost Accounting modules, each of which is likely to have its own main form. This help window appears when the user presses F1 or clicks the Help button when the control with the focus doesn't have a corresponding subtopic. Chapter headings are level 2 and appear in the Help Contents window. Topics within each chapter that explain the next layer down in the hierarchy of forms. Using the Accounts Receivable module of the accounting system as an example, topics might include Invoice Creation, Printing Invoices, Receiving Payments, and Aging the Accounts Receivable. Topic names appear in green with underscores and usually are identified by larger, bold typefaces. Topics use level-3 headings. Subtopics within each chapter that explain how to enter data in text boxes and how to use any subsidiary forms that are at the next level of the hierarchy. You open subtopic help windows from the main topic (chapter) help windows or by pressing F1 when a control object is assigned a subtopic window. Subtopic names have the same format as topic names but use a font that is one or two points smaller than that used for topic names. Subtopic headings are level 4. A glossary of potentially unfamiliar terms or familiar terms that are used in an unusual context or have an uncommon meaning in the manual. Doc-To-Help converts glossary entries into pop-up windows that you open by clicking highlighted text with dashed underscores. Index entries that create the entries that users see in the list box when they choose Help | Search. Figure 23.14 shows a sample Doc-To-Help document, D2HSETUP.DOC, in Word for Windows' outline mode. This help document has three heading levels; thus, D2HSETUP.DOC typifies the structure of help files for Windows applications. Writing your manual with one of Doc-To-Help's standard templates attached simplifies the help-file conversion process. Alternatively, you can convert existing manuals to Doc-To-Help's format by importing the styles contained in the standard Doc-To-Help template. The graphics shown in D2HSETUP.DOC import directly into your help file. Figure 23.14. A Doc-To-Help manual shown in Word for Windows' outline mode. NOTE Don't forget that Doc-To-Help has a toolbar that may be used in Word for Windows when you're creating or modifying a help file. A programmer can save a great deal of time and effort by using toolbars. ##### Creating the Help File from the Source Document After you've completed and printed proof copies of your application manual, you convert the manual to a Microsoft rich text format (.RTF) file. Rich text format files are text files that include embedded page-, line-, and character-formatting instructions. Doc-To-Help adds several menu choices to Word for Windows' Tools and Format menus that display special-purpose dialog boxes in which you select options for converting your manual to the required .RTF file and compiling the .RTF file to a help file. Figure 23.15 shows the dialog box for the conversion step, and Figure 23.16 shows the dialog box for the compilation step. When you click the OK button of the Reformat As Help File dialog box (shown in Figure 23.15), Doc-To-Help creates an .RTF version of the Word .DOC file and then displays the Compile dialog box. When you click the OK button of the Compile dialog box (shown in Figure 23.16), Doc-To-Help creates a help project file (.HPJ) and runs the help compiler to create the .HLP file. Figure 23.15. The Doc-To-Help Reformat as Help File dialog box. Figure 23.16. The Doc-To-Help Compile dialog box. ##### Help Project Files and the Compilation Process The help project file (.HPJ) tells the compiler the names and locations of the .RTF and bitmap (.BMP) files to be included in the .HLP file. The structure of .HPJ files is similar to a Windows initialization file such as MSACCESS.INI and is related to the structure of the .MAK files used by Visual Basic and C compilers. Headings are enclosed in square brackets and are followed by related entries. Here is a truncated version of the D2HSETUP.HPJ file that is automatically generated by Doc-To-Help and that creates D2HSETUP.HLP:
>     [OPTIONS]

>     INDEX=HelpContents1

>     ROOT=C:\DOC2HELP

>     COMPRESS=FALSE

>     TITLE=Doc-To-Help Introduction

>     [FILES]

>     C:\DOC2HELP\D2HSETUP.RTF

>     [MAP]

>     HelpContents1         1   ; Help Contents

>     Overview.2            2   ; Overview

>     HowDoc.To.HelpWorks.3 3   ; How Doc-To-Help Works

>     AnExample.4           4   ; An Example

>     You.reInControl.5     5   ; You're In Control

>     [BITMAPS]

>     C:\DOC2HELP\HELP0003.BMP

>     C:\DOC2HELP\HELP0001.BMP
> NOTE Unless you specify otherwise, the names of the .RTF, .HPJ, and .HLP files are the same as the names of the source .DOC file. The extensions change to designate the type of file. The preceding example of a help project file includes only sections and entries that are required to compile a simple help file with five help topics and two bitmaps. The .HPJ files for complex .HLP files become quite lengthy. Compiling a large help file can take several minutes on a slow computer, especially one that doesn't have enough RAM. After compilation, the Contents window of D2HSETUP.HLP appears as shown in Figure 23.17. Figure 23.17. The Contents window of D2HSETUP.HLP. ### Including Graphic Images in Help Files You can include large bitmap files, such as images captured from the forms of your application, in both your manual and the help file. The Hotspot Editor (SHED.EXE) included with Visual C++ lets you assign help context strings to control objects on your form. When the user clicks a control object, the window that explains the purpose of the control object appears. Figure 23.18 shows how to create a pop-up window that displays information about the Command Line edit control in the sample dialog box. Figure 23.18. Creating a pop-up window. If you use SHED.EXE to assign help context strings to the buttons and other dialog box controls of the Run dialog box that is shown in the help file, you can cause a jump to the window that deals with each of these subjects when the user clicks the control in the Run dialog box. Figure 23.19 shows the bitmap illustration from Figure 23.18 opened in SHED.EXE. You drag the mouse pointer to define a rectangular area that serves as the hotspot. Then you assign the help context string of the help topic you want to jump to. When the user double-clicks the area defined as the hotspot, the command line's help topic appears. Figure 23.19. Adding a help context string to a bitmap with the Hotspot Editor. ### Assigning Help File and Context ID Numbers to Objects Each topic window requires a help context string that the WinHelp engine (WINHELP.EXE) uses to create a jump from the Contents window to the topic window. Help context strings are footnotes that are identified by the pound symbol (#). If you want a specific help topic to appear when the user presses the F1 key, a feature called context-sensitive help, you need to assign a unique help context ID number to each of the topic and subtopic windows of your help file. You add help entries that contain the context string and the associated help context ID number as entries in the [MAP] section of your .HPJ file. After you create the final version of your help file, you enter the context ID number of the topic that corresponds to the form or control object in your application as the HelpContextID property of the object. To test your help, run your application under Windows. NOTE If you assign values to the HelpContextID property of control objects on your form, the help topic window corresponding to the HelpContextID value of the control object with the focus appears when the user presses the F1 key. If you assign a value to the HelpContextID property of the control object that receives the focus when you open the form (the first object in the tab order), F1 doesn't open the help topic window assigned to the form itself. If you want F1 to open a help topic window for the form, make sure that you assign the form's help topic ContextID value to the ContextID value of the first control object in the tab order. ### Calling the WinHelp() Function with Visual C++ Code With C Windows programs, you can call the WinHelp() function to display the application's help file. If you're using Windows applications designed with AppWizard, you're better off calling the MFC CWinApp::WinHelp() function. With this function, you need to specify only the command and any additional data that might be necessary. To control the action of the WinHelp engine with Visual C++ code, you call the CWinApp::WinHelp() function when you need to change a context ID value. The syntax of the CWinApp::WinHelp() function call, which calls ::WinHelp() (the sole help function contained in the USER.EXE DLL), is as follows:
>     virtual void CWinApp::WinHelp(DWORD dwData, UINT fuCommand);
> Here is the Windows WinHelp() function's prototype:
>     BOOL WinHelp(HWND hWnd, LPCSTR lpszHelpFile, UINT fuCommand, DWORD dwData);
> The Windows WinHelp() function returns a BOOL value which, if nonzero, indicates that the function was successful. The arguments of the WinHelp() function are explained in the following list: hWnd is a Windows handle (code number or integer) to the window that is active when the WinHelp() function is called with the F1 key. The hWnd property of a form or control provides this 16-bit handle. lpszHelpFile is the name of the WinHelp file, including the .HLP extension. fuCommand is an integer value that specifies the action that the function is to perform. Table 23.2 describes the fuCommand constant values. dwData is a long integer argument. Table 23.2 describes how the data of the dwData argument changes with the value of fuCommand. Table 23.2. WinHelp fuCommand constant values and corresponding actions.
> fuCommand Constant | Value | Description
> HELP_CONTEXT | 1 | Causes a specific help topic, identified by a long integer specified as the dwData argument, to be displayed.
> HELP_QUIT | 2 | Notifies WinHelp that the specified help file is no longer in use and can be closed. The dwData argument is ignored.
> HELP_INDEX | 3 | Displays the index of the specified WinHelp file, as designated by the author. The dwData argument is ignored.
> HELP_HELPONHELP | 4 | Displays help for using the WinHelp application itself. The dwData argument is ignored.
> HELP_SETINDEX | 5 | Sets the context number specified by the dwData argument, a long integer, as the current index for the specified WinHelp file.
> HELP_KEY | 257 | Displays the first corresponding topic found in a search for the keyword specified by the dwData argument—in this case, a string variable.
> HELP_MULTIKEY | 513 | Displays help for a keyword found in an alternative keyword table. The dwData argument is a data structure (user-defined data type) containing the size of the string, the letter of the alternative table, and the keyword string.
> Listing 23.3 shows the additions that you make to the Declarations section of your module to take advantage of all the features that WinHelp() offers. Listing 23.3. Declarations needed to use the WinHelp() function.
>     // Call CWinApp::WinHelp()

>     // Define global constants for fuCommand

>     #define HELP_CONTEXT     0x1    /* Display a specified topic */

>     #define HELP_QUIT        0x2    /* Terminate WinHelp for application */

>     #define HELP_INDEX       0x3    /* Display the Help index */

>     #define HELP_HELPONHELP  0x4    /* Display Help on using Help */

>     #define HELP_SETINDEX    0x5    /* Set the current Help index */

>     #define HELP_KEY         0x101  /* Display a topic for keyword */

>     #define HELP_MULTIKEY    0x201  /* Use the alternative keyword table */

>     #define KEY_F1           0x70   /* Key code for Help key */
You don't need to add the constants to your source file if you want to substitute the integer values shown in Table 23.2 as the fuCommand argument when you use the WinHelp() function. ### Summary Online help is a critical component of all but the most rudimentary database applications. This statement applies not only to Visual C++ Windows database applications, but also to database front ends you create in any language. This chapter isn't meant to be a substitute for the Help Compiler Guide, nor does it cover as much information as books that are devoted to authoring WinHelp files, such as Microsoft's Help Authoring Guide. If this chapter's examples of using the commercial help-authoring tools accomplished their purpose, you'll want to acquire one of these tools to accelerate the development of online WinHelp for your Visual C++ database applications. The next chapter, the last in this book, describes how you organize the Setup application for your Visual C++ database front ends and how to manage the distribution of your applications on diskettes. Contact reference@earthweb.com with questions or comments. Copyright 1998 EarthWeb Inc., All rights reserved. PLEASE READ THE ACCEPTABLE USAGE STATEMENT. Copyright 1998 Macmillan Computer Publishing. All rights reserved. |