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

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)

Category

Help

Go back to the alphabetical Function listing.
Go back to the Reference section index.


Last Modified: August 13, 1999
This page is copyright © 1999 Paul Kuliniewicz. Copyright Information Revised October 29, 2000
Go back to the Windows API Guide home page.
E-mail: vbapi@vbapi.com Send Encrypted E-Mail
This page is at http://www.vbapi.com/ref/w/winhelp.html