20.9  上下文帮助（contexts）

上下文帮助在旧版本Eclipse的效果是按F1键之后显示弹出式帮助，在Eclipse 3.1之后变成了视图式帮助。如图20.14所示，“上下文帮助”是指帮助信息可以和某窗口组件关联在一起，从而显示给用户有针对性的帮助。本节就来实现图20.14中的效果。

图20.14  视图式帮助

20.9.1  在plugin.xml中设置扩展点

打开plugin.xml文件的编辑框，将如下代码块插入到最后一行的</plugin>项之前：

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

      <contexts file="mycontexts.xml"/>

   </extension>

代码说明：

  ● org.eclipse.help.contexts是上下文帮助的扩展点。

  ● contexts的file指定上下文帮助的配置文件（尚未编写，下一步将完成此xml文件）。

20.9.2  编写配置文件mycontexts.xml

根据plugin.xml中的设置，把mycontexts.xml文件放置在项目的根目录下（和src目录平级）。该文件主要是把帮助信息分门别类，并定义好某项帮助的id、名称、注释和对应的html帮助文件。

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

<contexts>

         <context id="textHelpId">

                   <description>编辑器</description>

                   <topic href="contexts/1_3.html"  label="编辑器的帮助"/>

         </context>

         <context id="buttonHelpId">

                   <description>视图</description>

                   <topic href="contexts/1_2_1.html"  label="视图－创建"/>

                   <topic href="contexts/1_2_2.html"  label="视图－使用"/>

                   <topic href="contexts/1_2_3.html"  label="视图－实例"/>

         </context>

</contexts>

代码说明：

  ● 这里设置了两项帮助信息textHelpId、buttonHelpId。

  ● id：帮助信息ID标识。

  ● description：显示帮助信息时的标题栏文字。

  ● href：帮助信息子项所对应的帮助文件，可以和20.8节的帮助文件共用。

  ● label：显示帮助信息时，子项的显示名称。

20.9.3  创建HTML帮助文件

mycontexts.xml中的href项引用的都是20.8节的html帮助文件，所以此步省略。

20.9.4  将帮助信息和界面组件关联起来

将帮助信息和对应的界面组件关联起来，这样当焦点在此组件上时，按F1键才能显示出属于该组件的帮助。本例是给“视图1”设置一个上下文帮助，修改View1.java，在createPartControl方法前加入以下两句：

IWorkbenchHelpSystem help = PlatformUI.getWorkbench().getHelpSystem();

help.setHelp(parent, "cn.com.chengang.myplugin.buttonHelpId");

setHelp方法的第一个参数是和上下文帮助关联的组件对象，第二个参数由插件的ID标识（MANIFEST.MF 文件的Bundle-SymbolicName项）和上下文帮助项的Id标识（在mycontexts.xml 中的设置）组成。过去，旧版本的Eclipse是由WorkbenchHelp.setHelp(…)来设置帮助与组件之间的关联，在新版Eclipse中WorkbenchHelp类已经被废弃。

20.9.5  总结

上下文帮助（contexts）不依赖于普通帮助（toc）的设置，但两者有很多类似之处，它们HTML格式的帮助文件也可以共用。另外，也不是所有的组件都支持上下文帮助，比如ToolItem、TabItem、TableItem和TreeItem等就不支持。当然，组件对上下文帮助的支持情况，也有可能会随着Eclipse新版本的发布而有所变动。