A help system is becoming fundamental to the success of the software. It provides
information on how to use your product, and can be easily integrated into the program. To
author and compile your help file, you need to download the Help Compiler from Microsoft
(download it from Winfiles), and another third party
product to write the necessary RTF file. I use HelpScribble from JGSoft, which has a good user interface and is very easy
to use. Your help project is made up of several file types:
| RTF | This contains all of the text, references to pictures, and all the keywords. This is the heart of the help file before compilation. |
| HPJ | The project (.hpj) file is a text file that is used to compile your Help file. The project file contains all the information that the compiler needs to combine topic (.rtf) files and other elements into a Help file. |
| CNT | The contents file. This is distributed with the finished help file and is used by the Windows help engine to create the contents tree. |
| GID | This is created when the help file is first opened. It contains binary representations of the contents file and positions of topics within the main help file enabling the help file to be opened quicker the next time. |
| FTS,FTG | These contain the indexes of words and phrases created by the find tab. |
| BMP,SHG | These are the bitmaps which are compiled into the final help file. SHG files are Segmented Hypergraphics which are like image maps: they are sensitive to which area the user clicks on, enabling you to link to different topics depending on where the user clicks. |
| HLP | This is the compiled help file. You can select compression when you compile it, which reduces the file size considerably. You only need distribute this and the CNT file with your application. |
To integrate the help file into your applications you need to use the hefty
CommonDialog OCX to be able to use the features in VB . . . or do you? Using the Help API
you can do the same things, and more, without a weighty OCX. You will need these
declarations:
Public Declare Function WinHelp Lib _ "user32" Alias "WinHelpA" _ (ByVal hwnd As Long, ByVal _ lpHelpFile As String, _ ByVal wCommand As enm_wCommand, _ ByVal dwData As Long) As Long Public Declare Function WinHelpString _ Lib "user32" Alias "WinHelpA" _ (ByVal hwnd As Long, ByVal _ lpHelpFile As String, _ ByVal wCommand As enm_wCommand, _ ByVal strData As String) As Long Public Declare Function WinHelpStruct _ Lib "user32" Alias "WinHelpA" _ (ByVal hwnd As Long, ByVal _ lpHelpFile As String, _ ByVal wCommand As enm_wCommand, _ ByRef udtData As Any) As Long Public Enum enm_wCommand HELP_CONTEXT = &H1& HELP_QUIT = &H2& HELP_CONTENTS = &H3& HELP_INDEX = &H3& HELP_HELPONHELP = &H4& HELP_SETCONTENTS = &H5& HELP_SETINDEX = &H5& HELP_CONTEXTPOPUP = &H8& HELP_FORCEFILE = &H9& HELP_CONTEXTMENU = &HA& HELP_FINDER = &HB& HELP_WM_HELP = &HC& HELP_SETPOPUP_POS = &HD& HELP_FORCE_GID = &HE& HELP_TAB = &HF& HELP_KEY = &H101& HELP_COMMAND = &H102& HELP_PARTIALKEY = &H105& HELP_MULTIKEY = &H201& HELP_SETWINPOS = &H203& End Enum Public Type MULTIKEYHELP mkSize As Long mkKeylist As Byte szKeyphrase As String * 253 ' Array length is arbitrary; may be changed End Type Public Type HELPWININFO wStructSize As Long left As Long top As Long width As Long height As Long state As enm_windowstate rgchMember As String * 2 End Type Public Enum enm_windowstate SW_HIDE = 0& SW_SHOWNORMAL = 1& SW_SHOWMINIMIZED = 2& SW_SHOWMAXIMIZED = 3& SW_SHOWNOACTIVATE = 4& SW_SHOW = 5& SW_MINIMIZE = 6& SW_SHOWMINNOACTIVE = 7& SW_SHOWNA = 8& SW_RESTORE = 9& End Enum
I have included type-safe declarations so that we can pass strings and UDTs. The
WinHelp call has these parameters:
| hwnd | Handle of the window requesting Help. The WinHelp function uses this handle to keep track of which programs have requested Help. If wCommand specifies HELP_CONTEXTMENU, hwnd identifies the control requesting Help. |
| lpHelpFile | The name of the Help file that WinHelp is to display. The filename may be followed by an angle bracket (>) and the name of a secondary window if the topic is to be displayed in a secondary window rather than in the primary window. The name of the secondary window must have been defined previously in the [WINDOWS] section of the Help Project (.HPJ) file. |
| wCommand | Type of help requested. For a list of possible values and how they affect the value to place in the dwData parameter, see below. |
| xxxData | Additional data. The value used depends on the value of the wCommand parameter. For a list of possible values, click here. |
The wCommand can be one of the following constants:
HELP_COMMAND (Use WinHelpString)
Runs a Help macro or macro string.
strData: A string that specifies the name of the Help macro(s) to run. If the string
specifies multiple macro names, the names must be separated by colons or semicolons. You
must use the short form of the macro name for some macros because WinHelp does not support
the long name. For example, this will open the WinHelp engine and call the ExecProgram
macro, running calc.exe.:
WinHelpString hwnd, "C:WindowsCalc.hlp", _
HELP_COMMAND, "ExecProgram(""calc.exe"",0)"
HELP_CONTENTS
Displays the topic specified by the Contents option in the [OPTIONS] section of the
.HPJ file. This command is for backward compatibility. New programs should provide a .CNT
file and use the HELP_FINDER command.
dwData: Ignored; set to 0.
For example, this would open up the contents topic as defined in the .hpj file.
However, there isn’t one, so help just displays a default window:
WinHelp hwnd, "C:WindowsCalc.hlp", _ HELP_CONTENTS, 0
HELP_CONTEXT
Displays the topic identified by the specified context identifier defined in the [MAP]
section of the .HPJ file.
dwData: Long containing the context identifier for the topic.
For example, this will display a topic on changing the sign from the calculator help
file:
WinHelp hwnd, "C:WindowsCalc.hlp", _ HELP_CONTEXT, 80
HELP_CONTEXTPOPUP
Displays, in a pop-up window, the topic identified by the specified context identifier
defined in the [MAP] section of the .HPJ file.
dwData: Long containing the context identifier for a topic.
For example, this will display in a pop-up window the topic described in the above
example:
WinHelp hwnd, "C:WindowsCalc.hlp", _ HELP_CONTEXTPOPUP, 80
HELP_FINDER
Displays the Help Topics dialog box, selecting the previously selected tab. dwData:
Ignored; set to 0.
For example:
WinHelp hwnd, "C:WindowsCalc.hlp", _ HELP_FINDER, 0
HELP_FORCEFILE
Ensures that WinHelp is displaying the correct Help file. If the incorrect Help file is
being displayed, WinHelp opens the correct one; otherwise, there is no action.
dwdata: Ignored; set to 0.
For example:
WinHelp hwnd, "C:WindowsCalc.hlp", _ HELP_FORCEFILE, 0 'not quite sure
HELP_HELPONHELP
Displays Help on how to use WinHelp, if the WINHLP32.HLP file is available.
dwdata: Ignored; set to 0.
For example:
WinHelp hwnd, "C:WindowsCalc.hlp", _ HELP_HELPONHELP, 0
HELP_INDEX
Displays the topic specified by the CONTENTS option in the [OPTIONS] section of the
.HPJ file. This command is for backward compatibility. New programs should provide a .CNT
file and use the HELP_FINDER command.
dwdata: Ignored; set to 0.
For example:
WinHelp hwnd, "C:WindowsCalc.hlp", _ HELP_INDEX, 0
HELP_KEY (Use WinHelpString)
Displays the topic in the keyword table that matches the specified keyword, if there is
an exact match. If there is more than one match, this command displays the Topics Found
list box.
strdata: A keyword string. Multiple keywords must be separated by semi-colons.
For example, this will show information about the binary button in the calculator help
file:
WinHelpString hwnd, "C:WindowsCalc.hlp", _ HELP_KEY, "Bin button"
HELP_PARTIALKEY (Use WinHelpString)
Displays the topic in the keyword table that matches the specified keyword if there is
an exact match. If there is more than one match, this command displays the Topics Found
dialog box. To display the Index without passing a keyword, you should use an empty
string.
strdata: A keyword string. Multiple keywords must be separated by semi-colons.
For example:
WinHelpString hwnd, "C:WindowsCalc.hlp", _ HELP_PARTIALKEY, "Bin Butto"
HELP_QUIT
Informs the WinHelp program that it is no longer needed. If no other programs have
asked for Help, Windows closes the WinHelp program.
dwdata: Ignored; set to 0.
For example:
WinHelp hwnd, "C:WindowsCalc.hlp", _ HELP_QUIT, 0
HELP_TAB
Opens the Help Topics dialog box, displaying the specified extensible tab. The first
tab is 0. If there are no extensible tabs available, then the contents tab will be
selected.
dwData: Zero-based index of the extensible tab to display (0 is the first tab, 1 the
second, etc.).
For example, this will display the contents tab of the calculator help file:
WinHelp hwnd, "C:WindowsCalc.hlp", _ HELP_TAB, 0
HELP_SETCONTENTS
Specifies the Contents topic. The WinHelp program displays this topic when the user
clicks the Contents button if the Help file does not have an associated .CNT file. This is
not needed in Windows 95, but is included for backward compatibility.
dwdata: Long containing the context identifier for the Contents topic.
HELP_SETINDEX
Specifies the Index topic. The WinHelp program displays this topic when the user clicks
the Index button if the Help file does not have an associated .CNT file. This is not
needed in Windows 95, but is included for backward compatibility.
dwdata: Long containing the context identifier for the Index topic.
HELP_SETPOPUP_POS
Sets the position of the subsequent pop-up window.
dwdata: The position to display the pop-up window. The high word is the y-co-ordinate
and the low word is the x-co-ordinate.
For example:
Dim x As Integer, y As Integer x = 300 y = 300 WinHelp hwnd, "C:WindowsCalc.hlp", _ HELP_SETPOPUP_POS, y * 2 ^ 16 + x 'opens popup id WinHelp hwnd, "C:WindowsCalc.hlp", _ HELP_CONTEXTPOPUP, 80 'opens popup id Next
HELP_SETWINPOS (Use WinHelpStruct)
Displays the Help window, if it is minimised or in memory, and sets its size and
position as specified.
udtdata: A HELPWININFO structure that specifies the size and position of either a
primary or secondary Help window.
For example, this will show the help window with our chosen dimensions:
Dim mywinpos As HELPWININFO mywinpos.wStructSize = Len(mywinpos) mywinpos.left = 10 mywinpos.top = 300 mywinpos.width = 300 mywinpos.height = 10 mywinpos.state = SW_SHOW WinHelp hwnd, "C:WindowsCalc.hlp", _ HELP_CONTEXT, 80 'opens context id WinHelpStruct hwnd, "C:WindowsCalc.hlp", _ HELP_SETWINPOS, mywinpos
Specify the left, top, width and height variables in the respective properties of the
UDT.
Note that WinHelp divides the screen up into units so that both the width and height
are 1024 units. The wStructSize should be set so that the API knows how long the structure
is. The state contains the desired window state; it is similar to the shell
command’s windowstyle parameter. The options are:
| SW_HIDE | Hides the window and passes activation to another window. |
| SW_MINIMIZE | Minimises the specified window and activates the top level window in the Z order. |
| SW_RESTORE | Same as SW_SHOWNORMAL. |
| SW_SHOW | Activates a window and displays it in its current size and position. |
| SW_SHOWMAXIMIZED | Activates the window and displays it as a maximised window. |
| SW_SHOWMINIMIZED | Activates the window and displays it as an icon. |
| SW_SHOWMINNOACTIVE | Displays the window as an icon. The window that is currently active remains active. |
| SW_SHOWNA | Displays the window in its current state. The window that is currently active remains active. |
| SW_SHOWNOACTIVATE | Displays a window in its most recent size and position. The window that is currently active remains active. |
| SW_SHOWNORMAL | Activates and displays the window. Whether the window is minimised or maximised, Windows restores it to its original size and position. |
rgchMember does not do anything, so should be left empty.
Well that’s about it on the help API. You can now open up the help system, setting the
window position, and execute WinHelp macros, all without the CommonDialog control. It is
very easy to use, and does not require you to distribute another large ActiveX control.
Technology moves on, and the new standard for Windows 98 is HTML Help. This is beyond the
scope of this article, but you can read more about it at the Microsoft site at:
