第二十三章：创建图形方式帮助

通过添加图形方式“帮助”文件（HTML 形式或 WinHelp 帮助），可对应用程序进行一些专业级的修饰。图形方式的帮助中可以包含图形和经过格式编排的文本，而 .DBF 样式帮助不包含图形，只有单一字体的文本。有关创建 .dbf 样式帮助的详细内容，请参阅第二十四章“创建 .DBF 样式帮助”。

注释 Microsoft Visual Studio 6.0 包含有创建 HTML 帮助文件的 Microsoft HTML Help Workshop(Hhw.exe)。不包含创建 WinHelp 文件的 Microsoft Help Workshop 4.0(Hcw.exe)。上一版的 Microsoft Visual FoxPro 包含 Microsoft Help Workshop 4.0。

本章内容要点：

HTML 帮助
WinHelp 4.0

HTML 帮助

HTML 帮助提供了 Winhelp 的许多特性的同时，并增加了以下特性：

支持 HTML。
支持 ActiveX、Java和书写脚本（Javascript 和 Microsoft Visual Basic Script）等特性。
支持 HTML 的图象格式（.jpg 、.gif 、.png）。
提供从“帮助”主题中跳转到 Internet 的站点的功能。
提供查看“帮助”主题的 HTML 代码的功能。

HTML 帮助由 Microsoft HTML Help Workshop 创建，此软件包含在 Visual Studio 中并独立于 Visual FoxPro。HTML Help Workshop 提供一个完整的HTML 帮助创作系统，并且包含有向后兼容的功能，此功能可以很方便地从已有的 Winhelp 项目中创建 HTML 帮助文件。如果要创建用于您自己的应用程序的 HTML 帮助文件，请查阅 HTML Help Workshop 的联机帮助。

在 ...\Samples\Vfp98\Solution\Help 目录中包含一个 HTML 帮助项目的示例，此示例是 Solutions 示例的一部分。HTML 帮助示例包含以下文件：

文件	说明
Solution.chm	已编译的帮助文件。
Solution.hhp	项目文件 - 一个文本文件，此文件将所有构成帮助项目的元素以及包含有编译后的帮助文件的显示方式的信息组织在一起。
Solution.hhk	索引文件 - 包含索引条目（关键字）。
Solution.hhc	内容文件表。
Solution.ali	用于支持上下文相关帮助功能的别名文件。将 Product ID 映象为帮助主题。
Solution.hh	用于支持上下文相关帮助功能的头文件。包括 Product ID。
Solution.chi	当您希望访问仍然留在 CD-ROM 上的 .chm 文件时需要使用的索引文件，这种情形和 MSDN Library的情形相同。为了快速地访问帮助文件，.chi 文件允许将一定的定位信息安装在硬盘上，而将主要的内容留在 CD-ROM 上。.chi 文件不能在无 CD-ROM 的情况下使用。当没有使用 .chi 文件时，所有在 .chi 文件中的信息保留在 .chm 文件中。
MSDN_ie3.css	级联式样式表。
MSDN_ie4.css	级联式样式表。
FileName.htm	源内容文件。
FileName.gif	源图象文件。

计划对联机帮助的访问

除了创建一个包含有用信息的 HTML帮助文件之外，还需要向应用程序用户提供访问帮助的途径。有三种方法可以访问帮助：

帮助菜单 — 显示在应用程序主菜单栏上的一个菜单。
上下文相关帮助 — 当选定某个对象、控件或菜单选项并按 F1 键（或您指定的其他键）时显示的帮助。
“这是什么？”帮助 — 当用户寻求关于特定对象或控件的帮助时出现的帮助信息。

实现 HTML 帮助与实现 WinHelp 很相似。以下的章节将介绍如何实现应用程序的 HTML 帮助。

计划一个帮助菜单

一个典型的帮助菜单包含可以访问帮助系统的命令。我们强烈建议您的帮助菜单上应该有一个打开HTML 帮助系统的命令。除此之外，您可以在帮助菜单上放置附加命令来提供系统信息或者应用程序的版权及版本号信息等。

添加上下文的相关性

“上下文相关帮助”允许用户随时方便地访问与他们在应用程序中所做所见相关的帮助主题。例如，如果用户正在查看一个数据输入表单，“上下文相关帮助”能够提供与那个数据输入表单相关的帮助主题。

