Marshall Lamb (mlamb@us.ibm.com), 软件工程师, IBM

2000 年 7 月 01 日

JavaHelp 程序包为基于 Java 的用户界面应用程序提供易于实现的帮助功能。本文说明一种将 JavaHelp 软件集成到 Java 应用程序中的简单方法，通过这种方法，将对应用程序开发人员及其工作的影响减至最小。

在 Java 应用程序中开发图形用户界面的一个有力之处是，能够使它与平台上的其他类似应用程序的界面风格彼此相像。单个 Java 应用程序就可以看起来像 Windows NT 上的任何其他 Win32 应用程序，或者像 UNIX 上的 X-Windows 应用程序，而且这是自动实现的。接下来的挑战就是确保同时也有正常的窗口技术支持功能，使该应用程序不仅看起来像其他应用程序，而且行为也与它们类似。

在 Win32 平台上，最常见的跨应用程序的功能之一是 Windows 帮助引擎和查看器。直到最近，Sun 公司的 JavaHelp 软件能用之前，一直没有用于 Java 应用程序的通用帮助引擎或查看器，这使 Java 应用程序在其 Win32 对手之前处于明显的劣势。

在本文中我将讨论：

• 一个实际的 Java 应用程序项目（该项目需要帮助工具），以及 JavaHelp 程序包是如何成为解决方案的
• JavaHelp 程序包的哪些方面对我们最为有用
• 一个实用程序类，使 JavaHelp 更易于实现和部署
• 对该实用程序类的可能的增强

一个需要帮助功能的应用程序

我曾致力于一个急需帮助功能的大规模 Java 应用程序。我们需要一个工具，但没有开发自己工具的时间或资源。我们还想要一个支持开放式标准如 Java 编程和 HTML 的工具。显而易见的选择就是 JavaHelp 程序包，特别是因为我们领域中的许多其他产品已经在使用它或者正为使用它而进行评估。

JavaHelp 程序包的使用实际上非常简单，但要有效地使用它，开发人员必须了解此程序包的几个部分。试图让从事一个大型开发项目的许多开发人员都熟悉 JavaHelp 软件，并用它来加快速度，这可能既困难又费时。开发人员面对的复杂性越少，越能集中注意力于这个程序包本身，则集成和部署就越容易，将来的维护也就越省事。

我们必须解决的另一个实现问题是提供多少帮助。JavaHelp 程序包提供 Java 类，以提供字段级帮助以及基于操作的帮助。字段级帮助是指这样一种功能：选中某个用户界面控件并（例如）按 F1 键来获得该特定控件的帮助。基于操作的帮助是指单击对话框上的“帮助”按钮，或选择“帮助”主菜单类别下的某个选项。我们决定不在我们的应用程序中实现字段级帮助，原因是为每个控件管理帮助 ID 的成本太高，尤其是在整个周期中对用户界面的更改次数很多的情况下。我们转而着眼于基于操作的帮助上，以进一步减小对开发和技术编写人员的影响。

JavaHelp 程序包概述

JavaHelp 程序包内含许多类和实用程序，可以帮助您开发并实现帮助功能。有一些实用程序，用于生成索引和搜索帮助内容的控制文件。有一些 Java 类，用于实现字段级帮助和查看基于操作的帮助。甚至还有一些类，用于扩展帮助浏览器或者甚至实现您自己的帮助浏览器。随 JavaHelp 程序包提供用户指南以及 API javadoc。

本文不讨论建立帮助内容并扩展或开发帮助浏览器应用程序。由于上文已经说明的原因，也不讨论字段级帮助，而是集中说明帮助内容的文件系统结构，以及 JavaHelp 程序包的两个主要类：HelpSet 和 HelpBroker。这两个类已为我们用于自己的应用程序，以便于使用基于操作的帮助。

