Eclipse 插件向导实现自定义帮助功能（也称为上下文敏感的帮助支持）

文章转载自IBM 文档社区

原文地址：https://www.ibm.com/developerworks/cn/opensource/os-cn-rcp-contexthelp/

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 程序创建出上下文敏感的帮助系统，从而进一步完善产品的开发。

特别说明：

PlatformUI.getWorkbench().getHelpSystem().setHelp(myselComposite, "contextId");

myselComposite  如果直接传入getShell(),你会发现，你所有的向导页都会显示最后一页的帮助信息，这里应该使用每一个向导页的composite，这样向导页与帮助信息就进行动态匹配了。