七、允许全文搜索(Full Text

Search)的HTML帮助

在上一节学的 Windows 样式中讲到

Navigation Pane 属性页的时候打住了，这一节将详细详细是如何为 HTML

帮助加上全文搜索功能的。

Navigation Pane

属性页的下方，有一个叫做“Search

Tab”的复选框，我们要做的第一步就是选中它，如下图(以 1.3

版本为例，1.1 版本相似)：

第一步完成后，点击“确定”按钮以确认当前的设置。由于选中了

Search Tab 复选框，这里会打开一个“Resolve window

definition”向导。在该向导的第二步我们需要选中“Search

Tab”和“Compile full-text

Information”两个复选框，如下图所示：

然后一直往下，直到完成。设置就到此结束，然后就该编译了。由于编译过程中需要生成全文搜索信息，也就是字典，常常需要花很长一段时间，尤其是对于内容比较多的帮助文件。对于这种情况，有点象是死机，不过请你耐心的等一等，这的确是一个非常庞大的计算。

八、上下文相关(Context-Sensitive)的HTML帮助

我们的帮助文件已经基本完成了，美中不足的是这个 HTML

帮助还不能提供“上下文相关”的帮助。对于一个程序，虽有帮助文件却不支持上下文相关的帮助，无疑是一大缺憾。下面让我们一起来填补这一点不足。

首先，我们要给每个主题规定一个 ID

号，并且将不同的ID号定义成不同的常量。注意，ID

号和与之对应的常量都是唯一的！我们可以通过 C/C++

语言头文件(.H)做到这一点，在C/C++语言头文件中用 #define

语句定义常量，如：

#define IDH_LEARN_COVER 1

然后，我们还要将帮助文件的各主题映射到不同的常量：

选取“Project”标签，点击“HtmlHelp API

information”按钮，打开“HtmlHelp API

information”对话框；在第二个表页“Alias”中点击“Add”按钮，打开“Alias”对话框，如下图；第一栏中输入ID常量，如上例中的

IDH_LEARN_COVER，在第二栏中选择该ID对应的帮助主题，第三栏是备注内容，对生成的帮助文件没有影响，可以不填；点击“OK”按钮，如此便添加了一条映射信息，重复操作可以添加多条。

然后我们还得让 HTML Help Workshop

在编译时知道ID常量对应的ID数值是多少，也就是说，我们还得把上述创建的C/C++头文件添加到项目中。同样点取“Project”标签中的“HtmlHelp

API information”按钮打开“HtmlHelp API

information”对话框；这次选择第一个表页“Map”；单击该标签中的“Header

file…”即可根据提示选择保存有常量定义的C/C++头文件加入项目。

再进行最后一次编译，一个完整的帮助文件就做好了。至于帮助文件内容是否图文并茂，文本界面是否美观等就看你制作HTML的水平了。

九、在Visual Basic 6中使用HTML

Help

再介绍一下如何在 Visual Basic 6 中使用

HTML 帮助文件(.CHM)。

大家都知道在 Visual Basic 6 中可以通过

ActiveX 控件“Microsoft Common Dialog Control”调用 WinHelp

帮助文件，那么是否可以用同样的方法调用 HTML 帮助文件呢？

I am sorry，答案是否定的。

但是 Visual Basic 6 本身支持 HTML

帮助，我们完全可以直接调用 HTML 帮助文件而不借助于其它任何ActiveX

控件或 Windows API 函数。

你可以在工程属性中设置所需要使用的 HTML

帮助文件，或是在程序中直接将成员变量 App.HelpFile( =

help_file_name)

的值设置为程序所需使用的帮助文件名，如上例应使用语句 App.HelpFile =

"C:\Learn\Learn.chm"

来设置所需的帮助文件——当然，使用这样绝对的路径我并不赞成——你可以改为

App.HelpFile = App.Path +

"Learn.chm"。然后在窗体上添加一个“帮助”按钮，并在该按钮的单击事件中添加打开帮助文件的代码(假设该按钮的Name属性为“cmdHelp”)，相关代码如下：