JavaHelp 目录结构
JavaHelp 目录是一系列 HTML 文件。每个帮助主题有一个 HTML 文件，这些文件都驻留在同一目录中。帮助集文件（使用 .hs 扩展名） 包含有关这些 HTML 文件的路径，以及搜索数据库的指针、目录和该路径中所有帮助主题的索引表的信息。您也可以在帮助集的文件名中使用标准的语言环境扩展名，按语言组织帮助集文件。例如， MyProductHelpset_en.hs 是一个指向所有英语帮助文件的帮助集， MyProductHelpset_it.hs 则用于意大利语的帮助文件。

您也可以按应用程序组织您的 HTML 帮助目录，从而使每个应用程序都具有不同的帮助集文件，但您这样做会丧失跨应用程序的搜索功能。作为 JavaHelp 建立过程的一部分生成的搜索数据库要求所有要搜索的 HTML 文件位于同一目录中。

HelpSet
HelpSet 类保持一个到一系列 HTML 文件的引用，这些文件组成联机帮助的目录。这些引用记录在帮助集文件中，这在上一节已作了说明。当实例化一个 HelpSet 对象时，将提供要使用的帮助集文件的路径，作为参数。

通过使帮助集文件包括标准的语言环境扩展名，您可以通知 HelpSet 类根据系统的当前语言环境来搜索 Java CLASSPATH，以便找到要使用的正确帮助集，而 Win32 的帮助则不会这样做。

一旦被实例化和初始化，HelpSet 对象的行为将或多或少与指向 HTML 帮助文件目录的文件指针类似。在创建 HelpBroker 对象时您指定要使用的 HelpSet，它负责创建和管理帮助浏览器。

HelpBroker
HelpBroker 类负责显示帮助浏览器。此帮助浏览器的工作方式与 Win32 的帮助浏览器类似，即允许您查看或浏览目录或索引，也允许您搜索特定的主题。在指示 HelpBroker 对象显示帮助浏览器之前,您必须首先告诉它使用哪一个 helpset。

使用 HelpBroker 的浏览器所遇到的一个问题是，它由调用帮助浏览器的父窗口所拥有。如果父窗口启动了帮助浏览器，然后又启动了模式子对话框（即在消除子对话框之前不能操纵父框架），则不能操纵帮助浏览器。它是父框架的子级，而不是子对话框的子级。因此，即使您经过父对话框从子对话框更新帮助浏览器中的帮助主题，虽然新主题会出现，但是您不能选中帮助浏览器并浏览目录。

除了实现 HelpSet 和 HelpBroker 类关系外，我们使用自己的帮助实用程序来解决此问题。

实现一个帮助实用程序类

我们创建了一个称为 StudioHelp 的类，它允许开发人员容易地显示某个特定帮助主题。要使用 StudioHelp 类，开发人员必须在其应用程序中做两件事：初始化 StudioHelp，以使用正确的帮助集；调用 showHelp() 静态方法，以便在响应相应的帮助事件时显示帮助浏览器。开发人员不必为查找正确的帮助集而担心，也不必为管理 HelpSet 和 HelpBroker 类而担心。所有这一切都由 StudioHelp 类来照管。

通过在显示帮助浏览器的激活窗口之前设置，我们解决了上一节说明的模态问题。这就重新建立了浏览器窗口的父级，并使单个 HelpBroker 实例能够为所有的模式或非模式对话框服务。

请查看 StudioHelp 类的源代码。

所用的 JavaHelp 函数
下面是对在 StudioHelp 中使用的 HelpSet 和 HelpBroker 方法的说明：

HelpSet::findHelpSet(java.lang.ClassLoader cl, java.lang.String name)
使用 CLASSPATH 环境变量以找到按名称指定的帮助集文件。 FindHelpSet() 将尝试使用标准的 Java 语言环境搜索算法找到 CLASSPATH 的每个目录中的文件。例如，如果当前活动的语言环境是美国英语，且 name 被设置为 myhelpset.hs ，则 findHelpSet() 将首先搜索 myhelpset_en_US.hs ，然后搜索 myhelpset_en.hs ，最后搜索 myhelpset.hs 。通过 cl 指定了一个可选的 ClassLoader，可以指定它用于查找和加载帮助集文件。如果指定了空值，则使用系统缺省值 ClassLoader。

