XL5: Using the WinHelp Function with Visual Basic

The information in this article applies to:

• Microsoft Excel for Windows, versions 5.0, 5.0c

SUMMARY

This article describes how to use the Microsoft Windows version 3.1 WinHelp function with Visual Basic, Applications Edition, to use custom Help files with applications you create. This article assumes that you are familiar both with Visual Basic, Applications Edition, and with creating custom Help files.

MORE INFORMATION

Visual Basic Code Example

Microsoft provides examples of Visual Basic procedures for illustration only, without warranty either expressed or implied, including but not limited to the implied warranties of merchantability and/or fitness for a particular purpose. This Visual Basic procedure is provided 'as is' and Microsoft does not guarantee that it can be used in all situations. Microsoft does not support modifications of this procedure to suit customer requirements for a particular purpose. Note that a line that is preceded by an apostrophe introduces a comment in the code--comments are provided to explain what the code is doing at a particular point in the procedure. Note also that an underscore character (_) indicates that code continues from one line to the next. You can type lines that contain this character as one logical line or you can divide the lines of code and include the line- continuation character. For more information about Visual Basic for Applications programming style, see the "Programming Style in This Manual" section in the "Document Conventions" section of the "Visual Basic User's Guide."

The following examples include:

1. A global declaration section that demonstrates the declaration for the WinHelp function and includes predefined constants recognized by this function.

2. A sample procedure called SHOWHELPTOPIC that demonstrates how to display a specific topic within a Help file.

3. A sample procedure called HELPONHELP that demonstrates how to display the contents of the designated "Using Help" file.

4. A sample procedure called KEYWORDSEARCH that demonstrates how to start the Windows Help search engine to search for a specific keyword.

5. A sample procedure called HELPCONTENTS that demonstrates how to display the Contents topic in a help file.

6. A sample procedure called QUITHELP that demonstrates how to quit help.

7. A sample procedure called RUNHELPMACRO that demonstrates how to execute a WinHelp macro.

'---------------------------------------------------------------------
'GLOBAL DECLARATION SECTION
'---------------------------------------------------------------------

'The following two lines must be entered into a single line in your Visual
'Basic module.

     ByVal HelpFile$, ByVal wCommand As Integer, ByVal dwData As Any)

'Predefined Help Constants
Const HELP_CONTEXT = &h1      'Display topic in ulTopic
Const HELP_QUIT = &h2         'Terminate help
Const HELP_INDEX = &h3        'Display index
Const HELP_CONTENTS = &h3     'Display Contents for help
Const HELP_HELPONHELP = &h4   'Display help on using help
Const HELP_SETINDEX = &h5     'Set the current Index for multiindex help

Const HELP_FORCEFILE = &h9    'Ensure that help displays correct file
Const HELP_KEY = &h101        'Display topic for keyword in dwData
Const HELP_COMMAND = &h102    'Execute a Winhelp macro

'----------------------------------------------------------------------
'SHOWHELPTOPIC PROCEDURE
'Displays Help for a particular topic identified by a context number
'that has been defined in the [MAP] section of the .HPJ file.
'dwData is an unsigned long integer containing the context number
'for the topic.
'----------------------------------------------------------------------

Sub ShowHelpTopic()

    ContextID = 2697
    WinHelp 0, "c:\excel\macrofun.hlp", HELP_CONTEXT, ContextID
End Sub



'----------------------------------------------------------------------
'HELPONHELP PROCEDURE
'Displays the Contents topic of the designated Using Help file.
'dwData is ignored and should be set to zero length
'----------------------------------------------------------------------

Sub HelponHelp()
    WinHelp 0, "c:\excel\macrofun.hlp", HELP_HELPONHELP, ""
End Sub



'----------------------------------------------------------------------
'KEYWORDSEARCH PROCEDURE
'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.
'dwData is a string that contains a keyword for the desired topic.
'-----------------------------------------------------------------------

Sub KeywordSearch()
    WinHelp 0, "c:\excel\macrofun.hlp", HELP_PARTIALKEY, "WHILE-NEXT loops"
End Sub



'-----------------------------------------------------------------------
'HELPCONTENTS PROCEDURE
'Displays the Help contents topic as defined by the Contents option
'in the [OPTIONS] section of the .HPJ file.
'dwData is ignored and should be set to 0 length.
'-----------------------------------------------------------------------

Sub HelpContents()
    WinHelp 0, "c:\excel\macrofun.hlp", HELP_CONTENTS, ""
End Sub



'-----------------------------------------------------------------------
'QUITHELP PROCEDURE
'Informs the Help application that Help is no longer needed.
'If no other applications have asked for Help, Windows closes the Help
'application.
'dwData is ignored and should be set to zero length.
'-----------------------------------------------------------------------

Sub QuitHelp()
    WinHelp 0, "c:\excel\macrofun.hlp", HELP_CONTENTS, ""
    WinHelp 0, "c:\excel\macrofun.hlp", HELP_QUIT, ""
End Sub



'-----------------------------------------------------------------------
'RUNHELPMACRO PROCEDURE
'Executes a Help macro.
'dwdata is a string that contains a Help macro to be executed.
'-----------------------------------------------------------------------

Sub RunHelpMacro()
    WinHelp 0, "c:\excel\macrofun.hlp", HELP_CONTENTS, ""
    WinHelp 0, "c:\excel\macrofun.hlp", HELP_COMMAND, "CopyDialog()"
End Sub

REFERENCES

For more information on using the Windows API: "Microsoft Windows 3.1 Software Development Kit"

For more information regarding creating custom help files: "Microsoft Windows 3.1 Programming Tools", Microsoft Press, pages 21-66