Private Sub Form_Load()

If Right(App.Path, 1) = "\" Then

App.HelpFile = App.Path + "Learn.chm"

Else

App.HelpFile = App.Path + "\Learn.chm"

End If

End Sub

Private Sub cmdHelp_Click()

cmdHelp.HelpContextID = 1 选定 ID 号为 1 的主题

SendKeys "{F1}"

End Sub

当然，该按钮的HelpContextID属性值可以根据实际情况改为其它数值。OK！你的程序已经添加了美观而又方便的HTML帮助，能为你的程序增色不少呢！

十、在Viusal C++ 6中使用 HTML

Help

在 Visual C++ 6 中调用 HTML

帮助没有现成的函数，需要调用 HtmlHelp() 这个 API

函数。而在调用这个函数之前，还需要在你的工程中加上 HtmlHelp

的库文件和头文件：

1. 指定 HtmlHelp.h 的路径。

选择菜单“Project -> Settings...”，打开“Project

Settings”对话框。

选中“C/C++”选项卡，选择“Category”列表框的内容为“Preprocesor”，在“Additional

include

directories”项中填入包含“HtmlHelp.h”这一文件的路径。

这个文件你可以在你的硬盘上找，如果你安装了“HTML Help

Workshop”，那么在“HTML Help

Workshop”程序目录下有个“Include”目录就是。

2. 指定HtmlHelp.lib的路径。

按照与前面类似的方法，选择“Link”选项卡，选择“Category”为“Input”，在“Additional

library path”中填入包含“HtmlHelp.lib”文件的路径。

同样，在“HTML Help

Workshop”程序目录下的"Lib"目录就是。

3.

指定Lib文件。同样在“Link”选项卡中，选择“Category”为“General”，在“Object/librarie

module”中填入“HtmlHelp.lib”。

4.

最后，将HtmlHelp.h包含在程序中。你可以选择一个合适的位置加入“#include

”这一句话，但我建议你将这句话加入到“Stdafx.h”中。

注：以上所有内容在 MSDN 的“Including

HTML Help Support Files in an

Application”主题中均有介绍，在“搜索”选项卡中输入查找内容为“HtmlHelp”即可找到该主题。

最后是大家都关心的问题，如何在程序中调用 HTML

帮助。

如同在Visual Basic 6中使用HTML

Help一样，首先需要定位帮助文件的位置。假如我们把帮助文件(.chm)放在程序路径下，那么我们该如何去获得程序路径呢？程序大本营上是使用的

API 函数

GetModuleFileName()，例如，我使用以下代码定位程序路径和取文件的完整路径文件名：

CString appPath;

GetModuleFileName(NULL, appPath.GetBuffer(MAX_PATH),

MAX_PATH);

//注：使用该API函数得到的是程序文件完整路径文件名，去掉文件名后才是路径。

appPath.ReleaseBuffer();

int n = appPath.ReverseFind(\\);

CString helpFile;

helpFile = appPath.Left(n);

TCHAR c = helpFile.GetAt(n - 1);

if(c == \\) helpFile += "HtmlHelp.chm";

else helpFile += "\\HtmlHelp.chm";

通过 HtmlHelp 调用帮助文件(.chm)的程序代码如下：

HtmlHelp(NULL, (LPCSTR)helpFile,

HH_DISPLAY_TOPIC, 0);

//直接打开帮助文件的默认主题。

或

HtmlHelp(NULL, (LPCSTR)helpFile,

HH_HELP_CONTEXT, 1);

//打开其中一个主题，实现上下文相关的帮助调用。

如此，在 Visual C++ 6 中，你也能调用

Html 帮助了。这次可是用的 API 函数，也就是说，略为改动你就可以用于

VB，BCB，Delphi……

十一、多个HTML帮助文件的合并(Merge)

运用

假如你单独发行了若干小游戏，并为这些小游戏写了 HTML