HelpSet::createHelpBroker()
从一个 HelpSet 对象生成一个 HelpBroker 对象。然后使用此 HelpBroker 对象来显示帮助查看器，此查看器用于浏览 HelpSet 对象所代表的目录。

HelpBroker::setCurrentID(java.lang.String id)
设置帮助 ID，代表要显示的帮助主题。此帮助 ID 与包含该主题内容的 HTML 文件相同。例如，如果将 id 设置为 mainpanel ，则 HelpBroker 对象将搜索一个称为 mainpanel.htm 或 mainpanel.html 的文件，来提供该主题内容。

DefaultHelpBroker::setActivationWindow(java.awt.Window window)
通过将 HelpBroker 对象转换为 DefaultHelpBroker 类，并调用其 setActivationWindow() 方法，您就能够将帮助浏览器的父级对象设置为调用对话框的父级对象，从而甚至允许模式对话框显示可浏览的帮助。

HelpBroker::setDisplayed(boolean displayed)
指示 HelpBroker 对象是否显示帮助查看器。

使用 StudioHelp 实用程序类
此帮助实用程序类使用起来很简单。对于每个应用程序，您必须运行一次：

StudioHelp.initializeHelp("myhelpset.hs");

此步骤将借助要使用的相应 HelpSet 文件（如 myhelpset.hs ）来初始化帮助系统。请记住，您可以使用通常的语言环境专用后缀作为您的 HelpSet 文件名的一部分，来表明已转换的帮助内容，如 myhelpset_de_DE.hs 代表德语帮助文件。

然后，在应用程序中的每个对话框或框架对象中，您只须调用静态 showHelp() 方法来处理与帮助有关的事件，如捕获 F1 键击或帮助按钮事件，并显示相应的帮助 ID 作为结果：

StudioHelp.showHelp(this, true, "HelpTopic1");

HelpTopic1 是要显示的主题 ID。在您的帮助路径中应该有一个与 myhelpset.hs HelpSet 相关联的 HelpTopic1.html 文件。 this 参数是指正在从中显示帮助的当前窗口（父级窗口）。 true 参数指示 StudioHelp 显示浏览器。如果由于某种原因您需要暂时隐藏浏览器，您可以用 false 值调用 showHelp() ：

StudioHelp.showHelp(false, "");

可能的增强

您可以增强 StudioHelp 实用程序类，来对您的应用程序整合更多智能。例如，如果 StudioHelp 在您产品的多个应用程序之间共享，则您可以给予 StudioHelp 主权，让它根据 HelpSet 文件的初始化方式来指定正确的 HelpSet 文件，从而免除不同应用程序开发人员要担负的这种责任。例如，您可以指定一些静态标识符作为 initialize() 方法的一部分，来标识执行初始化的应用程序。如：

StudioHelp.initializeHelp(StudioHelp.CheckBalanceApp);

CheckBalanceApp 可以被定义为 StudioHelp 类中的一个静态整数：

static public int CheckBalanceApp = 2;

在 initialize() 方法中，您可以添加逻辑，将相应的 HelpSet 文件设置为指定标识符的结果：

switch (appType)
{
case CheckBalanceApp:   helpSetName = "myhelpset.hs";
break;
default: helpSetName = "defaulthelpset.hs";
break;
}

结论

JavaHelp 软件是一个多功能的有用工具，用于将帮助整合到基于 Java 的用户界面应用程序。在现有应用程序项目中部署此技术的最简单方法是，将维护 JavaHelp 的复杂性和开销封装在一个实用程序类中，并教会开发人员使用一个更为简化的接口，在应用程序中包括帮助功能。

