Using the Help API

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.