您自己决定应用程序中实施的“上下文相关帮助”的详细层次。例如，您可以为一个表单关联一个上下文相关帮助主题，或者您可以为表单上每一个控件和字段关联一个更详细的帮助主题。

按 F1 键是访问“上下文相关帮助”的最常用的方法，但是您也可以使用 ON KEY LABEL 指定任意键来激活“上下文相关帮助”。

在“表单”上使用“上下文相关帮助”

若要实施“上下文相关帮助”，必须为您的应用程序指定帮助，然后把特定的帮助主题与应用程序中不同的对象关联起来。

若要添加“上下文相关帮助”

为应用程序指定一个帮助。
为希望提供“上下文相关帮助”的每一个对象指定一个帮助主题。

指定一个帮助文件

通过在代码中包含 SET HELP TO file 命令(其中 file 是帮助文件的名字)，可以决定应用程序能访问哪些帮助文件。例如，如果帮助文件名为 Myhelp.chm，您可以使用下面的命令：

SET HELP TO Myhelp.chm

这个命令一般包含在应用程序主程序的设置代码中。

指定帮助主题

可以向 Visual FoxPro 应用程序中的特定对象指定一个帮助主题。

若要向一个对象指定一个帮助主题

在“设计”状态下打开想为之指定“上下文相关帮助”的对象，例如一个表单、控件或工具栏。
查看该对象的属性。
把 HelpContextID 属性设置为代表 HTML 帮助文件中特定主题的编号。

有关把 HTML 帮助主题映射为上下文 ID 编号的详细内容，请查阅 HTML Help Workshop 的联机帮助。

注释若要向菜单标题或菜单命令指定帮助标题，必须在与菜单标题或菜单命令相关联的过程中包含 SET TOPIC TO 命令。

实现“这是什么？”帮助

“这是什么？”帮助类似于上下文相关帮助，因为它提供对当前具有焦点的特定对象或控件的帮助。

对于 WinHelp，帮助并不激活帮助应用程序然后在默认大小的“帮助”窗口中显示帮助主题，而是在一个弹出式小窗口显示帮助主题，然后用户单击屏幕任意位置时该窗口消失。“这是什么？”帮助在提供简单提示型描述或特定控件定义时很有用。

与 WinHelp 不同，HTML 的“这是什么？”帮助显示在完全为默认大小的帮助窗口中。

要把“这是什么？”帮助与特定表单、表单控件或工具栏关联起来，把它们的 WhatsThisHelpID 属性设置为代表帮助特定主题的编号。

使用下列属性和方法程序来实现“这是什么？”帮助：

