为RCP程序添加帮助支持
《Adding Help Support to a Rich Client Platform (RCP) Application》,
特表示感谢。英语好的朋友可以直接看这篇文章。
v1.0.0
友好、易用的帮助系统是一个好的软件必备的部分,很少有软件能做到不需要任何文档。Eclipse的帮助系统是基于浏览器的,因此能够完全支持HTML,并且自动支持了搜索功能;而且可以支持上下文帮助和关键字索引。
帮助系统是RCP的一个可选的组件,它不是最小RCP的一部分,但是可以将其添加到RCP中为RCP程序提供帮助支持。
下面就以一个例子为基础说明为RCP程序添加帮助支持的过程。
在继续之前,首先确定你已经具有了一定的RCP方面的支持,了解了如何创建一个项目,以及如何产品配置。这些都不是本文的主题,需要了解这些内容,可以参考其他资料。本文下面内容假定读者已经了解并基本掌握了这方面的内容。
一、创建RCP程序。
PDE本身带了几个RCP程序的模板,我们就以其中的RCP Mail模板为例,这个不是本文的主题,根据模板创建一个RCP程序也比较简单,所以这里不再赘述。本例的项目名为org.example.rcp,其他都取默认值。
二、创建产品配置
一个产品配置是RCP程序必备的(虽然不会编译错误,也可以运行,但产品配置是RCP程序发布的基础)。我们的产品配置文件名为rcp.product,其他取默认值。
三、添加代码
首先,在RCP项目中找到AppllicationiActionBarAdvisor这个类,按照下面模板修改:
public class ApplicationActionBarAdvisor extends ActionBarAdvisor {
// Actions - important to allocate these only in makeActions, and then use them
// in the fill methods. This ensures that the actions aren't recreated
// when fillActionBars is called with FILL_PROXY.
private IWorkbenchAction exitAction;
private IWorkbenchAction aboutAction;
private IWorkbenchAction newWindowAction;
private OpenViewAction openViewAction;
private Action messagePopupAction;
private IAction helpContentAction = null; //帮助,此处添加三个Action用做菜单
private IAction helpSerchAction = null;
private IAction helpDynamicAction = null;
public ApplicationActionBarAdvisor(IActionBarConfigurer configurer) {
super(configurer);
}
protected void makeActions(final IWorkbenchWindow window) {
// Creates the actions and registers them.
// Registering is needed to ensure that key bindings work.
// The corresponding commands keybindings are defined in the plugin.xml file.
// Registering also provides automatic disposal of the actions when
// the window is closed.
exitAction = ActionFactory.QUIT.create(window);
register(exitAction);
aboutAction = ActionFactory.ABOUT.create(window);
register(aboutAction);
newWindowAction = ActionFactory.OPEN_NEW_WINDOW.create(window);
register(newWindowAction);
openViewAction = new OpenViewAction(window, "Open Another Message View", View.ID);
register(openViewAction);
messagePopupAction = new MessagePopupAction("Open Message", window);
register(messagePopupAction);
//帮助
helpContentAction = ActionFactory.HELP_CONTENTS.create(window);
register(helpContentAction);
helpSerchAction = ActionFactory.HELP_SEARCH.create(window);
register(helpSerchAction);
helpDynamicAction = ActionFactory.DYNAMIC_HELP.create(window);
register(helpDynamicAction);
}
protected void fillMenuBar(IMenuManager menuBar) {
MenuManager fileMenu = new MenuManager("&File", IWorkbenchActionConstants.M_FILE);
MenuManager helpMenu = new MenuManager("&Help", IWorkbenchActionConstants.M_HELP);
menuBar.add(fileMenu);
// Add a group marker indicating where action set menus will appear.
menuBar.add(new GroupMarker(IWorkbenchActionConstants.MB_ADDITIONS));
menuBar.add(helpMenu);
// File
fileMenu.add(newWindowAction);
fileMenu.add(new Separator());
fileMenu.add(messagePopupAction);
fileMenu.add(openViewAction);
fileMenu.add(new Separator());
fileMenu.add(exitAction);
// Help
helpMenu.add(aboutAction);
helpMenu.add(helpContentAction);
helpMenu.add(helpSerchAction);
helpMenu.add(helpDynamicAction);
}
protected void fillCoolBar(ICoolBarManager coolBar) {
IToolBarManager toolbar = new ToolBarManager(SWT.FLAT | SWT.RIGHT);
coolBar.add(new ToolBarContributionItem(toolbar, "main"));
toolbar.add(openViewAction);
toolbar.add(messagePopupAction);
}
}
四、测试一下
为RCP程序添加帮助系统,需要至少添加以下插件:org.apache.lucene
org.eclipse.help.appserver
org.eclipse.help.base
org.eclipse.help.ui
org.eclipse.help.webapp
org.eclipse.tomcat
org.eclipse.ui.forms。
打开产品配置文件,在编辑器的“配置”页面,点击添加,添加上述插件,然后再点击一“添加必须插件”。
在添加了所有必需插件以后,在“概述”页面点击启动产品,查看运行情况,可以看到在帮助菜单下,有了三个帮助相关的菜单。点击“帮助内容”会报一个未安装文档的错,其他两个菜单不会有错。
五添加简单的帮助内容
上面报的错误,是因为没有任何帮助内容可以使用,下面我们就提供一个简单的帮助内容,帮助内容一般也以一个独立的插件的形式存在,按照下面的步骤创建一个帮助内容插件:
1. File > New > Project > Plug-in project".
2. 在弹出的向导第一个页面中,保证复选框“Create a Java Project”处于未选中的状态。(当然,这个不是必须的)。
3. 输入项目名称”org.example.rcp.content”,并点击下一步。
4. 在模板选择页面选择Plug-in with sample help content"来使用模板创建一个帮助内容插件。
如果你和我一样使用3.2的中文版的话,那么你可能需要手动修改一下toc.xml文件,因为里面有个地方使用中文出现了乱码,打开这个文件,可以明显看到,把它改成任何符合xml规定的代码即可。如不做此不后面会出现错误。
5. 在产品配置文件编辑器的配置页面中,添加这个插件。
6. 在产品配置文件编辑器的概述页面中,点击启动产品,查看运行情况。
六、添加上下文帮助
上下文帮助是用户在任何界面下,点击F1(windows)或者单击菜单中的动态帮助,出现和当前界面相关联的帮助提示等。在Eclipse框架下,添加上下文帮助也是比较简单的。
首先,你需要为上下文指定一个ID,这个ID在后面会匹配到帮助内容的某一项或者几项。我们这里为RCP示例的“Message”视图创建一个上下文帮助,这需要修改View.java 这个文件,在这个类的createPartControl方法中添加:
PlatformUI.getWorkbench().getHelpSystem().setHelp(top, "org.example.rcp.content.context");
注意这里的第二个参数,是由文档插件ID+下面xml中id组成。
然后指定了上下文ID以后,就需要在帮助内容中添加与之相应的内容了。 在上面创建的org.example.rcp.ocntent项目下,创建一个文件”contexts.xml”,内容如下:
<contexts>
<context id="message">
<description>This is the sample context-sensitive help. </description>
<topic href="html/subtopic.html" label="Subtopic" />
</context>
</contexts>
然后需要把这个内容和上面的ID联系起来,这需要用到org.eclipse.help.context扩展点,这个扩展点需要指定的值就是刚刚创建的那个文件。 在扩展页面中
1. 点击添加,选择org.eclipse.help.context 这个扩展点(注意需要把下面的复选框取消选中才能看到这个扩展点),然后会提示是否添加到依赖项,选否。
2. 在file一项中,选择刚才创建的那个文件。
另外,在View.java文件中,做如下修改,即在setFocus()方法中,保证使top获得焦点,以使系统把正确的上下文传递给帮助系统,需要的修改参考下面代码:
private Composite top;
public void createPartControl(Composite parent) {
top = new Composite(parent, SWT.NONE);
...
}
public void setFocus() {
top.setFocus();
}
再次点击启动产品,并在焦点在Message视图上的情况下,按F1或者选菜单动态帮助查看效果,如果上面步骤都正确执行了,那么应该会在右边自动出现指定的帮助内容。