launching a Help file from within a win 32 program

[kyletindle]

ok simple problem i hope...

i'm doing a program in windows going fine but now i have to launch a help file (the standard windows type) ive created it using MS HTML workshop all compiled all works etc but in SIMPLE terms as this is my first windows program how do i do it...

help file from menu is called ID_HELP by the way and help file is called help.chm

cheers in advance

kyle tindle

[Bond]

In your ID_HELP handler, just use the HtmlHelp() API function, prototyped as follows:

HWND HtmlHelp(
              HWND    hwndCaller,
              LPCSTR  pszFile,
              UINT    uCommand,
              DWORD   dwData) ;

Look in MSDN for a good description of the parameters or try the following link:
http://msdn.microsoft.com/library/de...tmlhelpapi.asp

[SuperKoko]

To open a chm file, you can use the HtmlHelp function that is exported by the ocx (an ocx is just a normal dll that export ActiveX objects) HHCtrl.ocx.
I have only found on msdn, the declaration in visual basic of the function:

Declare Function HtmlHelp Lib "HHCtrl.ocx" Alias "HtmlHelpA" _ (ByVal hwndCaller As Long, _ ByVal pszFile As String, _ ByVal uCommand As Long, _ dwData As Any) As Long

But i have not found the declaration in C.

There is a little problem, because i don't know how to import functions from a file with a .ocx extension from a def file (if anyone know, he can says me how).
So, you can get a static library which import functions from the HHCtrl.ocx file:

Use implib from a dos prompt in the directory of your project like that:
implib -c hhctrl.lib %windir%\system\HHctrl.ocx

Or for Windows NT, 2000, XP
implib -c hhctrl.lib %sysdir%\HHCtrl.ocx

I am not sure that %sysdir% is defined in the windows NT, 2000, or XP environment, but i think so.
And now, here is an example of program using HtmlHelp function:

#define STRICT
#include <windows.h>

extern "C" HWND WINAPI HtmlHelpA(HWND hWndCaller,LPCSTR pszFile,UINT uCommand,ULONG_PTR pszTopic);
extern "C" HWND WINAPI HtmlHelpW(HWND hWndCaller,LPCWSTR pszFile,UINT uCommand,ULONG_PTR pszTopic);
#ifdef UNICODE
#define HtmlHelp HtmlHelpW
#else
#define HtmlHelp HtmlHelpA
#endif

#define HH_DISPLAY_TOPIC 0x0
#define HH_HELP_FINDER 0x0
#define HH_DISPLAY_TOC 0x1
#define HH_DISPLAY_INDEX 0x2
#define HH_DISPLAY_SEARCH 0x3
#define HH_SET_WIN_TYPE 0x4
#define HH_GET_WIN_TYPE 0x5
#define HH_GET_WIN_HANDLE 0x6
#define HH_GET_INFO_TYPES 0x7
#define HH_SET_INFO_TYPES 0x8
#define HH_SYNC 0x9
#define HH_ADD_NAV_UI 0xA
#define HH_ADD_BUTTON 0xB
#define HH_GETBROWSER_APP 0xC
#define HH_KEYWORD_LOOKUP 0xD
#define HH_DISPLAY_TEXT_POPUP 0xE
#define HH_HELP_CONTEXT 0xF
#define HH_TP_HELP_CONTEXTMENU 0x10
#define HH_TP_HELP_WM_HELP 0x11
#define HH_CLOSE_ALL 0x12
#define HH_ALINK_LOOKUP 0x13

int WINAPI WinMain(HINSTANCE,HINSTANCE,LPSTR,int)
   {
   if (HtmlHelp(GetDesktopWindow(),TEXT("help.chm")
   			,HH_DISPLAY_INDEX,0))
		{
   	MessageBox(NULL,"Click OK to exit the program","HtmlHelp function usage example!",0);
      }
   return 0;
   }

The declarations, are perhaps not exactly correct, since i have not found any web site that exactly declare the function.
You must link your program to the HHCtrl.lib file.
My includes files are old, so i have not the ULONG_PTR type, and i have typedefed it to LPTSTR in my project. I have finally removed this typedef, before posting the code. Theorically, this code must compile on your computer.

I, now explains the parameters of HtmlHelp.
BOOL WINAPI HtmlHelpA(
HWND hWndCaller,
LPCSTR pszFile,
UINT uCommand,
ULONG_PTR pszTopic);

hWndCaller, is a handle to a window which become the parent of the window created by the help library.
It works like the first parameter of the MessageBox function or the hWndParent of the DialogBox function.
In the example, it is set to the desktop window (it can also be set to NULL, but i don't know if it is really documented).

pszFile if a pointer to the path to the .chm file. If the path is not absolute, it searches the file firstly in the current directory, and if it does not find the file, it searches in the help directory (localised in %windir%).

uCommand
Set of flags that describe what topic is showed in the help file.
if HH_DISPLAY_TOPIC is set (that is the default case, because HH_DISPLAY_TOPIC=0), than the pszTopic parameter is a pointer to a string that represents the URL of the html file within the .chm.
if HH_HELP_CONTEXT is set, then the pszTopic parameter is an integer that represents the integer identifier of the topic.

if HH_DISPLAY_TOC is set, the help is opened with the table of contents tab selected.
if HH_DISPLAY_INDEX is set, the help is opened with the index tab selected.
if HH_DISPLAY_SEARCH is set, the help is opened with the search tab selected.

I have not searched the meaning of other flags (i have just found these flags on internet, searching with google).
I have looked to the threads and processes, and see that when the function is called, two new threads are created.
And two calls to the HtmlHelp function, don't create more threads.
One of the two threads, is used for creating the windows.
What is strange, is that the help browser blocks when the main thread is busy (i have tested that with a call to Sleep).

There is a second method to call the help browser:
Launch the hh.exe application. This application has command-line parameters mapid which identify the context ID, of the help.
You must call CreateProcess to do that.

Excuse me, but i have just found the documentation of HtmlHelp on msdn.
Look at http://msdn.microsoft.com/library/de...tmlhelpapi.asp
http://msdn.microsoft.com/library/de...lpcommands.asp
and http://msdn.microsoft.com/library/de...sconswitch.asp for the command-line parameters of hh.exe.

And welcome in the Win32 programming world!

[SuperKoko]

Excuse me Bond, i was typing my post when you posted.

[Bond]

Excuse me Bond, i was typing my post when you posted.

No problem. You're much more thorough than me!

[dhirallin]

The above seems like an overly complicated solution. Why not just add the Include and Lib directories that are included with HTML Help Workshop to your project, and include the lib and header file in your project, whammo done. I was searching around Google and there are several misleading posts which seem to imply that HTML Help doesn't work out-of-the-box with WinAPI. This is not true, it works fine just including the provided header and lib.

[MrViggy]

The above seems like an overly complicated solution. Why not just add the Include and Lib directories that are included with HTML Help Workshop to your project, and include the lib and header file in your project, whammo done. I was searching around Google and there are several misleading posts which seem to imply that HTML Help doesn't work out-of-the-box with WinAPI. This is not true, it works fine just including the provided header and lib.

It wasn't an overcomplicated solution 6 years ago (when the question was posted).

Viggy