You might want your DLL to receive notification of Windows Help events (for example, when the user selects a jump or changes input focus to an application other than Windows Help). To do this, you add a LDLLHandler function to the DLL. The LDLLHandler function has the job of processing messages sent from Windows Help to the DLL.
When the user clicks the Call HelloWorld hot spot in DLLDEMO.HLP, Windows Help loads DLLDEMO.DLL and looks for a function named LDLLHandler. If Windows Help finds LDLLHandler, it calls LDLLHandler. A sample LDLLHandler function is defined in the DLLDEMO.C file.
Note:
To debug your DLL or observe any of the operations described in this section, you can compile DLLDEMO for the CodeView for Windows symbolic debugger and open the DLL in CodeView while you view the sample title. See the DLLDEMO.C file for specific instructions.
The LDLLHandler function is defined in DLLDEMO.C as illustrated in the following example:
PUBLIC LONG PASCAL EXPORT LDLLHandler(
WORD wMsg,
LONG lParam1,
LONG lParam2)
{
switch(wMsg) {
case DW_WHATMSG:
return DC_INITTERM | DC_JUMP;
case DW_INIT:
return TRUE;
case DW_TERM:
return TRUE;
case DW_ACTIVATE:
return TRUE;
case DW_CHGFILE:
return TRUE;
}
return FALSE;
}In this definition, wMsg identifies the message Windows Help has sent to the DLL. The two LONG parameters are passed with the message and depend on the message type.
When the user first clicks the Call HelloWorld hot spot, Windows Help calls LDLLHandler with the wMsg parameter set to DW_WHATMSG. This message asks the DLL what types of Windows Help messages it wants to receive. LDLLHandler should return one or more of the flags in the following table with this information. Windows Help uses the flags returned by LDLLHandler to determine which messages the DLL wants to receive in the LDLLHandler function.
| LDLLHandler returns | Windows Help sends |
Description |
| DC_MINMAX | DW_MINMAX, DW_SIZE | Minimize, maximize, or resize Windows Help |
| DC_INITTERM | DW_INIT, DW_TERM | Initialize or terminate DLL |
| DC_JUMP | DW_STARTJUMP, DW_ENDJUMP, DW_CHGFILE | Jump or change .HLP file |
| DC_ACTIVATE | DW_ACTIVATE | Give Windows Help or another application input focus |
| DC_CALLBACKS | DW_CALLBACKS | Give DLL access to Windows Help entry points (see Calling Windows Help Internal Functions, later in this chapter, for more information) |
You combine these flags using the standard C bitwise-OR (|) operator. For example, many DLLs request notification when Windows Help is about to initialize or terminate them. The sample LDLLHandler function requests this notification and asks to be notified when the user has moved the input focus to or from Windows Help. It processes the DW_WHATMSG message as follows:
case DW_WHATMSG:
return DC_INITTERM | DC_ACTIVATE;The remainder of this section looks at the different Windows Help messages that LDLLHandler processes.
The DC_INITTERM flag tells Windows Help that the DLL should receive initialization and termination messages.
After LDLLHandler returns a DC_INITTERM flag, Windows Help sends a DW_INIT message. This message tells LDLLHandler to perform any required initialization operations (such as initializing variables or loading strings). The lParam1 and lParam2 parameters are not used.
If LDLLHandler returns FALSE, Windows Help unloads the DLL and stops sending messages. If LDLLHandler returns TRUE, the DLL remains loaded.
In the DLLDEMO sample, LDLLHandler returns TRUE for this message.
When the user ends a Windows Help session, Windows Help sends a DW_TERM message. This message tells LDLLHandler to perform any required cleanup operations before the DLL is unloaded from memory. The lParam1 and lParam2 parameters are not used, and the return value has no meaning.
The DC_MINMAX flag tells Windows Help that the DLL should receive messages when the user minimizes, maximizes, or resizes the Windows Help window.
Windows Help sends the DLL a DW_MINMAX message if the user minimizes or maximizes the context window.
The lParam1 parameter to DW_MINMAX indicates which operation was performed: 1L for minimized or 2L for maximized.
The lParam2 parameter is not used.
If LDLLHandler returns TRUE for this message, Windows Help continues sending this message throughout the remainder of the session; if LDLLHandler returns FALSE, Windows Help stops sending it.
Windows Help sends the DLL a DW_SIZE message if the user resizes the context window.
The lParam1 message specifies the horizontal size of the window in the low-order word and the vertical size in the high-order word.
The lParam2 parameter is not used.
If LDLLHandler returns TRUE for this message, Windows Help continues sending this message throughout the remainder of the session; if LDLLHandler returns FALSE, Windows Help stops sending it.
The DC_JUMP flag tells Windows Help that the DLL should receive messages when the user executes a jump in the Help file.
Windows Help sends the DLL a DW_STARTJUMP message after the user executes a jump. The parameters to DW_STARTJUMP are not used.
If LDLLHandler returns TRUE for this message, Windows Help continues sending this message throughout the remainder of the session; if LDLLHandler returns FALSE, Windows Help stops sending it.
Windows Help sends the DLL a DW_ENDJUMP message after it displays the jump-destination topic.
The lParam1 parameter specifies the byte offset of that topic within the Help file’s file system. This value can be passed to the LSeekHf function (defined in the DLL.H file) to perform a seek to that topic within the file.
The lParam2 parameter specifies the position of the scroll box in the topic. This value can be used in any of the standard Windows scrolling functions that accept scroll-position parameters.
If LDLLHandler returns TRUE for this message, Windows Help continues sending this message throughout the remainder of the session; if LDLLHandler returns FALSE, Windows Help stops sending it.
Windows Help sends the DLL a DW_CHGFILE message if the user selects Open from the File menu to change .HLP files or jumps to a topic in a different .HLP file. If the message is the result of a jump to a new file, Windows Help sends the DW_CHGFILE message between the DW_STARTJUMP and DW_ENDJUMP messages.
The lParam1 parameter specifies a long pointer to the .HLP filename. The lParam2 parameter is not used.
If LDLLHandler returns TRUE for this message, Windows Help continues sending this message throughout the remainder of the session; if LDLLHandler returns FALSE, Windows Help stops sending it.
The DC_ACTIVATE flag tells Windows Help that the DLL should receive a DW_ACTIVATE message when the user gives either Windows Help or another application the input focus.
The lParam1 parameter to the DW_ACTIVATE message specifies whether Windows Help received (nonzero LONG value) or lost (0L) the input focus. The lParam2 parameter is not used.
If LDLLHandler returns TRUE for this message, Windows Help continues sending this message throughout the remainder of the session; if LDLLHandler returns FALSE, Windows Help stops sending it.