Table of Contents
- About the Authors
- About the Contributors
- Tell Us What You Think!
- How to Use This Book
- What You Need to Use This Book
- What's New in Visual C++ 6.0
- Contacting the Main Author
- Part I: Introduction
- Chapter 1. The Visual C++ 6.0 Environment
- Part II: MFC Programming
- Chapter 2. MFC Class Library Overview
- Chapter 3. MFC Message Handling Mechanism
- Chapter 4. The Document View Architecture
- Chapter 5. Creating and Using Dialog Boxes
- Chapter 6. Working with Device Contexts and GDI Objects
- Chapter 7. Creating and Using Property Sheets
- Chapter 8. Working with the File System
- Chapter 9. Using Serialization with File and Archive Objects
- Part III: Internet Programming with MFC
- Chapter 10. MFC and the Internet Server API (ISAPI)
- Chapter 11. The WinInet API
- Chapter 12. MFC HTML Support
- Part IV: Advanced Programming Topics
- Chapter 13. Using the Standard C++ Library
- Chapter 14. Error Detection and Exception Handling Techniques
- Chapter 15. Debugging and Profiling Strategies
- Chapter 16. Multithreading
- Chapter 17. Using Scripting and Other Tools to Automate the Visual C++ IDE
- Part V: Database Programming
- Chapter 18. Creating Custom AppWizards
- Chapter 19. Database Overview
- Chapter 20. ODBC Programming
- Chapter 21. MFC Database Classes
- Chapter 22. Using OLE DB
- Chapter 23. Programming with ADO
- Part VI: MFC Support for COM and ActiveX
- Chapter 24. Overview of COM and Active Technologies
- Chapter 25. Active Documents
- Chapter 26. Active Containers
- Chapter 27. Active Servers
- Chapter 28. ActiveX Controls
- Part VII: Using the Active Template Library
- Chapter 29. ATL Architecture
- Chapter 30. Creating COM Objects Using ATL
- Chapter 31. Creating ActiveX Controls Using ATL
- Chapter 32. Using ATL to Create MTS and COM+ Components
- Part VIII: Finishing Touches
- Chapter 33. Adding Windows Help
- Part IX: Appendix
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().
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.
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:
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.