为RCP程序添加帮助支持

为RCP程序添加帮助支持
本文大量参考了EclipseCorner的文章
《Adding Help Support to a Rich Client Platform (RCP) Application》，
特表示感谢。英语好的朋友可以直接看这篇文章。
v1.0.0
2007-12-26
友好、易用的帮助系统是一个好的软件必备的部分，很少有软件能做到不需要任何文档。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或者选菜单动态帮助查看效果，如果上面步骤都正确执行了，那么应该会在右边自动出现指定的帮助内容。