【原创】实现联机帮助插件（二十一）
上一篇 / 下一篇 2008-07-11 11:30:31 / 个人分类：Eclipse插件开发
在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>
<extension point="org.eclipse.help.toc">
<toc file="toc.xml" primary="true"/>
<toc file="guide.xml"/>
<toc file="reference.xml"/>
<toc file="addoverview.xml"/>
<toc file="addguide.xml"/>
<toc file="addreference.xml"/>
</extension>
</plugin>
从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"?>
<toc label="Free Help of Contents" topic="help/titlepage.html">
<topic label="Overview" href="help/overview.html"/>
<topic label="Guide sub-section" >
<link toc="guide.xml"/>
<anchor id="afterGuide"/>
</topic>
<topic label="Reference sub-section">
<link toc="reference.xml"/>
<anchor id="afterReference"/>
</topic>
</toc>
帮助文档入口文件中定义第一层节点有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"?>
<toc label="Guide sub-section" topic="help/guide.html">
<topic label="Guide" href="help/guide1.html"/>
</toc>
通过锚点挂接的XML文件也只能多出一个“link_to”的标记挂接到相应锚点，定义如例程4所示。
例程4 addguide.xml
<?xml version="1.0" encoding="UTF-8"?>
<toc label="Additional Guide" link_to="toc.xml#afterGuide" >
<topic label="Additional Guide 1" href="help/anchor2.html"/>
</toc>
通过扩展点的定义和相应节点的XML文件定义，Eclipse就会构造出一个联机帮助文档的树，树的叶子节点会链接到相应的HTML文件，如图2所示。
图2 联机帮助文档
在联机帮助中在线调用Java类
联机帮助文档是纯文本的文件，不能够编译运行。但有些时候，用户可能需要在帮助文档中演示只有在Java代码中才能完成的操作，Eclipse也提供这方面的支持，用户可以在帮助文档的页面中调用相应的Java类。
如果要在网页中调用Java类，在用户的网页下要引入“org.eclipse.help/livehelp.js”文件，通过此 .js文件调用相应的Java代码，实现代码如例程5所示。
例程5 HelloHelp.html
<html>
<head>
<title>Example Active Help Page</title>
<script. language="JavaScript" src="../../org.eclipse.help/livehelp.js">
</script>
</head>
<body>
<h2>Active Help</h2>
This text is too confusing to understand. Click
<a href='javascript.:liveAction(
"com.free.help.activehelp",
"com.free.help.activehelp.HelloWorldActiveHelp",
"Kitty"
)'>
here</a> for more information.
</body>
</html>
单击此页面的链接将会执行“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)
相关阅读:
- 连载：大学生求职七大昏招（十三）抱怨(4) (jobchanceleo, 2008-7-10)
- Java编程语言中EJB技术的详细说明 (Java006, 2008-7-10)
- Hibernate的主键生成机制 (Java006, 2008-7-10)
- 深入讲解JSP 2.0下的动态内容缓存技术 (Java006, 2008-7-10)
- Sun公司Java将用于惠普智能手机 (Java006, 2008-7-10)
- JavaScript和Java的区别详细说明 (Java006, 2008-7-10)
- J2ME中应用程序的内存优化 (Java006, 2008-7-10)
- J2ME编程之Nokia 7210配置篇 (Java006, 2008-7-10)
- com.free.help.activehelp.rar (阿-甘, 2008-7-11)
导入论坛 引用链接 收藏 分享给好友 推荐到圈子 管理 举报
-
引用
删除
elvaelva1232003 / 2008-07-25 11:05:57
- 嘿嘿!
-
引用
删除
elvaelva1232003 / 2008-07-25 11:05:35
-
评 5 分
