上下文敏感的帮助 (context-sensitive help) 是指当用户按下 F1 在您的应用程序中所显示的关于当前执行的任务的帮助，它为用户提供动态的、弹出式的帮助信息，以提高系统的易用性。用户可以在一个向导页（Wizard page）上按 F1 键或者点击向导页左下端的问号按钮以获得该向导页的详细操作信息。本文讲解了如何使用 Eclipse Rich Client Platform (RCP) 里的 Help 插件在已有系统上实现向导页的上下文敏感帮助系统，并通过一个简单的例子直观的向读者展示如何创建 RCP 应用和向导页，如何激活向导页的问号按钮，如何添加 Help 相关的插件，增加扩展点，如何创建帮助内容以及关联该内容和相应的向导页等一系列完整过程。为对 RCP 帮助系统感兴趣的开发人员提供经验分享。
Eclipse 的帮助系统是基于一个引用 HTML 文件的 XML 目录表，它是由已有的 Eclipse 帮助插件实现的。我们可以非常容易的把 Eclipse 帮助插件嵌入到我们自己的 RCP 系统里，从而实现强大的联机帮助系统，并且拥有全文检索 , 定义书签等操作。
创建 RCP 应用和向导页
创建 RCP 应用
本文我们将首先创建一个独立的 RCP 应用程序“helpdemo”，其内容是一个带有标题的应用程序窗口，通过菜单选项可以添加一个向导页，为这个向导页实现上下文帮助。
步骤如下：
1）从下拉菜单中选择新建一个项目，继而选择新建 plug-in 项目：
图 1. 从通用项目库创建新插件项目
2）在项目名字处写上“helpdemo”作为项目的名字，然后点击“Next”按钮。
图 2. 指定项目的物理属性
3）在选项“是否创建 Rich Client Application”处，选择“Yes”，然后点击“Next”按钮。
图 3. 选择是否创建 RCP
4）在最后一个页面上选择需要应用的 Template，选择“Hello RCP”。
图 4. 选择 Hello RCP 模版
5）点击“Finish”按钮后。我们的 RCP 应用程序就创建出来了。
下面，让我们测试一下我们创建的 RCP 应用程序。
在 Manifest 编辑器上选择“Overview”标签页，点击“Testing”下面的“Launch an Eclipse Application”用以运行我们创建的 HelpDemo 应用程序。
图 5. 运行中的 HelpDemo 应用程序
在 Package Explore 里，我们可以看到
RCP 模板自动为我们创建了以下 5 个类，他们分别作用是：
Application 类 :RCP 应用程序入口
ApplicationWorkbenchAdvisor 类：初始化界面
ApplicationWorkbenchWindowAdvisor 类： 负责管理整个窗口生命周期，包括状态栏、工具栏、菜单、窗口标题、窗口大小和各种控件等等
ApplicationActionBarAdvisor 类：负责管理窗口的菜单栏、状态栏、工具栏的外观设计和行为（action）等
Perspective 类：界面布局
接下来我们会修改这些类来添加菜单，激活 Help 按钮等。
图 6. helpdemo 应用自动生成的代码
修改 RCP 应用标题
找到 eclipse 为我们的 RCP 应用自动生成的 ApplicationWorkbenchWindowAdvisor.java 类，在 preWindowOpen 方法里设定 RCP 应用程序的标题。
清单 1. 修改 RCP 应用标题
public void preWindowOpen() {
…
configure.setTitle(“Help demo”); // 修改 title
}
再次运行 RCP 应用，我们可以看到标题已经从“Hello RCP”变成“Help demo”了。
图 7. 修改 RCP 应用标题
创建一个向导页 (WizardPage)
在 Eclipse 里，向导（Wizard）是由 WizardDialog，Wizard 和 WizardPage 三部分组成的。他们三者之间，可以看成前者是后者的容器。最终显示在用户面前的是向导页（WizardPage）。向导页包含多种 SWT 界面元素，构建出一个复杂的页面，同时向导页上还定义了界面元素的操作行为。而我们的帮助支持就是在向导页上按 F1 键或者点击向导页左下端的问号按钮被调用的。
所以接下来，我们先创建一个简单的向导页示例，供后续使用。
清单 2. 创建向导页示例
package helpdemo;
import org.eclipse.jface.wizard.WizardPage;
import org.eclipse.swt.SWT;
import org.eclipse.swt.layout.GridData;
import org.eclipse.swt.layout.GridLayout;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Label;
import org.eclipse.ui.PlatformUI;
public class WizardPageA extends WizardPage {
protected WizardPageA(String pageName) {
super(pageName);
this.setTitle(pageName);
}
public void createControl(final Composite parent) {
final Composite composite = new Composite(parent, SWT.NONE);
setControl(composite);
composite.setLayout(new GridLayout(1, false));
Label description = new Label(composite, SWT.WRAP);
description.setLayoutData(new GridData(SWT.FILL, SWT.FILL, true, false, 1, 1));
description.setText("This is a WizardPage for Help Demo.");
}
}
创建向导
向导（Wizard）是装载了一系列向导页的容器。通过向导，我们可以根据需求加载一系列向导页，构建出复杂的界面，并且加载具体的业务逻辑处理方法。在我们的例子中，只创建了一个向导页，并且把向导页 WizardPageA 加入了向导 WizardA 中。
清单 3. 创建向导
package helpdemo;
import org.eclipse.jface.wizard.Wizard;
public class WizardA extends Wizard {
private WizardPageA wizardA;
public WizardA() {
wizardA = new WizardPageA("WizardPage A");
this.addPage(wizardA);
}
public boolean canFinish() {
return true;
}
public boolean performFinish() {
return true;
}
}
创建向导对话框
向导对话框（WizardDialog）是向导的容器。通过向导对话框可以构造出一个完整的 GUI 界面以及操作界面。它负责装载向导类，操作时通过按钮 Back、Next 来在多个向导页之间切换。
清单 4. 创建向导对话框
package helpdemo;
import org.eclipse.jface.wizard.IWizard;
import org.eclipse.jface.wizard.WizardDialog;
import org.eclipse.swt.widgets.Shell;
public class WizardDialogA extends WizardDialog{
public WizardDialogA(Shell parentShell, IWizard newWizard) {
super(parentShell, newWizard);
// TODO Auto-generated constructor stub
}
}
创建 action 类用来弹出向导对话框
下面，我们要定义响应菜单或者工具栏按钮的 action 类。通过重写 run() 方法打开向导对话框。
清单 5. 定义 action 类
package helpdemo;
import org.eclipse.jface.action.Action;
import org.eclipse.jface.action.IAction;
import org.eclipse.jface.viewers.ISelection;
import org.eclipse.ui.IWorkbenchWindow;
import org.eclipse.ui.IWorkbenchWindowActionDelegate;
import org.eclipse.ui.PlatformUI;
public class NewWizardAction extends Action implements IWorkbenchWindowActionDelegate {
@Override
public void run(IAction action) {
WizardA wizardOne = new WizardA();
WizardDialogA dialog = new WizardDialogA(PlatformUI.getWorkbench().
getActiveWorkbenchWindow().getShell(), wizardOne);
dialog.create();
dialog.open();
}
@Override
public void selectionChanged(IAction action, ISelection selection) {
// TODO Auto-generated method stub
}
@Override
public void dispose() {
// TODO Auto-generated method stub
}
@Override
public void init(IWorkbenchWindow window) {
// TODO Auto-generated method stub
}
}
添加菜单 Menu
我们需要在已有的 RCP 应用里添加菜单。找到名为"ApplicationActionBarAdvisor"的类。修改 fillMenuBar 方法，在其中新建 MenuManager，并且把其加入到 menubar 中。
清单 6. 添加菜单 Menu
public void fillMenuBar(IMenuManager menuBar) {
MenuManager menu = new MenuManager(“&Menu”,”Menu”);
menuBar.add(menu);
}
添加 actionset
插件开发环境提供了 Manifest 编辑器来为插件的配置文件提供图形化的编辑功能。我们切换到“plugin.xml”的 tab 页直接修改代码，增加以下扩展点（extension），加入 actionset。
清单 7. 添加 actionset
<extension
point="org.eclipse.ui.actionSets">
<actionSet
id="helpdemo.NewWizard"
label="NewWizard"
visible="true">
<action
class="helpdemo.NewWizardAction"
id="helpdemo.NewWizard"
label="&NewWizard"
menubarPath="Menu/NewWizard"
style="push">
</action>
</actionSet>
</extension>
测试
下面来测试下我们创建的 RCP 向导对话框，向导页以及 action。运行应用程序后，一个标题为 Help Demo 的对话框弹了出来，其中在菜单栏上还有我们新建立的菜单。
图 8. 点击 Menu
点击 menu->NewWizard，我们的 WizardPageA 被打开。
图 9. 向导页
这个向导页，就是我们即将加入上下文敏感帮助支持的页面。如果你的程序已经能成功显示，那我们的准备工作已经就绪。下面，将开始添加 Help 了。
激活向导页的 help 按钮
在前一步生成的 RCP 应用的类中找到 ApplicationWorkbenchAdvisor 类。我们需要在其中激活 help 按钮，也就是我们通常在 eclipse 的向导页看到的左下角的问号。
重写 initialize 方法。 把对话框的“setDialogHelpAvailable”方法设成 true 就代表激活 help 按钮。同时，需要 import IWorkbenchConfigurer 和 TrayDialog 类。
清单 8. 激活 help 按钮
import org.eclipse.jface.dialogs.TrayDialog;
import org.eclipse.ui.application.IWorkbenchConfigurer;
@Override
public void initialize(IWorkbenchConfigurer configurer) {
TrayDialog.setDialogHelpAvailable(true);
}
运行 RCP 应用，可以看到 help 按钮已经出现在 wizardPage 的左下角。
图 10. 激活了 help 按钮的向导页
此时点击 help 按钮没有任何反应，因为我们还没有加入 help 的相关依赖。
添加 Help 插件依赖
接下来我们需要把 help 相关的插件导入到我们的项目中，这些插件包括：
org.eclipse.help
org.eclipse.help.base
org.eclipse.help.ui
org.eclipse.help.webapp
在 Manifest 编辑器打开“Dependencies”tap 页面通过点击”Add”按钮依次加入以上 help 插件依赖。
图 11. 添加 help 依赖
增加扩展点 help.contexts 到 plugin.xml
在 plugin.xml 中增加 help.contexts 扩展点，help_contexts.xml 是定义帮助内容的配置文件。
清单 9. 在 plugin.xml 中增加 help.contexts 扩展点
<extension
point="org.eclipse.help.contexts">
<contexts
file="help_contexts.xml"
plugin="helpdemo">
</contexts>
</extension>
创建帮助内容
清单 10. help_contexts.xml 内容
<contexts>
<context id="WizardA">
<description>WizardA: Demo for context-sensitive help.
</description>
<topic href="html/WizardA_subtopic.html"
label="WizardA:Subtopic" />
</context>
</contexts>
清单 11. WizardA_subtopic.html 内容
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <title>Table of Contents</title> </head> <body> <h3>WizardA_subtopic</h3>This is Help Content Page. </body> </html>
help_contexts.xml 和 html/WizardA_subtopic.html 位置如下
图 12. 帮助文档内容文件位置
通过 context id 关联向导页及其对应的帮助内容
添加下面代码到向导页 WizardA 的 createControl 方法：
清单 12. 关联向导页极其对应的帮助内容
public void createControl(finalComposite parent)
｛
……
PlatformUI.getWorkbench().getHelpSystem().setHelp(getShell(),
"helpdemo.WizardA");
// 需要指定 helpdemo 以此来保证 context id 的唯一性
｝
通过添加以上代码，将向导页 WizardA 和它对应的帮助内容页面通过 context id“helpdemo.WizardA”关联起来。
运行结果：点击 help 按钮或者按 F1，上下文帮助页面将被打开。其中，我们可以看到帮助主题：WizardA：Subtopic。
图 13. 上下文敏感帮助运行结果
其中右边部分的描述，及 topic 等就是 help_contexts.xml 里的内容。
点击超链接 WizardA:Subtoic 将打开我们新建的 help 内容页面，即 html/WizardA_subtopic.html 页面的内容。
图 14. 上下文敏感帮助内容页面
至此，RCP 向导页面的上下文敏感的帮助支持全部实现了。
结束语
利用 eclipse 提供的强大的 help 插件可以简化 help 系统的开发。通过本文提供的方法，我们能够有效的利用 Eclipse 中的 help 插件为自己的 RCP 程序创建出上下文敏感的帮助系统，从而进一步完善产品的开发。
转自http://www.ibm.com/developerworks/cn/opensource/os-cn-rcp-contexthelp/index.html