HOWTO: Programatically Create a Tri-pane HTML Help Window

ID: Q183191

The information in this article applies to:

SUMMARY

HTML Help enables you to use a three-pane help window. This allows you to view the toolbar, contents, and help topics in one help window. There are two ways to create a three-pane HTML Help window from a Visual C++ application:

  1. Use the HTML Help Workshop to create a window definition.


  2. Programmatically create a window definition using the HTML Help API.


This article demonstrates how to use both of these methods.


MORE INFORMATION

Using Predefined Window Definitions



The HTML Help Workshop can easily create and modify Window Definitions within an HTML Help project. For additional information, please see the following article in the Microsoft Knowledge Base:
Q189084 HOWTO: Create a Tri-pane Window with HTML Help Workshop
In a Visual C++ application, start the HTML Help window by using the HTML Help API. To use the HTML Help API, Visual C++ applications must include htmlhelp.h and a link to hhctrl.lib. These files can be found in the HTML Help Workshop's \Include and \Lib directories, respectively.

In the following sample code, sample.chm is an HTML Help file that contains a window definition called "mywindow". This example invokes HTMLHelp in MFC's CFrameWnd::OnHelp message handler: 

   // CMainFrame message handler
   void CMainFrame::OnHelp()
   {
      // display the topic "intro.htm" in the window defined
      // in the HTML Help Workshop
      HtmlHelp(m_hWnd,"sample.chm::\\intro.htm>mywindow",
         HH_DISPLAY_TOPIC,0);
   }

Using the HTML Help API

To create the three-pane window programmatically, you must first create the HH_WINTYPE structure and fill in all of its fields. The HH_WINTYPE structure is defined in HtmlHelp.h and documented in the HTML Help Workshop. Following is an example:

Sample Code


   /////////////////////////////////////////// 
   // Create an HH_WINTYPE structure.
   {
   HH_WINTYPE m_hhWinType;
   // Initialize all structure members to zero.
   ZeroMemory(&m_hhWinType, sizeof(HH_WINTYPE));
   // Define a custom message for use with idNotify.
   // You are responsible for ensuring that this ID
   // does not conflict with other Windows/MFC messages.
   #define IDD_HELPTAB 69999

   // Set the size of the structure.
   m_hhWinType.cbStruct = sizeof(HH_WINTYPE);

   // Set up the properties of the HTML window:
   // tripane window, sync topic with index/TOC, and so forth.
   // NOTE: fsValidMembers - HHWIN_PARAM_PROPERTIES must be set.
   m_hhWinType.fsWinProperties = HHWIN_PROP_TRI_PANE |
      HHWIN_PROP_AUTO_SYNC;

   // Put BACK, HOME, FORWARD, and EXPAND buttons on toolbar pane.
   // NOTE: fsValidMembers - HHWIN_PARAM_TB_FLAGS must be set.
   m_hhWinType.fsToolBarFlags = HHWIN_BUTTON_BACK |
      HHWIN_BUTTON_HOME | HHWIN_BUTTON_FORWARD |
      HHWIN_BUTTON_EXPAND;

   // The file is in the right pane. The full path is not needed.
   m_hhWinType.pszFile = "intro.htm";

   // Full Paths or CHM locations of various files (if used).
   // To specify that a file is within a CHM, use the following
   // syntax: "CHMFileName.chm::\\FileName.xxx"
   // Home Page:
   m_hhWinType.pszHome = "c:\\mypath\\intro.htm";
   // Table of Contents:
   m_hhWinType.pszToc = "c:\\mypath\\contents.hhc";
   // Index:
   m_hhWinType.pszIndex = "c:\\mypath\\index.hhk";
   // Expansion width of navigation pane (left pane):
   // NOTE: fsValidMembers - HHWIN_PARAM_NAV_WIDTH must be set.
   m_hhWinType.iNavWidth = 175;

   // Initial display state:
   // NOTE: fsValidMembers - HHWIN_PARAM_SHOWSTATE must be set.
   m_hhWinType.nShowState = SW_RESTORE;

   // TOC should be activated.
   // NOTE: fsValidMembers - HHWIN PARAM_CUR_TAB must be set.
   m_hhWinType.curNavType = HHWIN_NAVTYPE_TOC;

   // Tabs on top.
   // NOTE: fsValidMembers - HHWIN_PARAM_TABPOS must be set.
   m_hhWinType.tabpos = HHWIN_NAVTAB_TOP;

   // ID to use in WPARAM in WM_NOTIFY:
   m_hhWinType.idNotify = IDD_HELPTAB;

   // Title of Help Window:
   m_hhWinType.pszCaption= "My Title";

   // Indicate which fields in structure are valid.
   m_hhWinType.fsValidMembers = HHWIN_PARAM_STYLES |
   HHWIN_PARAM_PROPERTIES | HHWIN_PARAM_RECT |
   HHWIN_PARAM_TB_FLAGS | HHWIN_PARAM_NAV_WIDTH |
   HHWIN_PARAM_SHOWSTATE | HHWIN_PARAM_TABPOS |
   HHWIN_PARAM_CUR_TAB;

   // Specify the name of the window definition.
   m_hhWinType.pszType = "MyWindowName";

   // This call creates the new type from the values in
   // the HH_WINTYPE structure. This example assumes that
   // a valid CHM file, "sample.chm", exists.
   HtmlHelp(m_hWnd, "c:\\mypath\\sample.chm",
      HH_SET_WIN_TYPE, (DWORD) &m_hhWinType);
   }

   // Display the default topic in the window that was defined above
   // MFC's CFrameWnd::OnHelp message handler.
   void CMainFrame::OnHelp()
   {
   HtmlHelp(m_hWnd, "sample.chm>MyWindowName",
      HH_DISPLAY_TOPIC,0);
   }


REFERENCES

For additional information, please see the following article in the Microsoft Knowledge Base:

Q186907 HOWTO: Set Up Visual C++ to Use the HTML Help API


HTML Help Workshop Help; topic: HTMLHelp API Reference; Modifying the default Help window;

HTML Help Web Site:
http://www.msdn.microsoft.com/workshop/author/htmlhelp

Additional query words: 


Keywords          : kbHTMLHelp 
Version           : WINDOWS:1.21
Platform          : WINDOWS 
Issue type        : kbhowto

Last Reviewed: July 30, 1999