| BOOL WinHelp(hwnd, lpszHelpFile, fuCommand, dwData) | |||||
| HWND hwnd; | /* handle of window requesting help | */ | |||
| LPCSTR lpszHelpFile; | /* address of directory-path string | */ | |||
| UINT fuCommand; | /* type of help, */ | ||||
| DWORD dwData; | /* additional data, */ | ||||
The WinHelp function starts Windows Help (WINHELP.EXE) and passes optional data indicating the nature of the help requested by the application. The application specifies the name and, where required, the path of the help file that the Help application is to display. For information about creating and using help files, see Microsoft Windows Programming Tools.
hwnd
Identifies the window requesting Help. The WinHelp function uses this handle to keep track of which applications have requested Help.
lpszHelpFile
Points to a null-terminated string containing the path, if necessary, and the name of the help file that the Help application is to display.
The filename may be followed by an angle bracket (>) and the name of a secondary window if the topic is to be displayed in a secondary window rather than in the primary window. The name of the secondary window must have been defined in the [WINDOWS] section of the Help project (.HPJ) file.
fuCommand
Specifies the type of help requested. For a list of possible values and how they affect the value to place in the dwData parameter, see the following Comments section.
dwData
Specifies additional data. The value used depends on the value of the fuCommand parameter. For a list of possible values, see the following Comments section.
The return value is nonzero if the function is successful. Otherwise, it is zero.
Before closing the window that requested the help, the application must call WinHelp with fuCommand set to HELP_QUIT. Until all applications have done this, Windows Help does not terminate.
The following table shows the possible values for the fuCommand parameter and the corresponding formats of the dwData parameter:
| fuCommand | dwData | Action |
| HELP_CONTEXT | An unsigned long integer containing the context number for the topic. | Displays Help for a particular topic identified by a context number that has been defined in the [MAP] section of the .HPJ file. | |
| HELP_CONTENTS | Ignored; applications should set to 0L. | Displays the Help contents topic as defined by the Contents option in the [OPTIONS] section of the .HPJ file. | |
| HELP_SETCONTENTS | An unsigned long integer containing the context number for the topic the application wants to designate as the Contents topic. | Determines which Contents topic Help should display when a user presses the F1 key. | |
| HELP_CONTEXTPOPUP | An unsigned long integer containing the context number for a topic. | Displays in a pop-up window a particular Help topic identified by a context number that has been defined in the [MAP] section of the .HPJ file. | |
| HELP_KEY | A long pointer to a string that contains a keyword for the desired topic. | Displays the topic found in the keyword list that matches the keyword passed in the dwData parameter if there is one exact match. If there is more than one match, displays the Search dialog box with the topics listed in the Go To list box. If there is no match, displays the Search dialog box. | |
| HELP_PARTIALKEY | A long pointer to a string that contains a keyword for the desired topic. | Displays the topic found in the keyword list that matches the keyword passed in the dwData parameter if there is one exact match. If there is more than one match, displays the Search dialog box with the topics found listed in the Go To list box. If there is no match, displays the Search dialog box. If you just want to bring up the Search dialog box without passing a keyword (the third result), you should use a long pointer to an empty string. | |
| HELP_MULTIKEY | A long pointer to the MULTIKEYHELP structure, as defined in WINDOWS.H. This structure specifies the table footnote character and the keyword. | Displays the Help topic identified by a keyword in an alternate key word table. | |
| HELP_COMMAND | A long pointer to a string that contains a Help macro to be executed. | Executes a Help macro. | |
| HELP_SETWINPOS | A long pointer to the HELPWININFO structure, as defined in WINDOWS.H. This structure specifies the size and position of the primary Help window or a secondary window to be displayed., Displays the Help window if it is minimized or in memory, and positions it according to the data passed. | ||
| HELP_FORCEFILE | Ignored; applications should set to 0L. | Ensures that WinHelp is displaying the correct Help file. If the correct Help file is currently displayed, there is no action. If the incorrect Help file is displayed, WinHelp opens the correct file. | |
| HELP_HELPONHELP | Ignored; applications should set to 0L. | Displays the Contents topic of the designated Using Help file. | |
| HELP_QUIT | Ignored; applications should set to 0L. | Informs the Help application that Help is no longer needed. If no other applications have asked for Help, Windows closes the Help application. | |
The MULTIKEYHELP structure has the following form:
typedef struct tagMULTIKEYHELP { /* mkh */
UINT mkSize;
BYTE mkKeylist;
BYTE szKeyphrase[1];
} MULTIKEYHELP;For a full description of this structure, see the Microsoft Windows Programmer's Reference, Volume 3.