This review was originally published in the August 1995 issue
of Windows Tech Journal and is reprinted here with permission.
When you come home after a hard day's work, you may not have the time or energy to cook up a Windows Help file. Many C, C++, and Visual Basic programmers are faced with this problem. They don't often have to wrestle with the creation of Help files. But a Help file isn't that hard to create. Sometimes all your Help system needs is a quick Windows API call to add a little zing.
So set your mind at ease, 'cause soon you'll be able to whip up a batch of files to satisfy the whole family—and the Help will be more responsive, flexible, and better-tasting than your usual fare.
Click here to see the WinHelp Basics sidebar.
PREHEAT HARD DRIVE TO 350
I'll use my company's recent creation as an example. We had decided to record our business rules as a stand-alone Windows Help file, and we documented each procedure in two ways: a diagram of flowchart symbols and a step-by-step numbered list.
We created diagrams using Visio and exported them as Windows metafiles. Their symbols include shapes for processes (rectangles), decisions (diamonds), terminators (rounded rectangles), and connectors (circles). Four of the diagrams—installation, removal, upgrade, and service—deal with equipment. These diagrams represent a continuous, interrelated process. One service call could involve actions shown on several diagrams.
Connector symbols link the diagrams. A connector on one diagram indicates a link to a specific connector on another. We wanted our users to be able to click on one connector and have the Help system display not only another diagram, but the correct matching connector on that other diagram.
Also, users could scroll to specific locations, but we wanted the ability to display a specific object or region programmatically. My company needed "intelligent jumps" that would jump to whatever portion of a graphic we wanted to display.
SEASON TO TASTE
None of the WinHelp macros scrolls a graphic. Most simply duplicate the functions of standard help menu items (print, copy topic, annotate) or help buttons (search, next, previous).The RegisterRoutine macro lets you use any function in a dynamic link library as if it were a WinHelp macro. Because Windows itself consists of three DLLs, you can use Windows API functions as macros. But it takes a little footwork.
If a help topic contains a graphic (bitmap or metafile) larger than the window can display, WinHelp automatically adds scrollbars. It displays the top left margin of the topic and hence the top left corner of the graphic. When a graphic with scrollbars is displayed in the compiled Help file, several keys can scroll the graphic horizontally or vertically, letting you display any portion.
I wondered, if I sent Windows a message that one of these keys was pressed, whether the help window would display the desired part of a graphic.
So I used PostMessage to send the WinHelp window a WM_KEYDOWN message....
The intricate details from this article are omitted here for readability, since this is a writing sample and not intended to communicate the precise procedural steps for working with the Windows message loop. Contact me if you want to see the complete unabridged article.
WINHELP WELL-DONE
WinHelp imposes some restrictions on Windows programmers. You don't have pointers or loops. You also don't have variables, though you can embed one function as a parameter of another function and have the return value of the embedded function supply that parameter.
To overcome some of these limitations, you can create a DLL and register its functions using the RegisterRoutine macro—but sometimes a quick API call is all you need.
When the urge to add functionality to your Help system strikes, think about which Windows API functions you can use or which message you can send to let Windows do the work for you.
As you can see, creating Help files isn't a big deal. Just follow my simple recipe, and in no time you'll be serving up Help files your users will love.
Austin Avrashow is a technical writer and help system designer in Portland, Oregon.