【原创】实现联机帮助插件（二十一）

　　在Eclipse中，联机帮助是使用者获得帮助信息的主要手段。用户可以通过“Help”→“Help Contents”菜单打开联机帮助文档。

　　Eclipse的联机帮助文档可以包含大量的信息，帮助文档的内容是以HTML文件的形式组织的，帮助文档的结构是以XML文件的形式进行组织的。也就是说，用户既可以复用已有的HTML文件形式的帮助，又可以利用XML文件结构化地组织帮助。

　　联机帮助扩展点的实现

　　在Eclipse中，一切都是插件，如果添加用户的联机帮助文档，用户需要实现Eclipse的“org.eclipse.help.toc”扩展点，添加“org.eclipse.help.toc”扩展点的步骤如下。

　　1. 在清单文件的Extensions页添加“org.eclipse.ui.toc”节点。

　　2. 在“org.eclipse.help.toc”节点上添加若干个toc子节点。

　　设置toc子节点的file属性为相应的XML文件，其中有一个节点的primary值为true，说明此节点为帮助文档的入口节点，如图1所示。

　　

图1 toc子节点属性

　　另外toc子节点提供了XML文件在Eclipse中的注册信息，联机帮助插件的plugin.xml文件如例程1所示。

　　例程1 plugin.xml

  
     
     
     
     
     
     
  

　　从plugin.xml文件可以看出每个toc子节点都对应一个XML文件，通过XML文件可以组织帮助子节点的结构。

　　联机帮助文档的结构

　　Eclipse的联机帮助文档不需要有扩展点的实现类，联机帮助文档是通过XML文件进行组织的。如插件的清单文件所示，在扩展点中只注册了相关的XML文件，这些XML文件之间又会相互引用，从而组成一个以XML文件为基础的树型结构。

　　Eclipse提供多种场景帮助文档的实现。

　　场景一：用户想一次性完成帮助文档。在这种情况下，用户可以直接构建自己的XML树。

　　场景二：用户不能够一次性完成帮助文档。在这种情况下，用户可以在XML文档中预置锚点，其他用户想实现这方面的帮助时，把自己的帮助挂接到此锚点即可(也是就说，用户可以通过这种实现方式把自己的帮助挂接在JDT的帮助文档中)。

　　下面将给出这两种场景下XML文档的实现。

　　从plugin.xml文件可以看出，帮助文档入口文件为toc.xml，此文件展示了帮助文档的第一层节点。XML文件如例程2所示。

　　例程2 toc.xml

<?xml version="1.0" encoding="UTF-8"?>

   

   
       
       
   

   
       
       
   

　　帮助文档入口文件中定义第一层节点有3个，下面分别解释这3个节点。

　　第一个节点是叶子节点，用href标记链接到“help/overview.html”文件。

　　第二个节点是子节点，子节点下有一个节点通过标记“link”到guide.xml，通过guide.xml进行定义，另外一个子节点通过“id”定义了一个锚点“afterGuide”，用户可以把自己的XML文件挂接到此锚点。

　　第三个节点结构和第二个节点一样。

　　通过“link”方式连接的XML文件的结构和toc.xml文件类似，例如guide.xml的定义如例程3所示。

　　例程3 guide.xml

<?xml version="1.0" encoding="UTF-8"?>

   

　　通过锚点挂接的XML文件也只能多出一个“link_to”的标记挂接到相应锚点，定义如例程4所示。

　　例程4 addguide.xml

<?xml version="1.0" encoding="UTF-8"?>

   

　　通过扩展点的定义和相应节点的XML文件定义，Eclipse就会构造出一个联机帮助文档的树，树的叶子节点会链接到相应的HTML文件，如图2所示。

　　

图2 联机帮助文档

　　在联机帮助中在线调用Java类

　　联机帮助文档是纯文本的文件，不能够编译运行。但有些时候，用户可能需要在帮助文档中演示只有在Java代码中才能完成的操作，Eclipse也提供这方面的支持，用户可以在帮助文档的页面中调用相应的Java类。

　　如果要在网页中调用Java类，在用户的网页下要引入“org.eclipse.help/livehelp.js”文件，通过此 .js文件调用相应的Java代码，实现代码如例程5所示。

　　例程5 HelloHelp.html

 

    Example Active Help Page
   
   
 
 
   

Active Help

    This text is too confusing to understand.  Click
   
    here for more information.
 

　　单击此页面的链接将会执行“com.free.help.activehelp”插件下的“com.free.help.activehelp. HelloWorldActiveHelp”文件，参数为“Kitty”，HelloWorldActiveHelp实现了“ILiveHelpAction”接口，通过“setInitializationString(String data)”方法传递来自页面的参数，代码如例程6所示。

　　例程6 HelloWorldActiveHelp.java

　　public class HelloWorldActiveHelp implements ILiveHelpAction {

　　private class HelloWorldInnerClass implements Runnable {

　　private String _name;

　　public HelloWorldInnerClass(String name) {

　　_name = name;

　　}

　　public void run() {

　　IWorkbenchWindow window =

　　PlatformUI.getWorkbench().getActiveWorkbenchWindow();

　　if (window != null) {

　　Shell shell = window.getShell();

　　shell.setMinimized(false);

　　shell.forceActive();

　　//打开一个通信对话框

　　MessageDialog.openInformation(window.getShell(), "Hello, " + _name,

　　"Hello, " + _name);

　　}

　　}

　　}

　　private String _name;

　　public void setInitializationString(String data) {

　　_name = data;

　　}

　　public void run() {

　　Display.getDefault().syncExec(new HelloWorldInnerClass(_name));

　　}

　　}

　　当用户单击帮助文档的链接时，将会执行关联的Java类，程序执行效果如图3所示。

　　

图3 页面调用Java代码

　　Eclipse中除了联机帮助，还有欢迎界面帮助以及上下文帮助，也是通过扩展点实现其功能。

　　下载(com.free.help.activehelp.rar)

image001.jpg

image002.jpg

image003.jpg

来自 “ ITPUB博客 ” ，链接：http://blog.itpub.net/13081368/viewspace-374981/，如需转载，请注明出处，否则将追究法律责任。

转载于:http://blog.itpub.net/13081368/viewspace-374981/