Marshall Lamb (mlamb@us.ibm.com), 软件工程师, IBM

2000 年 7 月 01 日

JavaHelp 程序包为基于 Java 的用户界面应用程序提供易于实现的帮助功能。本文说明一种将 JavaHelp 软件集成到 Java 应用程序中的简单方法，通过这种方法，将对应用程序开发人员及其工作的影响减至最小。

在 Java 应用程序中开发图形用户界面的一个有力之处是，能够使它与平台上的其他类似应用程序的界面风格彼此相像。单个 Java 应用程序就可以看起来像 Windows NT 上的任何其他 Win32 应用程序，或者像 UNIX 上的 X-Windows 应用程序，而且这是自动实现的。接下来的挑战就是确保同时也有正常的窗口技术支持功能，使该应用程序不仅看起来像其他应用程序，而且行为也与它们类似。

在 Win32 平台上，最常见的跨应用程序的功能之一是 Windows 帮助引擎和查看器。直到最近，Sun 公司的 JavaHelp 软件能用之前，一直没有用于 Java 应用程序的通用帮助引擎或查看器，这使 Java 应用程序在其 Win32 对手之前处于明显的劣势。

在本文中我将讨论：

• 一个实际的 Java 应用程序项目（该项目需要帮助工具），以及 JavaHelp 程序包是如何成为解决方案的
• JavaHelp 程序包的哪些方面对我们最为有用
• 一个实用程序类，使 JavaHelp 更易于实现和部署
• 对该实用程序类的可能的增强

一个需要帮助功能的应用程序

我曾致力于一个急需帮助功能的大规模 Java 应用程序。我们需要一个工具，但没有开发自己工具的时间或资源。我们还想要一个支持开放式标准如 Java 编程和 HTML 的工具。显而易见的选择就是 JavaHelp 程序包，特别是因为我们领域中的许多其他产品已经在使用它或者正为使用它而进行评估。

JavaHelp 程序包的使用实际上非常简单，但要有效地使用它，开发人员必须了解此程序包的几个部分。试图让从事一个大型开发项目的许多开发人员都熟悉 JavaHelp 软件，并用它来加快速度，这可能既困难又费时。开发人员面对的复杂性越少，越能集中注意力于这个程序包本身，则集成和部署就越容易，将来的维护也就越省事。

我们必须解决的另一个实现问题是提供多少帮助。JavaHelp 程序包提供 Java 类，以提供字段级帮助以及基于操作的帮助。字段级帮助是指这样一种功能：选中某个用户界面控件并（例如）按 F1 键来获得该特定控件的帮助。基于操作的帮助是指单击对话框上的“帮助”按钮，或选择“帮助”主菜单类别下的某个选项。我们决定不在我们的应用程序中实现字段级帮助，原因是为每个控件管理帮助 ID 的成本太高，尤其是在整个周期中对用户界面的更改次数很多的情况下。我们转而着眼于基于操作的帮助上，以进一步减小对开发和技术编写人员的影响。

JavaHelp 程序包概述

JavaHelp 程序包内含许多类和实用程序，可以帮助您开发并实现帮助功能。有一些实用程序，用于生成索引和搜索帮助内容的控制文件。有一些 Java 类，用于实现字段级帮助和查看基于操作的帮助。甚至还有一些类，用于扩展帮助浏览器或者甚至实现您自己的帮助浏览器。随 JavaHelp 程序包提供用户指南以及 API javadoc。

本文不讨论建立帮助内容并扩展或开发帮助浏览器应用程序。由于上文已经说明的原因，也不讨论字段级帮助，而是集中说明帮助内容的文件系统结构，以及 JavaHelp 程序包的两个主要类：HelpSet 和 HelpBroker。这两个类已为我们用于自己的应用程序，以便于使用基于操作的帮助。

