Programming Context-Sensitive Help

If you plan on having context-sensitive Help for all individual window elements and dialog box controls, note that this will result in hundreds or thousands of context-sensitive Help topics. To manage the integration of context-sensitive Help, you need to assign the Help context IDs in a systematic manner. You can give your tech writer the responsibility of assigning the IDs, but you are the one who is going to have to integrate the context-sensitive Help so you should be the one who decides how it is done.

Since the Help compiler has several restrictions on header files (for example, it doesn't support #ifdef and #endif statements, and it can't handle arithmetic in #define statements), you should create a separate header file just for the Help context IDs that you can share with the tech writer. If you assign the context IDs using consistent prefixes (such as HIDC_), the Microsoft Help Workshop can automatically verify that the IDs defined in the header file exist in the Help file. This technique helps you make sure that all Help topics actually have help. If you are using Microsoft Visual C++, you can have the dialog box editor automatically assign context IDs for controls by selecting the Help ID check box in the control's Properties dialog box. The context ID values are based on a combination of the dialog box ID and the control ID. Alternatively, you can use the MakeHm utility to automatically generate the context IDs.

If you are using context-sensitive Help for dialog boxes, be careful in how you assign control IDs in the dialog box templates. Note that when users need Help for a control, sometimes they click the control directly and other times they click the control label. The good news is that you can give context-sensitive Help to static text labels simply by giving them a control ID of -1 (that is, IDC_STATIC) and ensuring that the control with the desired Help context is directly after the label in the tab order and has the tab stop attribute set. Now if the user clicks the label, WinHelp will recognize the control as a label and use the desired Help context instead. The bad news: WinHelp does this for all controls, not just static text labels, so you need to assign control IDs other than -1 for any control that should not have context-sensitive Help. Lastly, you need to discuss with your tech writer whether group box controls should have context-sensitive Help, since it might make sense in certain cases, such as when you're using the group box as a label for one or more controls.

You provide WinHelp the information it needs to map from the selected control ID to the desired Help context ID by using an array of DWORD pairs, where the first DWORD is the control ID and the second DWORD is the Help context ID. This array is terminated with two NULLs so that WinHelp can find the end of the array. All controls in the dialog box with a control ID other than -1 need to be in this array, even if they do not have a Help context. In this case, the Help context ID should be -1. Let's look at some typical code:

LRESULT CALLBACK ExampleDlgProc (HWND hDlg, UINT uMsg, WPARAM wParam,                                  LPARAM lParam) {    // The array of control IDs and context IDs    Static DWORD helpIDs [] =    {       ID_CONTROL1, HIDC_CONTROL1,       ID_CONTROL2, HIDC_CONTROL2,       0, 0    }    switch (uMsg)    {         case WM_HELP:            WinHelp(((LPHELPINFO)lParam)->hItemHandle,            _T("helpfile.hlp"), HELP_WM_HELP, (DWORD)(LPVOID)helpIDs);         break;        }    return FALSE; }

Given all these requirements, let's quickly summarize the rules for assigning control IDs and Help context IDs:

• For a normal control with a Help context Assign a control ID other than -1 and a context ID other than -1 and put the mapping in the Help ID array.
• For a normal control without a Help context Assign a control ID other than -1 and a context ID of -1 and put the mapping in the Help ID array.
• For a static text label of an enabled control Assign a control ID of -1 and assign its tab order just before the control with the desired Help context. Do not put the mapping in the Help ID array.
• For a static text label of a disabled control Assign the label a control ID other than -1 and a context ID to the desired help context and put the mapping in the Help ID array. Unfortunately, the mechanism for assigning context IDs doesn't work if the associated control is disabled.