Visual C++ 6 Unleashed

Visual C++ 6 Unleashed

By and

Calling WinHelp from Your Applications

Now that you have created a working help file, you need to be able to access the help file from within your application. This is done by using the ::WinHelp() function, although you will also take a look at some of the MFC functions that simplify calling ::WinHelp().

::WinHelp()

The Win32 API provides access to many different features of the WinHelp system via a single function call,::WinHelp(). The prototype for ::WinHelp() is shown here:

BOOL WinHelp( HWND hWndMain, LPCTSTR lpszHelp,
   UINT uCommand, DWORD dwData );

The hWndMain parameter should be passed as a handle of the window that is requesting help, and the lpszHelp parameter should contain the path to the help file that is to be used.

The uCommand parameter is used to specify the operation that will be performed, and dwData is used in different ways depending on the value of uCommand. Some of the most commonly used values of uCommand are shown here:

  • HELP_FINDER: Displays the Help Topics dialog box, containing the table of contents for the help file.
  • HELP_HELPONHELP: Displays help information on using WinHelp. The file winhlp32.hlp must be available for this.
  • HELP_CONTEXT: Displays a topic identified by a context ID that appears in the [MAP] section of the .hpj file. dwData should contain the context ID.
  • HELP_CONTEXTPOPUP: This is similar to HELP_CONTEXT, but the help topic is displayed as a pop-up window. dwData should contain the context ID.
  • HELP_QUIT: This tells WinHelp to close all WinHelp windows. dwData is ignored.

For more on additional commands for use with ::WinHelp(), see the online help in Developer Studio.

Using Help with MFC

The Microsoft Foundation Classes provide easy access to the WinHelp system, particularly if you have created your application with AppWizard.

CWinApp::WinHelp()

The CWinApp class supports a WinHelp() method that can simplify the process of displaying help. The prototype for CWinApp::WinHelp() is shown here:

virtual void WinHelp( DWORD dwData, UINT nCmd = HELP_CONTEXT );

Basically, this function simply wraps the Win32 API ::WinHelp() function, although MFC will keep track of the window handle and help file path for you. The values of dwData and nCmd should be the same as the values of dwData and uCommand shown previously for ::WinHelp().

MFC Help Handlers

If you have created your MFC application with AppWizard and selected the context-sensitive help option, you will notice that several handlers have been added to the message map for your applications. These are used to handle the messages that are generated by the commands on the Help menu that AppWizard generates. An example of these message map entries is shown here:

ON_COMMAND(ID_HELP_FINDER, CFrameWnd::OnHelpFinder)
ON_COMMAND(ID_HELP, CFrameWnd::OnHelp)
ON_COMMAND(ID_CONTEXT_HELP, CFrameWnd::OnContextHelp)
ON_COMMAND(ID_DEFAULT_HELP, CFrameWnd::OnHelpFinder)

The ID_HELP_FINDER message is sent by the Help Topics command on the Help menu. The handler function, OnHelpFinder(), simply calls CWinApp::WinHelp(), as shown here:

AfxGetApp()->WinHelp(0L, HELP_FINDER);

The ID_HELP message is sent when the user presses F1. The OnHelp() function will attempt to display a help topic that is relevant to the current window. If none is found, the default help topic will be displayed.

The ID_CONTEXT_HELP message is sent when the user enters help mode by pressing shift+F1 or clicks the Help mode tool. The OnContextHelp() handler places the application in Help mode. Once in Help mode, user input is handled differently. MFC will try to display help for any controls clicked, rather than send the command message for the control.

When no help topics are found for a particular context, the ID_DEFAULT_HELP message is sent. MFC handles this by displaying the table of contents for the help file.

In addition, the CWinApp class supports the OnHelpUsing() method, which will display help on using the WinHelp interface. You can easily add support for this to your application by adding a menu item with the ID of ID_HELP_USING and adding the following message map entry:

ON_COMMAND( ID_HELP_USING, OnHelpUsing )

In most cases, it is easiest to use the predefined command IDs for requesting help and simply use the message map entries to call the appropriate handlers in the CWinApp class. However, you might want to call CWinApp::WinHelp() directly from your application in some cases.

Share ThisShare This