How to Add a Custom Tab to the Help Topics Dialog Box

• Microsoft Win32 Application Programming Interface (API) included with:

      - Microsoft Windows NT version 3.51
      - Microsoft Windows 95 version 4.0
  

SUMMARY

This article discusses how to add a custom tab to the Help Topics dialog box. This option is only available in version 4.0 or later of the Help Compiler for Windows.

MORE INFORMATION

Create a Dialog Resource

To add a custom tab to the WinHelp Help Topics dialog box, you must do three things:

1. Create a dialog template resource to display in the custom help tab. The dialog template that you create will be displayed over the top of the existing Help Tab dialog box. You do not need to worry about the size of the dialog frame; WinHelp will automatically resize it at display time to ensure that it fits.

2. Ensure that the dialog template that you create has no borders and includes the WS_CHILD and the DS_CONTROL styles. DS_CONTROL is a new style that ensures that the dialog box will get the focus when the tab is activated. DS_CONTROL is defined in Winuser.h file included with the Win32 SDK. The definition is as follows:

      #define DS_CONTROL          0x0400L
   
   

3. Make the dialog box itself visible. On this last point, Help (Hcw.hlp) incorrectly suggests that the dialog box should be invisible. This is an error. If you do not ensure that the dialog box is visible, you will not be able to see it when you click on the custom help tab.

Write a DLL to Support the Dialog Resource

Once you have created the dialog resource, you must write a DLL to support it. In addition to including the dialog box procedure, the DLL must export the following function, prototyped as follows:

   HWND WINAPI OpenTabDialog(HWND, DWORD, DWORD)

Example DLL

Here is an example of what this DLL might look like:

#include <windows.h>
#include "resource.h"

/* DllMain exists solely for the purpose of obtaining the DLL instance
 * and storing it in a global variable used to call CreateDialog().
 */

  LPVOID lpReserved)

     switch (fdwReason){

          case DLL_PROCESS_ATTACH:
               hinst = hinstDll;
               break;
     }

     return (TRUE);

BOOL WINAPI DialogProc (HWND hDlg, UINT message, UINT wParam,

  long lParam)

     . . .

     return FALSE;

/* This procedure is called by WINHLP32. Winhelp passes in its hwnd
 * so you can call Create Dialog. The instance handle for the DLL is
 * stored in a global variable that is initialized in LibMain.

     return (CreateDialog (hinst, MAKEINTRESOURCE(IDD_DIALOG1), hwnd,
  DialogProc));

Modify the Help Project (.hpj) File

Once the DLL has been written, you must modify the Help project file (.hpj file) to include the custom tab and link the DLL to it. If you are using HCW, open your Contents file (.cnt file). (If you have not created one, you must do so in order to use your custom tab.) In the Contents dialog box, follow these steps:

1. Click the Tabs button to bring up the Custom Tabs dialog box.

2. Click the Add button to bring up the Add Tab dialog box.

3. Enter the name to appear on the tab in the Tab Name edit box.

4. Enter the name of your custom .dll file (and optionally the path) in the DLL File Name edit box.

5. Click OK twice to exit the dialog boxes.

6. On the File menu, click Save to save your changes.

7. Compile the .hpj file. When you use your help file, the custom tab should now be available to you.

   :Tab <tab name>=<path to DLL>

   :Tab mytab=c:\helptab\debug\helptab.dll