属性	说明
WhatsThisHelp	设置表单的该属性为真(.T.)，可以启用表单以及表单上任意控件的“这是什么？”帮助。
WhatsThisButton	如果希望表单的标题栏显示一个“这是什么？”按钮，设置属性为真(.T.）。
WhatsThisHelpID	对一个表单、控件或工具栏，把该属性设置为对应于 HTML 帮助文件中某个主题的 ID 编码。
WhatsThisMode	使用这个方法程序可以显示“这是什么？”帮助，问号代表鼠标指针然后启动“这是什么？”帮助模式。单击一个对象将显示该对象 WhatsThisHelpID 属性指定的帮助主题。

若要实现“这是什么？”帮助

在设计模式下打开想启用“这是什么？”帮助的表单。
把表单的 WhatsThisHelp 属性设置为“真”(.T.)。
若要在表单标题中显示一个“这是什么？”帮助按钮，把表单的 WhatsThisButton 属性设置为“真”(.T.)。
若要把一个“这是什么？”帮助主题与该表单关联起来，把表单的 WhatsThisHelpID 属性设置为与帮助中主题相对应的 ID 编码。
若要把一个“这是什么？”帮助主题与表单上特定控件关联在一起，选择控件然后把它的 WhatsThisHelpID 属性设置为与 HTML 帮助文件中的主题相对应的 ID 编码。

编程实现帮助特性

对应用程序编程，这样用户就可以访问 HTML 帮助系统。虽然一个 HTML 帮助系统可能包含一个或多个独立的文件，但从用户的角度看来，帮助只是应用程序的一部分。

可以使用 SET HELP TO 及 SET TOPIC TO 命令编写 Visual FoxPro 应用程序使其使用图形或 .dbf 样式的帮助。SET HELP TO 指定了应用程序所用的自定义帮助。SET TOPIC TO 为自定义帮助中的主题设置识别关键字。

保留 F1

当用户在应用程序中按 F1 键时，Visual FoxPro 会显示一个“上下文相关帮助”主题。为了做到这一点，可在帮助表中为需要“上下文相关帮助”的主题指定一个帮助相关 ID，并把此值赋给表单或控件的 HelpContextID 属性。当表单或控件获得焦点并且用户按 F1 键时，Visual FoxPro 就会显示该主题。

注释在默认情况下 F1 键是可用作上下文相关帮助激活键的。因为这是一个公认的激活上下文帮助的标准，因此并不推荐您重定义这个键。

在表单中包含“帮助”按钮

如果在表单中添加“帮助”按钮，用户可以更方便地访问帮助信息。如果用户是个新手，那么更应该考虑添加一个“帮助”按钮。

若要设置上下文相关帮助并添加一个“帮助”按钮

在表单的 Init 事件中，将表单中所有对象的 HelpContextID 属性都设置为该帮助主题的 ID 值。例如，如果该值为 7，可用如下命令：
```
THIS.SetAll("HelpContextID", 7)
```
在表单中添加一个命令按钮。
把命令按钮的 Caption 属性设置为“帮助”。
在命令按钮的 Click 事件中，添加下面的命令：
```
HELP ID THIS.HelpContextID
```

提示可把“帮助”按钮保存为一个类，这样就可以方便地把它添加到任何表单中。有关把对象保存成类的详细内容，请参阅第九章“创建表单”。

发布已编译的 HTML 帮助系统

除了为您的 HTML 帮助系统创建 .chm 文件之外，您还可以使用一个免费发布的安装程序—Hhupd.exe，安装或注册下列 HTML 帮助的运行时刻组件。您的用户电脑中必须安装 Internet Explorer 或者 Internet Explorer 运行时刻引擎。

组件名称	说明
Hhctrl.ocx	HTML Help ActiveX 控件
Itss.dll	处理编译过的 HTML 的动态链接库
Itircl.dll	完整文字查找动态链接库
Hh.exe	HTML 帮助查看器

这个安装程序可以在 Redist 文件夹中找到，Redist 文件夹位于安装 HTML Help Workshop 的文件夹中。此安装程序可以从其他安装程序中调用，并且可以被设置为“静态”模式运行，这样就避免了对您已经创建完成的安装程序的干扰。如果需要完整的命令行选项列表，运行 Hhupd.exe/?。

WinHelp 4.0

使用 Microsoft Help Workshop，此软件在 Visual FoxPro 的前一版本中提供，创建图形样式 Windows 帮助文件。Help Workshop 中包含了“帮助指南”，“帮助指南”（Hcw.hlp）是一个图形样式的帮助文件，包含了创建一个强大的帮助系统所需的许多信息。

选择帮助特性

WinHelp 系统可具有下列部分或所有特征：

一个目录页面，提供帮助系统中主题的层次结构的视图。
一个基于您所提供的关键字的索引，引导用户到特定内容。
全文本查找功能，允许用户通过特定字及短语在帮助中查找信息。
具有多种字体、字体大小和颜色的文本。
图形，包括多种分辨率的位图。
宏，扩展帮助系统的功能，使操作自动化。
热点，这是一个鼠标敏感区域，可让用户跳转到相关的主题；弹出式窗口用于显示附加文本；添加到帮助系统的宏命令。
段式超图形，即具有一个或多个热点的图形。
辅助窗口。
可定制的菜单。
Windows 图元文件格式的图形
.DLL 文件

计划对联机帮助的访问

除了创建一个包含有用信息的 WinHelp 文件之外，还需要向应用程序用户提供访问帮助的途径。有三种方法可以访问帮助：

帮助菜单 — 显示在应用程序主菜单栏上的一个菜单。
上下文相关帮助 — 当选定某个对象、控件或菜单选项并按 F1 键（或您指定的其他键）时显示的帮助。
“这是什么？”帮助 — 当用户寻求关于特定对象或控件的帮助时出现的简单弹出式提示。

计划一个帮助菜单

一个典型的帮助菜单包含可以访问帮助主题的命令。WinHelp 4.0 的访问特性是“帮助查找器”窗口，它是一个可以按内容、索引以及全文本方式查找的单个对话框。

“帮助查找器”窗口

我们强烈建议您的帮助菜单上应该有一个打开“帮助查找器”窗口的命令。除此之外，您可以在帮助菜单上放置附加命令来提供系统信息或者应用程序的版权及版本号信息。

使用带“HELP FINDER”参数的 WinHelp 函数能够以编程方式调用“帮助查找器”窗口。有关的详细信息，请参阅本章稍后的“使用 WinHelp 函数”以及“帮助指南”中的 WinHelp 主题。

添加帮助的上下文相关性

按 F1 键是访问“上下文相关帮助”的最常用的方法，但是您也可以使用 ON KEY LABEL 指定任意键来激活“上下文相关帮助”。

在“表单”上使用“上下文相关 WinHelp”

若要实施“上下文相关帮助”，必须为您的应用程序指定帮助，然后把特定的帮助主题与应用程序中不同的对象关联起来。

若要添加“上下文相关帮助”

为应用程序指定一个帮助。
为希望提供“上下文相关帮助”的每一个对象指定一个帮助主题。

指定一个帮助文件

通过在代码中包含 SET HELP TO file 命令(其中 file 是帮助文件的名字)，可以决定应用程序能访问哪些帮助文件。例如，如果帮助文件名为 Myhelp.hlp，您可以使用下面的命令：

SET HELP TO Myhelp.hlp

这个命令一般包含在应用程序主程序的设置代码中。

指定帮助主题

应用程序中的特定对象指定一个帮助主题。

若要向一个对象指定一个帮助主题

在“设计”状态下打开想为之指定“上下文相关帮助”的对象，例如一个表单、控件或工具栏。
查看该对象的属性。
把 HelpContextID 属性设置为代表帮助文件中特定主题的编号。

有关把帮助主题映象为上下文 ID 编码的详细内容，请参阅“帮助指南”。

注释若要向菜单标题或菜单命令指定帮助标题，必须在与菜单标题或菜单命令相关联的过程中包含 SET TOPIC TO 命令。

实现“这是什么？”帮助

“这是什么？”帮助类似于上下文相关帮助，因为它提供对当前具有焦点的特定对象或控件的帮助。对于 WinHelp，帮助并不激活帮助应用程序然后在默认大小的“帮助”窗口中显示帮助主题，而是在一个弹出式小窗口显示帮助主题，然后用户单击屏幕任意位置时该窗口消失。“这是什么？”帮助在提供简单提示型描述或特定控件定义时很有用。

提示使您的“这是什么？”帮助主题保持简洁、准确，这样窗口就不会变得过大从而覆盖掩盖您正描述的特性。

“这是什么？”帮助

要把“这是什么？”帮助与特定表单、表单控件或工具栏关联起来，可以将它们的 WhatsThisHelpID 属性设置为代表帮助特定主题的编号。

使用下列属性和方法程序来实现“这是什么？”帮助：

属性	说明
WhatsThisHelp	设置表单的该属性为真(.T.)，可以启用表单以及表单上任意控件的“这是什么？”帮助。
WhatsThisButton	如果希望表单的标题栏显示一个“这是什么？”按钮，设置属性为真(.T.）。
WhatsThisHelpID	对一个表单、控件或工具栏，把该属性设置为对应于帮助文件中某个主题的 ID 编码。
WhatsThisMode	使用这个方法程序可以显示“这是什么？”帮助，问号代表鼠标指针然后启动“这是什么？”帮助模式。单击一个对象将显示该对象 WhatsThisHelpID 属性指定的帮助主题。

使用“这是什么？”按钮

若要实现“这是什么？”帮助

在设计模式下打开想启用“这是什么？”帮助表单。
把表单的 WhatsThisHelp 属性设置为“真”(.T.)。
若要在表单标题中显示一个“这是什么？”帮助按钮，把表单的 WhatsThisButton 属性设置为“真”(.T.)。
若要把一个“这是什么？”帮助主题与该表单关联起来，把表单的 WhatsThisHelpID 属性设置为与帮助中主题相对应的 ID 编码。
若要把一个“这是什么？”帮助主题与表单上特定控件关联在一起，选择控件然后把它的 WhatsThisHelpID 属性设置为与帮助文件中的主题相对应的 ID 编码。

编程实现帮助特性

您可以对您的应用程序编程，这样用户可以在 Microsoft 帮助中访问您的帮助信息。虽然一个帮助可能包含一个或多个独立的文件，但用户看来帮助只是应用程序的一部分。

使用 WinHelp 函数

在编程过程中在您的应用程序中使用帮助的另一个方法是调用 WinHelp 函数。WinHelp 函数是 Windows 应用程序编程接口 (API) 的一部分。WinHelp 函数仅用于 Windows 平台。

除了使用 HelpContextID 属性之外，还可以使用 WinHelp 函数，特别是在需要调用第二个帮助文件时。

提示如果使用了 SET HELP TO、HELP ID 以及SET TOPIC TO，就不需要使用 WinHelp 函数了。

若要使用 WinHelp 函数

定义应用程序将要传递的命令参数。
有关这些参数的说明，请参阅本章稍后的“wCmd 参数”部分。
用 SET LIBRARY TO 设置库并定义要使用的变量，这个工作一般在应用程序主文件的初始化代码中完成。
```
SET LIBRARY TO SYS(2004) + "FOXTOOLS.FLL" ADDITIVE
Help = RegFn("Help", "LCIC", "I")
```
库一定要设置成 Foxtools.fll fSYS(2004) 返回安装 Foxtools.fll 的 Visual FoxPro 根目录。

如果希望通过传送 K 关键字来打开一个帮助主题，可以用 RegFn( ) 定义一个变量，如上一示例中的 Help 变量。如果希望打开映射到一个编码的帮助主题，用 RegFn 定义一个象上面示例 HelpI 一样的变量，用一个编码代替 dwData 中的字符串。如果传递编码，必须在 .hpj 文件的 [MAP] 节中把它们映射为用注脚标记 (#) 编码定义的唯一的上下文字符。
使用 CallFn( ) 调用函数。
例如，如果您的帮助文件调用的是 Myhelpfile.hlp，使用带有主题的 K 关键字的 CallFn( ) 函数打开 Myhelpfile.hlp 中的主题
```
#define HELP_KEY 0x0101
wCmd = HELP_KEY
cFilename = "Myhelpfile.hlp"
dwData = "Add Menu Items at Run Time"
CallFn(Help, MainHWND(), cFileName, wCmd, dwData)
```

有关 FoxTools 函数的详细内容，请参阅 \Vfp98\Tools 目录下的 Foxtools.chm。

指定 WinHelp 参数

下列参数指定了 WinHelp 函数的选项。

hWnd 参数

hWnd 参数标识请求帮助的窗口。帮助使用这个标识符跟踪哪一个应用程序请求过帮助。在 Visual FoxPro 中，使用包含在 Foxtools.fll 库中的 MainHWND( ) 函数传递 hWnd 参数。

lpzFileName 参数

lpzFileName 参数是一个字段串，指定包含所需主题的帮助的有效路径及文件名称。它是以值传递方式传递的。

wCmd 参数

wCmd 参数或者指定用户对特定主题定位的查找类型，或者指明应用程序不再需要帮助。它可以设置为下列任何值。

常量	值	意义
HELP_FINDER	0x000B	显示“帮助查找器”窗口。
HELP_CONTEXT	0x0001	显示由上下文编号标识的特定主题的帮助。
HELP_HELPONHELP	0x0004	加载 Help.hlp 并显示“使用帮助”索引主题。
HELP_INDEX	0x0003	显示“帮助项目”文件 (.hpj) 中的 [OPTIONS] 一节定义的主帮助索引主题。
HELP_KEY	0x0101	显示在关键字列表中发现的第一个与 dwData 参数指定的关键字相对应的主题。
HELP_QUIT	0x0002	通知帮助应用程序已不再需要帮助。如果没有其他应用程序请求帮助，Windows 将关闭帮助应用程序。
HELP_SETINDEX	0x0005	把特定主题设置为索引主题。

dwData 参数

dwData 参数代表应用程序请求帮助的主题。它的内容和格式取决于应用程序调用 WinHelp 函数时所传递的 wCmd 值。

在对帮助的大多数调用帮助时是按值传递方式传递 dwData 参数的，这是 Visual FoxPro 的默认设置。

根据环境设置，上一行中的 dwData 或者代表一个文本字符串，指示要查找的关键字，或者是一个数值，指示标识一个特定主题的上下文编号。

以下列表中描述了对应于每个 wCmd 值的 dwdata 。

wCmd 值	dwData 格式
HELP_CONTEXT	一个包含主题上下文编号的数值。 HELP_CONTEXT 使用 -1 可以代替使用 HELP_INDEX。
HELP_HELPONHELP	忽略。
HELP_INDEX	忽略。
HELP_KEY	指向一个字符串的长指针，该字符串包含所需主题的关键字。
HELP_QUIT	忽略。
HELP_SETINDEX	包含要设置为索引主题的上下文编号的数值。

因为 WinHelp 函数可以指定一个上下文编号或关键字，所以它可以支持“上下文相关帮助”及对帮助中主题的查找。

注释如果帮助包含两个以上的索引，应用程序必须指定其中一个为默认索引。要确保设置的是正确的索引，应用程序在调用帮助时，应该把 wCmd 设置为 HELP-SETINDEX（其中 dwData 指定相应的上下文标识）。对帮助的每次调用都要后接 HELP_CONTEXT 的命令设置。千万不要把 HELP_SETINDEX 与 HELP_INDEX 一起使用。

为帮助保留 F1

注释在默认情况下 F1 键是可用作上下文相关帮助激活键的。因为这是一个公认的激活上下文帮助的标准，因此并不推荐您重定义这个键。

在表单中包含“帮助”按钮

如果在表单中添加“帮助”按钮，用户可以更方便地访问帮助信息。如果用户是个新手，那么更应该考虑添加一个“帮助”按钮。

若要设置上下文相关帮助并添加一个“帮助”按钮

在表单的 Init 事件中，将表单中所有对象的 HelpContextID 属性都设置为该帮助主题的 ID 值。例如，如果该值为 7，可用如下命令：
```
THIS.SetAll("HelpContextID", 7)
```
在表单中添加一个命令按钮。
把命令按钮的 Caption 属性设置为“帮助”。
在命令按钮的 Click 事件中，添加下面的命令：
```
HELP ID THIS.HelpContextID
```

提示可把“帮助”按钮保存为一个类，这样就可以方便地把它添加到任何表单中。有关把对象保存成类的详细内容，请参阅第九章“创建表单”。

退出帮助

帮助应用程序是所有 Windows 应用程序共享的资源。因为它也是一个独立的应用程序，所以用户可以象其他应用程序一样执行它。这样应用程序对帮助应用程序只能拥有有限的控制能力。

尽管应用程序不能直接关闭帮助应用程序窗口，但它可以通知帮助应用程序它不再需要帮助。在关闭主窗口之前，应用程序应该把 wCmd 参数设置为 HELP_QUIT，以此通知帮助说明应用程序不再需要它了。

如果应用程序在执行过程的某个位置要调用帮助，那么在终止应用程序前，必须把 wCmd 参数设置为 HELP_QUIT 来调用帮助。

如果一个应用程序打开了一个以上的帮助，它必须为每一个帮助文件调用 WinHelp 函数使其退出帮助应用程序。

如果一个应用程序或动态链接库 (DLL) 已经打开了一个帮助但不希望帮助应用程序的相关实例保持活动状态，那么这个应用程序或 DLL 应该把 wCmd 参数设置为 HELP_QUIT 来调用“帮助”，这样可以退出帮助应用程序的那个实例。

注释在终止之前，一个应用程序或 DLL 总是应该对任何一个打开的帮助文件调用“帮助”。只要使用某帮助文件名调用“帮助”就会打开相应的帮助文件。

直到所有调用“帮助”的窗口相继把 wCmd 设置为 HELP_QUIT 调用“帮助”以后，帮助应用程序才退出。如果一个应用程序没有这么做，那么即使在所有请求帮助的应用程序都终止以后，帮助应用程序仍将继续运行。