WinHelp Function

Declare Function WinHelp Lib "user32.dll" Alias "WinHelpA" (ByVal hWndMain As Long, ByVal lpHelpFile As String, ByVal uCommand As Long, dwData As Any) As Long

Platforms

Windows 95: Supported.
Windows 98: Supported.
Windows NT: Requires Windows NT 3.1 or later.
Windows 2000: Supported.
Windows CE: Not Supported.

Description & Usage

WinHelp opens a Windows Help file or somehow manipulates an open Help file. The precise action taken by the function depends on the value passed as uCommand, but all of them work with Windows Help files. This function is used to provide all access points between an application and its help file(s).

Return Value

If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns a non-zero value.

Visual Basic-Specific Issues

Whenever passing a String or a Long (not including an array of Longs) as dwData, you must preceed it with the ByVal keyword. Do not use the keyword when passing any data structure or an array.

Parameters

hWndMain

In most cases, a handle to the window which is opening the Help file. If uCommand is either HELP_CONTEXTMENU or HELP_WM_HELP, this is a handle to the particular control to open up context-sensitive Help about.

lpszHelp

The filename of the Help file to display. The filename can be followed by the > character and the name of a secondary Help window (defined in the Help file) to open instead of the primary one.

uCommand

Exactly one of the following flags specifying which action the function is to take on the Help file:

HELP_COMMAND: Execute a Help macro or macro string. dwData is a string specifying the name(s) of the Help macro(s) to run. If more than one is specified, separate each name with semicolons.
HELP_CONTENTS: Display the Contents topic of the Help file. dwData must be 0. This flag is obsolete; use the HELP_FINDER flag instead.
HELP_CONTEXT: Display the topic identified by the value passed as dwData.
HELP_CONTEXTMENU: Display the Help topic associated with the window's selected control in a pop-up window. dwData is an array of pairs of Longs (dwords): the first in a pair is a control identifier, and the second in a pair is the context identifier of the associated Help topic. The array's last pair must be two zeros.
HELP_CONTEXTPOPUP: Display the topic identified by the value passed as dwData in a pop-up window.
HELP_FINDER: Display the Help Topics dialog box. dwData must be 0.
HELP_FORCEFILE: Ensure that Windows Help is displaying the correct Help file; if it is not, then display the correct one instead. dwData must be 0.
HELP_HELPONHELP: Display the Help on using Windows Help Help file, which is part of Windows. dwData must be 0.
HELP_INDEX: Same as HELP_CONTENTS.
HELP_KEY: Display the topic in the keyword table that matches the keyword(s) in the string passed as dwData. If multiple matches are found, display the Index topic with each found topic in the Topics Found dialog box. Multiple keywords in dwData must be separated by semicolons.
HELP_MULTIKEY: Display the topic specified by a keyword in an alternative keyword table. dwData is a MULTIKEYHELP structure which specifies a table footnote character and a keyword.
HELP_PARTIALKEY: Same as HELP_KEY, except that to display the index without passing a keyword, pass an empty string as dwData.
HELP_QUIT: Close Windows Help unless other programs currently need it.
HELP_SETCONTENTS: Set which Help topic is considered to be the Contents topic. dwData is the context identifer of the topic to set as the Contents.
HELP_SETINDEX: Same as HELP_SETCONTENTS.
HELP_SETPOPUP_POS: Set the position of a subsequent pop-up window. dwData is a POINT_TYPE structure identifying the coordinates of the upper-left corner of the subsequent pop-up window.
HELP_SETWINPOS: Display the Help window, if it is minimized or hidden, and set its size and position. dwData is a HELPWININFO structure holding the size and position information of the desired Help window.
HELP_TCARD: Indicate that the topic to display is for a training card. This must be combined with another flag.
HELP_WM_HELP: Display the topic for the control identified by hWndMain. dwData is an array of pairs of Longs (dwords): the first in a pair is a control identifier, and the second in a pair is the context identifier of the associated Help topic. The array's last pair must be two zeros.

dwData

Depends on the value of uCommand.

Constant Definitions

Const HELP_COMMAND = &H102
Const HELP_CONTENTS = &H3
Const HELP_CONTEXT = &H1
Const HELP_CONTEXTMENU = &HA
Const HELP_CONTEXTPOPUP = &H8
Const HELP_FINDER = &HB
Const HELP_FORCEFILE = &H9
Const HELP_HELPONHELP = &H4
Const HELP_INDEX = &H3
Const HELP_KEY = &H101
Const HELP_MULTIKEY = &H201
Const HELP_PARTIALKEY = &H105
Const HELP_QUIT = &H2
Const HELP_SETCONTENTS = &H5
Const HELP_SETINDEX = &H5
Const HELP_SETPOPUP_POS = &HD
Const HELP_SETWINPOS = &H203
Const HELP_TCARD = &H8000
Const HELP_WM_HELP = &HC

Example

' This code is licensed according to the terms and conditions listed here.

' Display the Help Topics dialog box of the Help file C:\MyApp\appehelp.hlp.
' The window Form1 is opening Windows Help.
Dim retval As Long  ' return value

' Display the Help file as mentioned above.  Note how the ByVal keyword must
' be used because we're passing a regular Long to it.
retval = WinHelp(Form1.hWnd, "C:\MyApp\apphelp.hlp", HELP_FINDER, ByVal 0)