INFO: HTML Help Embedded Windows - Issues and Workarounds

ID: Q194116

The information in this article applies to:

Microsoft HTML Help, versions 1.3, 1.0, 1.1, 1.2, 1.21

SUMMARY

Embedded Help windows provide a way to integrate Help with a Windows application. If you plan to implement embedded Help windows using the HTML Help executable (Hh.exe) program, these are the issues you need to know about:

There are several key limitations to using embedded windows.

To use embedded windows, you need to run Hhctrl.ocx in single- threaded mode.

MORE INFORMATION

Limitations of Embedded Windows

Embedded windows are a simple solution to a difficult problem. To begin with, embedded Help is not truly embedded--it is parented. Embedding Help in your Windows application involves parenting a Help window to a window in your application, making the Help window a child of that application window. The only way to control this window is through the Win32 API. Under normal circumstances, this does not present a problem because you write the code for both the parent window and the child window. Unfortunately, in the case of embedded Help, the Help window is based on code written in HTML Help, which means that a Help window is the frame window for Hh.exe. A Help window is not designed to be a child window.

If you only need to show some contextual Help information, the performance of embedded Help should be acceptable. However, if you need to do more extensive customization, there are some problems with using embedded Help. The main limitations are as follows:

You do not have much control over the appearance of the Help window. The HTML Help API does not currently support this.

Painting and resizing of the embedded window is unpredictable. Your Help is usable, but it might not always work perfectly.

If you encounter bugs, your ability to fix them is limited because you cannot change the code for the HTML Help window.

Running Hhctrl.ocx in Single-Threaded Mode

Hhctrl.ocx runs in a second thread, so that it can handle the keyboard. This causes instability when you use Hhctrl.ocx in an embedded Help scenario. The best solution is to turn off the secondary thread and have your Windows application pump messages. If you are planning to implement embedded Help, you should upgrade to HTML Help 1.2, which supports message pumping through the HTML Help API.

Setting the control to become single threaded involves calling two API commands: 1) call HH_INITIALIZE at startup, and 2) call HH_UNINITIALIZE at shutdown. Pumping messages consists of calling the HTML Help API HH_PRETRANSLATEMESSAGE command and passing it the MSG structure from your GetMessage call in your message loop. For example:

Code example: HH_INITIALIZE


   DWORD dwCookie = NULL;
   HtmlHelp(NULL, NULL, HH_INITIALIZE,   (DWORD)&dwCookie) ;
   // Cookie returned by Hhctrl.ocx. This must be used in the
   // HH_UNINITIALIZE call.

Code example: HH_UNINITIALIZE


   HtmlHelp(NULL, NULL, HH_UNINITIALIZE, (DWORD)dwCookie) ;
   // Pass in cookie.

Code example: HH_PRETRANSLATE


MSG msg;

   while (GetMessage (&msg, NULL, 0, 0))
   // Retrieve a message from the calling thread's message queue.
   {
      if (!HtmlHelp (NULL,NULL,HH_PRETRANSLATEMESSAGE,&msg))
      {
          TranslateMessage (&msg);
          DispatchMessage (&msg);
      }
   }

Return values for HH_PRETRANSLATE:

True, if message is translated.

False, if command fails.

NOTES:

Call HH_INITIALIZE before calling any other command and call HH_UNINITIALIZE only when your application ends. You should call these commands once during the life of your application.

Do not call HH_UNINITIALIZE before or at process detach.

REFERENCES

HTML Help Workshop: HTML Help API

Additional query words:

Keywords : kbAPI kbSDKPlatform kbHTMLHelp100 kbHTMLHelp110 kbHTMLHelp120 kbGrpDSTools kbHTMLHelp121 kbHTMLHelp130
Version : WINDOWS:1.0,1.1,1.2,1.21
Platform : WINDOWS
Issue type : kbinfo