Advanced HTML Help Workshop Use

Adding Context Sensitive Help to Your LB Programs

Originally published in NL 131
-

Start with the Table of Contents File

Adding context sensitive help to you LB program is really quite easy. To simplify things this article builds upon the Creating Compiled HTML Help article] Start by creating a folder for this project. The folder I used is "E:\LBNews\108\chm", although you can use any folder you wish. Extract the files from

chm.zip

into your project folder. [Newsletter Home Page.] Using Notepad, open the "Table of Contents.hhc" file.

Look for

<param name="Name" value="Main Page">
<param name="Local" value="index.htm">

This defines the htm file to be used for "Main Page", and there are similar entries for hello.htm and text.htm. The "Local" values need to be changed to reflect the path to your project folder, like this

<param name="Local" value="E:\LBNews\108\chm\index.htm">

Save the file. This has nothing to do with using context sensitive help but it must be done before you will be able to compile the help file in its new project folder.

Modifications to the Project File

To enable context sensitive help for a chm help file a couple of categories must be added to the project file. The help project file used in newsletter 108 is named "mainpage.hhp". Using Notepad, open this file and add the following lines to the end of the file:

[ALIAS]
IDH_HELLO = hello.htm
IDH_CLONE = text.htm
[MAP]
IDH_HELLO 10
IDH_CLONE 20

Save the file. What you have just done is to associate a number with the two htm files hello.htm and text.htm. These are our context sensitive help topics that we want to display from our program. Assigning a number for each of these pages allows the help file to be opened at the one of the specified pages. Please note that the IDH_ prefix should always be used. Open mainpage.hhp in HTML Help Workshop and compile it. That's all there is to it!

Displaying Context Sensitive Help

To call a specific topic from your program, perhaps from a button in a dialog, you make a dll call and pass the appropriate IDH number for the page to display. Here is a short demo. Copy the code into the LB editor and save it in the same folder as the help file mainpage.chm. When the saved code is run it should open mainpage.chm to the My First Program page.

Demo

'Calling context sensitive help from Liberty BASIC
 
HH.HELP.CONTEXT = 15 'HH_HELP_CONTEXT 
hlpFile$ = DefaultDir$ + "\mainpage.chm"
IDMyFirstProgram = 10
IDNotePadClone = 20
 
'make sure hhctrl.ocx exists
hhctrl = LoadLibrary("hhctrl.ocx")
r = FreeLibrary(hhctrl)
 
if hhctrl then
  open "hhctrl.ocx" for dll as #hhctrl
  calldll #hhctrl, "HtmlHelpA", 0 As Long, _
    hlpFile$ As ptr, HH.HELP.CONTEXT As Long, _
    IDMyFirstProgram As Long, r As Long
else
  notice "Help is not available" + chr$(13) + _
  "You must have Internet Explorer 4.0 or later to use help."
end if
 
'Do not immediately close #hhctrl.
'You must allow enough time for the help file to display
'before closing the dll.
wait
 
if hhctrl then close #hhctrl
end
 
Function LoadLibrary(file$)
  Calldll #kernel32, "LoadLibraryA", file$ As Ptr, LoadLibrary As Ulong
End Function
 
Function FreeLibrary(hDLL)
  Calldll #kernel32, "FreeLibrary", hDLL As Ulong, FreeLibrary As Long
End Function

ContextSensitiveHelp