如何用 Win32 SDK 编程创建 Tri-pane HTML Help 窗口
如何用 Win32 SDK 编程创建 Tri-pane HTML Help 窗口
编译/zxn
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:\\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);
}
最后，我想在强调几点在 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。
由于时间关系，本文没有附带的范例程序，如果哪位读者有兴趣的话,可以做一个，届时请一定不要忘了共享一份源代码，用以填补本文的不足。我定会重谢！
有关HTML Help的更详细的信息，请访问 HTML Help 在线帮助站点:http://msdn.microsoft.com/workshop/Author/htmlhelp/