JavaHelp 目录结构
JavaHelp 目录是一系列 HTML 文件。每个帮助主题有一个 HTML 文件，这些文件都驻留在同一目录中。帮助集文件（使用 .hs 扩展名） 包含有关这些 HTML 文件的路径，以及搜索数据库的指针、目录和该路径中所有帮助主题的索引表的信息。您也可以在帮助集的文件名中使用标准的语言环境扩展名，按语言组织帮助集文件。例如， MyProductHelpset_en.hs 是一个指向所有英语帮助文件的帮助集， MyProductHelpset_it.hs 则用于意大利语的帮助文件。

您也可以按应用程序组织您的 HTML 帮助目录，从而使每个应用程序都具有不同的帮助集文件，但您这样做会丧失跨应用程序的搜索功能。作为 JavaHelp 建立过程的一部分生成的搜索数据库要求所有要搜索的 HTML 文件位于同一目录中。

HelpSet
HelpSet 类保持一个到一系列 HTML 文件的引用，这些文件组成联机帮助的目录。这些引用记录在帮助集文件中，这在上一节已作了说明。当实例化一个 HelpSet 对象时，将提供要使用的帮助集文件的路径，作为参数。

通过使帮助集文件包括标准的语言环境扩展名，您可以通知 HelpSet 类根据系统的当前语言环境来搜索 Java CLASSPATH，以便找到要使用的正确帮助集，而 Win32 的帮助则不会这样做。

一旦被实例化和初始化，HelpSet 对象的行为将或多或少与指向 HTML 帮助文件目录的文件指针类似。在创建 HelpBroker 对象时您指定要使用的 HelpSet，它负责创建和管理帮助浏览器。

HelpBroker
HelpBroker 类负责显示帮助浏览器。此帮助浏览器的工作方式与 Win32 的帮助浏览器类似，即允许您查看或浏览目录或索引，也允许您搜索特定的主题。在指示 HelpBroker 对象显示帮助浏览器之前,您必须首先告诉它使用哪一个 helpset。

使用 HelpBroker 的浏览器所遇到的一个问题是，它由调用帮助浏览器的父窗口所拥有。如果父窗口启动了帮助浏览器，然后又启动了模式子对话框（即在消除子对话框之前不能操纵父框架），则不能操纵帮助浏览器。它是父框架的子级，而不是子对话框的子级。因此，即使您经过父对话框从子对话框更新帮助浏览器中的帮助主题，虽然新主题会出现，但是您不能选中帮助浏览器并浏览目录。

除了实现 HelpSet 和 HelpBroker 类关系外，我们使用自己的帮助实用程序来解决此问题。

实现一个帮助实用程序类

我们创建了一个称为 StudioHelp 的类，它允许开发人员容易地显示某个特定帮助主题。要使用 StudioHelp 类，开发人员必须在其应用程序中做两件事：初始化 StudioHelp，以使用正确的帮助集；调用 showHelp() 静态方法，以便在响应相应的帮助事件时显示帮助浏览器。开发人员不必为查找正确的帮助集而担心，也不必为管理 HelpSet 和 HelpBroker 类而担心。所有这一切都由 StudioHelp 类来照管。

通过在显示帮助浏览器的激活窗口之前设置，我们解决了上一节说明的模态问题。这就重新建立了浏览器窗口的父级，并使单个 HelpBroker 实例能够为所有的模式或非模式对话框服务。

请查看 StudioHelp 类的源代码。

所用的 JavaHelp 函数
下面是对在 StudioHelp 中使用的 HelpSet 和 HelpBroker 方法的说明：

HelpSet::findHelpSet(java.lang.ClassLoader cl, java.lang.String name)
使用 CLASSPATH 环境变量以找到按名称指定的帮助集文件。 FindHelpSet() 将尝试使用标准的 Java 语言环境搜索算法找到 CLASSPATH 的每个目录中的文件。例如，如果当前活动的语言环境是美国英语，且 name 被设置为 myhelpset.hs ，则 findHelpSet() 将首先搜索 myhelpset_en_US.hs ，然后搜索 myhelpset_en.hs ，最后搜索 myhelpset.hs 。通过 cl 指定了一个可选的 ClassLoader，可以指定它用于查找和加载帮助集文件。如果指定了空值，则使用系统缺省值 ClassLoader。

