Help Manager

Application Components

The Application Source

1. The call can complete successfully, and the return value is the handle of the help instance.
2. The function can partially complete, returning a help instance handle and specifying an error code in the  ulReturnCode field. 
3. The function can fail returning NULL.  Because of the subtle difference between (1) and (2), it is not sufficient   to simply check the return value.
   

Gotcha! Note that the call to WinAssociateHelpInstance will not work if you call it within the WM_CREATE message of the  window with which it is associated.  WinAssociateHelpInstance needs a valid window handle, and when the  WM_CREATE message is received, the window handle is not yet valid.

Messages

• "Using help..."
• "General help..."
• "Keys help..."
• "Help index..."
  

The Help Tables

1. The user presses F1.
2. The help instance determines the ID of the window that it is currently associated with. 
3. The HELPITEM for the given window ID is referenced, and the appropriate HELPSUBTABLE is determined. 
4. The menu item ID (or the ID of the window with the focus) is used to look up in the HELPSUBTABLE the ID of the help panel to display. 
5. The help panel definition is retrieved from the compiled help file. 
6. The help panel is displayed.
   

Sample HELPTABLE

 HELPTABLE HELP_CLIENT
 {
         HELPITEM HELP_CLIENT, SUBHELP_CLIENT, EXTHELP_CLIENT
         HELPITEM DLG_OPEN, SUBHELP_OPEN, EXTHELP_OPEN
         HELPITEM DLG_PRODUCTINFO,
                 SUBHELP_PRODUCTINFO, EXTHELP_PRODUCTINFO
 }
 
 
 HELPSUBTABLE SUBHELP_CLIENT
 {
         HELPSUBITEM M_FILE,  HELP_M_FILE
         HELPSUBITEM MI_NEW,  HELP_MI_NEW
         HELPSUBITEM MI_OPEN, HELP_MI_OPEN
         HELPSUBITEM MI_SAVE, HELP_MI_SAVE
         HELPSUBITEM MI_CLOSE,HELP_MI_CLOSE
         HELPSUBITEM MI_EXIT, HELP_MI_EXIT
         HELPSUBITEM M_HELP,  HELP_M_HELP
         HELPSUBITEM MI_USINGHELP,   HELP_MI_USINGHELP
         HELPSUBITEM MI_GENERALHELP, HELP_MI_GENERALHELP
         HELPSUBITEM MI_KEYSHELP,    HELP_MI_KEYSHELP
         HELPSUBITEM MI_HELPINDEX,   HELP_MI_HELPINDEX
         HELPSUBITEM MI_PRODINFO,    HELP_MI_PRODINFO
 }
 HELPSUBTABLE SUBHELP_SETOPEN
 {
         HELPSUBITEM DOPEN_EF_FILENAME, HELP_DOPEN_EF_FILENAME
         HELPSUBITEM DLG_PB_OK,         HELP_DLG_PB_OK
         HELPSUBITEM DLG_PB_CANCEL,     HELP_DLG_PB_CANCEL
         HELPSUBITEM DLG_PB_HELP,       HELP_DLG_PB_HELP
 }
 
 HELPSUBTABLE SUBHELP_PRODINFO
 {
         HELPSUBITEM DLG_PB_CANCEL,  HELP_DLG_PB_CANCEL
         HELPSUBITEM DLG_PB_HELP,    HELP_DLG_PB_HELP
 }

Gotcha! If the resource ID specified in the WinCreateStdWindow call is different from that used as the resource ID of the HELPTABLE, the first parameter to the HELPITEM that refers to the main window should be the same as the HELPTABLE resource ID and not the ID for the frame resources.

Message Boxes

         (USHORT)WinMessageBox(HWND   hwndParent, // parent window
                               HWND   hwndOwner,  // owning window
                               PSZ    pszMessage, // pointer to the text
                               PSZ    pszTitle,   // pointer to the title
                               USHORT usHelpId,   // help topic id
                               ULONG  ulStyle);   // message box style

Fishing, Anyone ?

        (BOOL)WinSetHook(HAB habAnchor,     // HAB of the calling thread
		         HMQ hmqQueue,      // HMQ of the calling thread,
				            // HMQ_CURRENT for current thread or NULL for
			                    // system-wide hook
			 USHORT usHookType, // HK_* constant
		         PFN pfnHookProc,   // pointer to the hook procedure
		         HMODULE hmodProc); // HMODULE containing pfnHookProc

        (BOOL)pfnHookProc(HAB habAnchor,    // HAB of the calling thread
		          SHORT sMode,      // HLPM_* constant
		          USHORT usTopic,   // Topic number
			  USHORT usSubTopic,// Subtopic number
			  PRECTL prclPosition);

Gotcha! Note that the documentation states that the help hook should be installed before creating the help instance.  However, since WinSetHook installed the hook at the head of the hook chain, this information is backwards.  For this procedure to work properly, the call to WinSetHook should be placed after the call to WinAssociateHelpInstance.

Gotcha! The header files in the Toolkit indicate that the parameters for the help hook are a SHORT and two USHORTs for 16-bit applications and a LONG and two ULONGs for 32-bit application. This is incorrect. The parameters are always a SHORT and two USHORTs.

The Help Panels

Sample Help Panel

 :h1 id='MYPANEL' res=1000.My help panel
 :p.When adding online help to your PM application, the following
 steps must be taken
 :fnref refid='MYFN'.:
 :ul compact.
 :li.Initialization code must be written
 :li.Messages must be processed
 :li.Resources must be defined
 :li.Help panels must be compiled
 :eul.
 :fn id='MYFN'.
 Footnotes start on an implied paragraph.
 :efn.

Putting It All Together

Restrictions

Using HELP TABLEs for Message Box Help

• Hooks are "performance-eaters," so help-related activity will execute faster using HELPTABLEs.
• Using HELPTABLEs is less confusing which makes them easier to code.

• Each message box requires a HELPITEM in the HELPTABLE. For large applications, your HELPTABLE can quickly get unwieldy using HELPTABLEs.

1. Add a HELPITEM in the HELPTABLE with the first parameter having the value of the identifier specified as the fifth parameter to WinMessageBox. The second parameter of the HELPITEM specifies a HELPSUBTABLE for the message box and the third specifies the resource ID of the "General help" panel for the message box.
2. Add a HELPSUBTABLE whose identifier is the same as that of the second parameter of HELPITEM created in step 1.
3. Add one HELPSUBITEM in the HELPSUBTABLE created in step 2 for each button displayed in the message box (specified using the MB_ constants). The first parameter of the HELPSUBITEM is the MBID_ constant corresponding to the message box button, and the second parameter is - as you would guess - the resource ID of the help panel corresponding to the message box button.

Gotcha! If a HELPSUBTABLE corresponding to a message box is empty, nothing will happen when the user presses F1 on that message box. No error message can be sent because, as we stated earlier, the message box does not necessarily know to whom the message should be sent.