Microsoft & .NET Visual Basic Using the Help API

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.

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:

Using HTML Help
Adding
Help to your application

Latest Posts

Related Stories