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

最新推荐文章于 2020-06-01 12:15:52 发布

余云勇

最新推荐文章于 2020-06-01 12:15:52 发布

阅读量1.6k

点赞数

分类专栏： Eclipse插件开发

Eclipse插件开发专栏收录该内容

32 篇文章 1 订阅

订阅专栏

文章转载自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="&amp;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，这样向导页与帮助信息就进行动态匹配了。

余云勇

关注

0
点赞
踩
1

收藏

觉得还不错? 一键收藏
0
评论
Eclipse 插件向导实现自定义帮助功能（也称为上下文敏感的帮助支持）

文章转载自IBM 文档社区原文地址：https://www.ibm.com/developerworks/cn/opensource/os-cn-rcp-contexthelp/Eclipse 的帮助系统是基于一个引用 HTML 文件的 XML 目录表，它是由已有的 Eclipse 帮助插件实现的。我们可以非常容易的把 Eclipse 帮助插件嵌入到我们自己的 RC
复制链接

扫一扫