An application makes a Help system available to the user by calling the WinHelp function. The WinHelp function uses the following C-language syntax.
Syntax
BOOL WinHelp (hWnd, lpszHelpFile, wCommand, dwData)
HWND hwnd;/* handle of window requesting help*/
LPCSTR lpszHelpFile;/* address of directory-path string*/
UINT wCommand;/* 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.
Parameters
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 and extension of the Help file that the Help application is to display. The Help file extension (usually .HLP) is required, and a directory path to the Help file is recommended.
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 the main Help window. The name of the secondary window must have been defined in the [WINDOWS] section of the Help project file for the Help file being called. For a description of the possible effects on the main and secondary Help windows, see the following “Comments” section.
wCommand
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 wCommand parameter. For a list of possible values, see the following “Comments” section.
Return Value
WinHelp returns a nonzero value if the function is successful. Otherwise, the return value is zero.
Comments
Before closing the window that requested Help, the application must call WinHelp with wCommand set to HELP_QUIT. Until all applications have done this, Windows Help does not terminate.
The following table describes the possible effects on the main and secondary Help windows when using the >WindowName parameter:
| State at time of call | Effect on window after API call |
| Main | Secondary |
| closed | closed |
| open | open |
The following table shows the possible values for the wCommand parameter and the corresponding formats of the dwData parameter.
| wCommand value
dwData format |
Action |
| HELP_CONTEXT
An unsigned long integer containing the context number for the topic. |
Displays the topic identified by a context number that has been defined in the [MAP] section of the Help project file. |
| HELP_CONTEXTNOFOCUS
An unsigned long integer containing the context number for the topic. |
Displays the topic identified by a context number that has been defined in the [MAP] section of the Help project file. Help does not change the focus to the window displaying the topic. |
| HELP_CONTEXTPOPUP
An unsigned long integer containing the context number for the topic. |
Displays in a pop-up window the topic identified by a context number that has been defined in the [MAP] section of the Help project file. The main Help window is not displayed. |
| HELP_CONTENTS
Ignored; applications should set to 0L |
Displays the topic defined by the CONTENTS option in [OPTIONS] section of the Help project 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 F1 or chooses the Contents button in Help. This call should never be used with HELP_CONTENTS.
If a Help file has two or more Contents topics, the application must assign one as the default. To ensure that the correct Contents topic remains set, the application should call WinHelp with wCommand set to HELP_SETCONTENTS and dwData specifying the corresponding context identifier. Each call to WinHelp should be followed with a command set to HELP_CONTEXT. |
| HELP_POPUPID
A long pointer to a string that contains the context string of the topic to be displayed. |
Displays in a pop-up window the topic identified by a specific context string. The main Help window is not displayed. |
| HELP_KEY
A long pointer to a string that contains a keyword for the requested topic. |
Displays the topic 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, it displays the first topic found. If there is no match, it displays an error message. |
| HELP_PARTIALKEY
A long pointer to a string that contains a keyword for the requested topic. |
Displays the topic 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, it displays the Search dialog box with the topics found listed in the Go To box. If there is no match, it 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 topic identified by a keyword in an alternate keyword table. |
| HELP_COMMAND
A long pointer to a string that contains a Help macro to be executed. |
Executes the Help macro string specified in the dwData parameter. Help must be running and the Help file must be open when Help receives this API message; otherwise, Help may ignore this message. |
| HELP_SETWINPOS
A far pointer to the HELPWININFO structure, as defined in WINDOWS.H. This structure specifies the size and position of the main Help window or a secondary window. |
Positions the Help window according to the data passed. If the Help window is minimized, it is opened first and then positioned. |
| HELP_CLOSEWINDOW
Ignored; applications should set to 0L. |
Closes the main Help window, or a secondary window if specified in the lpszHelpFile argument. |
| HELP_FORCEFILE
Ignored; applications should set to 0L. |
Ensures that the correct Help file is displayed. If the correct Help file is currently displayed, there is no action. If the correct Help file is not displayed, WinHelp opens the correct file and displays the topic defined by the CONTENTS option in the [OPTIONS] section of the Help project file. |
| HELP_HELPONHELP
Ignored; applications should set to 0L. |
Displays the Contents topic of the designated How To Use 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 requested Help, Windows closes the Help application. |
The following table shows the complete list of #defines for WinHelp commands.
| wCommand | Hexadecimal value |
| #define HELP_CONTEXT | 0x0001 |
| #define HELP_QUIT | 0x0002 |
| #define HELP_INDEX | 0x0003 (Windows Help version 3.0) |
| #define HELP_CONTENTS | 0x0003 |
| #define HELP_HELPONHELP | 0x0004 |
| #define HELP_SETINDEX | 0x0005 (Windows Help version 3.0) |
| #define HELP_SETCONTENTS | 0x0005 |
| #define HELP_CONTEXTPOPUP | 0x0008 |
| #define HELP_FORCEFILE | 0x0009 |
| #define HELP_KEY | 0x0101 |
| #define HELP_COMMAND | 0x0102 |
| #define HELP_POPUPID | 0x0104 |
| #define HELP_PARTIALKEY | 0x0105 |
| #define HELP_CLOSEWINDOW | 0x0107 |
| #define HELP_CONTEXTNOFOCUS | 0x0108 |
| #define HELP_MULTIKEY | 0x0201 |
| #define HELP_SETWINPOS | 0x0203 |