HelpSet::createHelpBroker()
从一个 HelpSet 对象生成一个 HelpBroker 对象。然后使用此 HelpBroker 对象来显示帮助查看器，此查看器用于浏览 HelpSet 对象所代表的目录。

HelpBroker::setCurrentID(java.lang.String id)
设置帮助 ID，代表要显示的帮助主题。此帮助 ID 与包含该主题内容的 HTML 文件相同。例如，如果将 id 设置为 mainpanel ，则 HelpBroker 对象将搜索一个称为 mainpanel.htm 或 mainpanel.html 的文件，来提供该主题内容。

DefaultHelpBroker::setActivationWindow(java.awt.Window window)
通过将 HelpBroker 对象转换为 DefaultHelpBroker 类，并调用其 setActivationWindow() 方法，您就能够将帮助浏览器的父级对象设置为调用对话框的父级对象，从而甚至允许模式对话框显示可浏览的帮助。

HelpBroker::setDisplayed(boolean displayed)
指示 HelpBroker 对象是否显示帮助查看器。

使用 StudioHelp 实用程序类
此帮助实用程序类使用起来很简单。对于每个应用程序，您必须运行一次：

StudioHelp.initializeHelp("myhelpset.hs");

此步骤将借助要使用的相应 HelpSet 文件（如 myhelpset.hs ）来初始化帮助系统。请记住，您可以使用通常的语言环境专用后缀作为您的 HelpSet 文件名的一部分，来表明已转换的帮助内容，如 myhelpset_de_DE.hs 代表德语帮助文件。

然后，在应用程序中的每个对话框或框架对象中，您只须调用静态 showHelp() 方法来处理与帮助有关的事件，如捕获 F1 键击或帮助按钮事件，并显示相应的帮助 ID 作为结果：

StudioHelp.showHelp(this, true, "HelpTopic1");

HelpTopic1 是要显示的主题 ID。在您的帮助路径中应该有一个与 myhelpset.hs HelpSet 相关联的 HelpTopic1.html 文件。 this 参数是指正在从中显示帮助的当前窗口（父级窗口）。 true 参数指示 StudioHelp 显示浏览器。如果由于某种原因您需要暂时隐藏浏览器，您可以用 false 值调用 showHelp() ：

StudioHelp.showHelp(false, "");

可能的增强

您可以增强 StudioHelp 实用程序类，来对您的应用程序整合更多智能。例如，如果 StudioHelp 在您产品的多个应用程序之间共享，则您可以给予 StudioHelp 主权，让它根据 HelpSet 文件的初始化方式来指定正确的 HelpSet 文件，从而免除不同应用程序开发人员要担负的这种责任。例如，您可以指定一些静态标识符作为 initialize() 方法的一部分，来标识执行初始化的应用程序。如：

StudioHelp.initializeHelp(StudioHelp.CheckBalanceApp);

CheckBalanceApp 可以被定义为 StudioHelp 类中的一个静态整数：

static public int CheckBalanceApp = 2;

在 initialize() 方法中，您可以添加逻辑，将相应的 HelpSet 文件设置为指定标识符的结果：

switch (appType)
{
case CheckBalanceApp:   helpSetName = "myhelpset.hs";
break;
default: helpSetName = "defaulthelpset.hs";
break;
}

结论

JavaHelp 软件是一个多功能的有用工具，用于将帮助整合到基于 Java 的用户界面应用程序。在现有应用程序项目中部署此技术的最简单方法是，将维护 JavaHelp 的复杂性和开销封装在一个实用程序类中，并教会开发人员使用一个更为简化的接口，在应用程序中包括帮助功能。