How to Add a Custom Tab to the Help Topics Dialog Box (139834)

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)
				

This function will be called automatically by WinHelp when the custom tab is clicked; at which point, WinHelp passes the window handle of the tab dialog box as the first parameter. This allows you to call CreateDialog() from within the function. The remaining two parameters are reserved for future use and can be ignored.

Example DLL

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

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

HINSTANCE hinst;  // Used by OpenTabDialog()

/* DllMain exists solely for the purpose of obtaining the DLL instance
 * and storing it in a global variable used to call CreateDialog().
 */ 
BOOL WINAPI DllMain (HINSTANCE hinstDll, DWORD fdwReason,
  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.

HWND WINAPI OpenTabDialog(HWND hwnd, DWORD dwReserved1, DWORD dwReserved2){


     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.

If you do not wish to work with HCW, you can open your Contents file in a text editor, and add the following line:

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

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

Once you make this change, you will need to save the file and recompile your .hpj file.