The help hook allows an application to include online help. The system calls a help hook function during the default processing of the WM_HELP message. Help processing is done in two stages: creating the WM_HELP message and calling the help hook. The WM_HELP message can come from the following sources:
The WM_HELP message is posted to the current focus window. The default processing in WinDefWindowProc is to pass the message up to the parent window. If the message reaches the client window, it can be processed there. If the message reaches a frame window, the default frame-window procedure calls the help hook. The help hook is also called if a WM_HELP message is generated while the application is in menu mode, that is, while a selection is being made from a menu. The following code shows the syntax for a help hook function:
BOOL EXPENTRY HelpHook(HAB hab, ULONG usMode, ULONG idTopic, ULONG idSubTopic, PRECTL prcPosition)
If a help hook function returns TRUE, the system does not call the next help hook function in the chain. If the function returns FALSE, the system calls the next help hook function in the chain. The arguments passed to the function provide contextual information, such as the screen coordinates of the focus window and whether the message originated in a message box or a menu.
The WM_HELP message often goes to a frame window instead of to the client window. The frame window processes a WM_HELP message as follows:
Mode = HLPM_FRAME Topic = frame-window identifier Subtopic = focus-window identifier Position = screen coordinates of focus window
Mode = HLPM_WINDOW Topic = identifier of parent of focus window Subtopic = focus-window identifier Position = screen coordinates of focus window
An application receives the WM_HELP message in its dialog-window procedure. The application can ignore the message, in which case the frame-window action occurs as described, or the application can handle the WM_HELP message directly.
Menu windows receive a WM_HELP message when the user presses the Help accelerator key (F1 by default) while a menu is displayed. Menu windows process WM_HELP messages by calling the help hook, specifying the following:
Mode = HLPM_MENUTopic = identifier of pull-down menu Subtopic = identifier of selected item in pull-down menu Position = screen coordinates of selected item
A help hook function should respond by displaying information about the selected menu item.
WinDefWindowProc processes WM_HELP messages by passing the message to the parent window. Typically, the message moves up the parent chain until it arrives at a frame window.