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

时间:2023-01-20 16:44:41

文章转载自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. 从通用项目库创建新插件项目
Eclipse 插件向导实现自定义帮助功能(也称为上下文敏感的帮助支持)

2)在项目名字处写上“helpdemo”作为项目的名字,然后点击“Next”按钮。

图 2. 指定项目的物理属性
Eclipse 插件向导实现自定义帮助功能(也称为上下文敏感的帮助支持)

3)在选项“是否创建 Rich Client Application”处,选择“Yes”,然后点击“Next”按钮。

图 3. 选择是否创建 RCP
Eclipse 插件向导实现自定义帮助功能(也称为上下文敏感的帮助支持)

4)在最后一个页面上选择需要应用的 Template,选择“Hello RCP”。

图 4. 选择 Hello RCP 模版
Eclipse 插件向导实现自定义帮助功能(也称为上下文敏感的帮助支持)

5)点击“Finish”按钮后。我们的 RCP 应用程序就创建出来了。

下面,让我们测试一下我们创建的 RCP 应用程序。

在 Manifest 编辑器上选择“Overview”标签页,点击“Testing”下面的“Launch an Eclipse Application”用以运行我们创建的 HelpDemo 应用程序。

图 5. 运行中的 HelpDemo 应用程序
Eclipse 插件向导实现自定义帮助功能(也称为上下文敏感的帮助支持)

在 Package Explore 里,我们可以看到 
RCP 模板自动为我们创建了以下 5 个类,他们分别作用是:
Application 类 :RCP 应用程序入口 
ApplicationWorkbenchAdvisor 类:初始化界面 
ApplicationWorkbenchWindowAdvisor 类: 负责管理整个窗口生命周期,包括状态栏、工具栏、菜单、窗口标题、窗口大小和各种控件等等 
ApplicationActionBarAdvisor 类:负责管理窗口的菜单栏、状态栏、工具栏的外观设计和行为(action)等 
Perspective 类:界面布局 
接下来我们会修改这些类来添加菜单,激活 Help 按钮等。

图 6. helpdemo 应用自动生成的代码
Eclipse 插件向导实现自定义帮助功能(也称为上下文敏感的帮助支持)

修改 RCP 应用标题

找到 eclipse 为我们的 RCP 应用自动生成的 ApplicationWorkbenchWindowAdvisor.java 类,在 preWindowOpen 方法里设定 RCP 应用程序的标题。

清单 1. 修改 RCP 应用标题
 public void preWindowOpen() { 
 …
       configure.setTitle(“Help demo”); // 修改 title 
 }

再次运行 RCP 应用,我们可以看到标题已经从“Hello RCP”变成“Help demo”了。

图 7. 修改 RCP 应用标题
Eclipse 插件向导实现自定义帮助功能(也称为上下文敏感的帮助支持)

创建一个向导页 (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
Eclipse 插件向导实现自定义帮助功能(也称为上下文敏感的帮助支持)

点击 menu->NewWizard,我们的 WizardPageA 被打开。

图 9. 向导页
Eclipse 插件向导实现自定义帮助功能(也称为上下文敏感的帮助支持)

这个向导页,就是我们即将加入上下文敏感帮助支持的页面。如果你的程序已经能成功显示,那我们的准备工作已经就绪。下面,将开始添加 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 按钮的向导页
Eclipse 插件向导实现自定义帮助功能(也称为上下文敏感的帮助支持)

此时点击 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 依赖
Eclipse 插件向导实现自定义帮助功能(也称为上下文敏感的帮助支持)

增加扩展点 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. 帮助文档内容文件位置
Eclipse 插件向导实现自定义帮助功能(也称为上下文敏感的帮助支持)

通过 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. 上下文敏感帮助运行结果
Eclipse 插件向导实现自定义帮助功能(也称为上下文敏感的帮助支持)

其中右边部分的描述,及 topic 等就是 help_contexts.xml 里的内容。
点击超链接 WizardA:Subtoic 将打开我们新建的 help 内容页面,即 html/WizardA_subtopic.html 页面的内容。

图 14. 上下文敏感帮助内容页面
Eclipse 插件向导实现自定义帮助功能(也称为上下文敏感的帮助支持)

至此,RCP 向导页面的上下文敏感的帮助支持全部实现了。

结束语

利用 eclipse 提供的强大的 help 插件可以简化 help 系统的开发。通过本文提供的方法,我们能够有效的利用 Eclipse 中的 help 插件为自己的 RCP 程序创建出上下文敏感的帮助系统,从而进一步完善产品的开发。

特别说明:

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

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