为RCP添加帮助系统

一款软件，如果希望用户能够快速的上手，完善的帮助系统必不可少。帮助中要包含操作指南，相关的疑难解答，软件的配置，维护等信息。优秀的文档可以节省用户的时间精力，也为维护人员省去了不少麻烦。

Eclipse的帮助系统可以说是十分优秀，功能全面，界面美观，操作便利，而且和Eclipse IDE结合的十分紧密，用户在任何时候都可以通过F1来体会这一点。

在RCP中，也可以利用Eclipse Help构建自己的帮助系统。Eclipse 帮助系统包括静态，动态和上下文敏感的帮助，这些都可以应用到RCP中。

在RCP中，加入帮助，也是通过plugin,如果要帮助要依赖于指定的plugin，也可以做成fragment的形式，这里是以plugin的形式。

要实现完整的帮助功能，需要依赖于以下插件：

1.    org.apache.lucene

2.    org.eclipse.help.appserver

3.    org.eclipse.help.base

4.    org.eclipse.help.ui

5.    org.eclipse.help.webapp

6.    org.eclipse.tomcat

7.    org.eclipse.ui.forms

1        在RCP的帮助菜单中加入Help Contents

在RCP的ActionBarAdvisor.makeActions()方法中实例化Help Constents Action，并注册到工作台中。

com.mi.pwdgate.ApplicationActionBarAdvisor.makeActions()

helpContentsAction = ActionFactory.HELP_CONTENTS.create(window);

register(helpContentsAction);

 

在Help Menu的About Action前面加入此helpContentsAction,在fillMenuBar()中实现。

com.mi.pwdgate.ApplicationActionBarAdvisor.fillMenuBar()

    MenuManager helpMenu = new MenuManager("&Help","help");

    helpMenu.add(helpAction);

    helpMenu.add(aboutAction);

 

现在运行RCP时，可以看到 Help > Help Contents 菜单项。运行RCP 时，要选中上面列出的plugin 。

 

 

2        加入帮助内容

帮助文件就是一组html 格式的文件，要加入到帮助系统中必须要有一个定义帮助文件结构的配置文件，是xml 格式。帮助文件的内容需要资料人员制作成标准的html 文件即可。为了美观性，也可以加入css 。

1）  在plugin.xml 文件中加入扩展点

        plugin.xml

        <extension point="org.eclipse.help.toc">

              <toc file="toc.xml" primary="true"/>

               <toc file="tocgettingstarted.xml"/>

</extension>

    此扩展点告诉帮助系统所有的toc文件，toc文件中定义的帮助的显示结构，它们显示在帮助对话框的左边。这个扩展点标示了2个toc 文件，它们都是位于帮助的顶级。其中toc.xml标示为primary,保证其在帮助对话框中永远显示。

 

插件根目录下的toc.xml文件，

    toc.xml

    <toc label="Pass Gate User Guide" topic="html/toc.html">

        <topic label="Getting started" href="doc/gettingstarted.html"/>

        <topic label="Copy" href="doc/copy.html"/>

        <topic label="Preferences" href="doc/preferences.html">

            <topic label="Policy" href="doc/preferences_policy.html"/>

<topic label="User Interaction" href="doc/preferences_ui.html"/>

        </topic>

        <topic label="Import" href="doc/imexport_import.html"/>

        <topic label="Export" href="doc/imexport_export.html"/>

        <topic label="Credits" href="doc/credits.html"/>

</toc>

              帮助文件结构

 

执行RCP后，可以在帮助对话框中看到刚才加入的帮助内容

 

3        加入上下文敏感帮助

如果希望能够和用户进行良好的交互，上下文敏感的帮助就必不可少。当用户执行特定的操作，或者在操作某个程序界面，只要点击帮助件，就可以得到与此相关的帮助内容。在Windows是F1,在GTK是Ctrl+F1。在Eclipse3.1以前，是以Infopops的形式出现，就是弹出一个黄色的框框，从Eclipse3.1，默认的形式是Help View。

 

下面在PassGateView中加入上下文敏感帮助

com.mi.pwdgate.view. PassGateView. createPartControl()

PlatformUI.getWorkbench().getHelpSystem().setHelp(viewer.getControl(),

                      " pwdgatehelp.PassGateView");

其中" pwdgatehelp.PassGateView"是上下文的id,系统使用这个id在上下文表中寻找要显示的内容。上下文表由org.eclipse.help.contexts扩展点定义。在plugin文件中加入如下内容。

plugin.xml

<extension point="org.eclipse.help.contexts">

       <contexts file="contexts.xml"/>

</extension>

contexts.xml文件中定义了上下文id和显示内容的映射。

contexts.xml

<contexts>

 <context id="PassGateView">

    <description>This is Password Gate View</description>

    <topic

      label="Password Gate"/>

      href="doc/gettingstarted.html"

    <topic

      label="Preference"/>

      href="doc/preferences.html"

 </context>

</contexts>

PlatformUI.getWorkbench().getHelpSystem().setHelp(viewer.getControl(),

                            "pwdgatehelp.PassGateView");中，上下文id, PassGateView对应contexts.xml中的context id, pwdgatehelp对应帮助插件的plugin id。

 

运行RCP,在Password Gate View 按F1,自动打开Help View。

 

用PDE的导出Wizard到处该帮助plugin，就生成了一个独立的帮助plugin，可以直接放在自己的RCP产品的plugins目录下。