帮助。突然有一天，你打算把这些小游戏集合起来搞成一个“游戏乐园”，是不是要把它们的帮助文档源文件(.htm)

再拿出来编译一遍呢？添加 HTML

道是非常方便，可是那一堆目录和索引，难道需要重写吗？——天啊，人生最痛苦的事莫过于此。

不过没关系， 虽然有些时候 Microsoft

的东东的确很差劲，但这次，它想到了——提供了一个非常方便的合并(Merge)

功能，可以把目录、索引甚至全文搜索字典都合并起来。

怎么开始呢？还记得在“设置工程选项(Project

Options)”一节中最后介绍的内容吗？对了，就是从这里开始的：工程选项(Option)

对话框的 Merge Files 属性页。不过在这之前我们需要新建一个 HTML

帮助工程，所有制作将在这个工程中完成。

Merge Files 属性页里只有添加(Add...)

和删除(Remove)

两个按钮，它们的作用我想不必介绍了吧。只需要在这里添加你想要合并的文件，第一步就简单的完成了。不过切记，这个合并不是真正意义上的合并——生成后的

HTML

帮助文件大小和没合并前几乎一样大。因此，发布帮助文档的时候，需要将被合并的

HTML 帮助一起发布。

现在还有一个问题，我编译后找遍了所有链接，始终打不开被合并的帮助文件啊，什么地方搞错了？不要着急，我们才刚刚完成第一步，不过做完这一步，被合并

HTML

帮助文件的索引和全文搜索字典都已经合并进来了，你没找到吗？那是你观察不仔细。

下面，我们要做的第二步是合并目录。

在刚才新建的工程中添加一个目录文件，当然，是新建的。然后右键单击空白处弹出菜单。菜单的前两项都已经在“为帮助文件添加目录(Contents)和索引(Index)”一节有介绍过了，第三项“Insert

File...”才是本节的重头戏。

点击“Insert

File...”菜单项，会弹出一个叫做“Include

File”的对话框，选择你要合并的 HTML

帮助文件(.chm)，然后……还没完，你还需要动手添加如下文字

.....chm::\contents.hhc

前面的 .....chm 是你选择的文件，后面的

::\contents.hhc 是要你动手输入的。其中 contents.hhc

要根据实际你使用的目录文件名来填写，而这个目录文件是 .....chm

的，不是当前工程的。如果还没明白，看看下面注意事项的例图。

编译运行，一切正常，该合并的都合并了，从目录里就能找到被合并帮助文件中的内容。不过，这个样子好象还是有点不对劲啊——下面我来说说需要注意的地方。

第一，我们没有给这个新工程添加主题文件。有什么后果？想想你用

IE 浏览一个不存在的页面时会出现什么样的情况吧。任何一个 HTML

帮助都有一个默认页的，我们新建这个工程也不例外，虽然它合并了其它的

HTML

帮助，但是——还是没有自己的默认页啊。结论：无论如何要给它添加一个主题文件，就算是封面好了。

第二，HTML Help Workshop 在这里有一个

BUG，先看看两张图：

图 1

图 2

发现什么地方不一样了吗？我的本意是想生成图 2

那个的目录树的，Test 是父节点，有两个子节点；而不是象图 1

那样，三个节点在同一个层次。那么它们编译后的结果怎样呢？请看：

图 3

图 4

结果很可笑是不是？由 图 2

的结构编译生成的却是如 图 4

那样错误的目录树。所以，需要你注意的第二点就是：想要目录中的并入文件节点是子某个节点的字节点，在编辑时应该让它和这个节点同层次。

有时候我们会见到一从一个帮助页中链接到另一个帮助文件的例子，比如在

MSDN 中就非常多，这就是怎么实现的呢？其实，这不是 HTML Help

Workshop 的工作，而是主题文件(.htm) 的工作。需要在 HTML

文件中插入一个用打开 HTML 帮助的 ActiveX

控件，这里就不详述了。