如何用 Win32 SDK 編程創建Tri-pane HTML Help 窗口

 　　HTML Help 使用戶能在一個幫助窗口中使用工具棒、查看目錄和幫助主題。目前，有兩種方法創建 Tri-pane 類型的 HTML Help 窗口：

　　使用 HTML Help Workshop 創建窗口

　　使用 HTML Help API 編程創建窗口

　　本文將介紹如何使用這兩種方法創建Tri-pane HTML Help 窗口。

　　使用預定義窗口

　　在 HTML Help Workshop環境中很容易創建和修改工程的窗口定義，有關窗口定義的其它信息，請參考微軟知識庫文章：Q189084 HOWTO: Create a Tri-pane Window with HTML Help Workshop

　　本文假設在你的應用程序開發工具為 Visual C++，那麼要在自己的程序中使用HTML Help幫助，必須借助於HTML Help提供的 API 函數;要調用這些 API 函數，就必須包含 htmlhelp.h 文件，並且將庫文件 hhctrl.lib 或者 htmlhelp.lib 鏈接到自己的程序代碼中。只要你安裝了HTML Help Workshop環境，這些文件存放在 HTML Help Workshop下的 Include 和 Lib 目錄中。

　　在下面的示范代碼中，sample.chm是一個編譯好的HTML Help幫助文件，其中有一個叫“ mywindow”的窗口定義，下面的代碼示范了如何在一個 MFC 程序中調用 HTML Help API函數：

　　// 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);

　　}

　　使用 HTML Help API

　　為了創建 three-pane 窗口, 必須首先創建和填寫HH_WINTYPE結構。 HH_WINTYPE結構在HtmlHelp.h中定義,詳細說明參見HTML Help Workshop文檔。 以下是一個例子:

　　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:mypathintro.htm";

　　// Table of Contents:

　　m_hhWinType.pszToc = "c:mypathcontents.hhc";

　　// Index:

　　m_hhWinType.pszIndex = "c:mypathindex.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:mypathsample.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);

　　}

　　最後，我想在強調幾點在 Visual C++ 工程中使用 HTML Help API 應注意的事項：

　　一、在調用 HTML Help API 的.cpp源文件中包含“Htmlhelp.h”。安裝HTML Help Workshop後，文件“Htmlhelp.h”被存放在 “HTML Help Workshop”目錄下的 Include 子目錄中。

　　二、在 VC 工程中加入Htmlhelp.lib文件，以便保證編譯器 link 時 API 成功輸出。安裝HTML Help Workshop後，文件“Htmlhelp.lib”被存放在 “HTML Help Workshop”目錄的 lib 子目錄中。

　　三、當 Building VC 工程時, 可能產生以下警告信息(如何使用 Hhctrl.lib 庫文件，則不存在此問題。):

　　......default lib LIBCMT conflicts with use of other libs; use /NODEFAULTLIB:library.

　　如果是這樣的話，可以對VC的編譯環境進行設置，方法是：

　　在“Project”菜單中，選擇 “Settings”->“Link標簽”->“Category 下拉列表”->選“Input”;然後在“Ignore Libraries”編輯框輸入“ LIBCMT”，這樣就屏蔽(Disable)掉缺省的庫搜索 (default library search)，所以，如果使用了缺省庫，就必須顯式列出。

　　經過以上的步驟 Visual C++ 工程應該能成功調用 HTML Help API。