描述和打包上下文相关帮助内容

上下文相关帮助是通过使用户界面代码中声明的上下文标识与某个描述及指向相关联机帮助主题的链接相关联来描述的。这些关联是在 XML 文件中指定的。您可以创建任意数目的包含每个插件的上下文帮助关联的 XML 文件。每个上下文标识的描述和链接是在 XML 文件的 <context> 元素中指定的。每个上下文元素都可以有一个可选的 <description> 元素,该元素用来描述用户界面对象以及任意数目的链接至联机文档的 <topic> 元素。

从 3.1 开始,上下文元素可以任意覆盖用来在“帮助”视图中显示上下文帮助信息的缺省标题。

<contexts>
	<context id="panic_button" title="Panic Button Title">
		<description>This is the panic button.</description>
		<topic href="tasks/pushing_the_panic_button.htm" label="Pushing the panic button"/>
		<topic href="reference/panic_button.htm" label="Panic Button Reference"/>
	</context>
	...
</contexts>

一旦在 XML 文件中描述了上下文,就可以在插件清单中引用上下文文件了。注意,上述上下文标识不是完全限定的。这种情况是允许的,条件是在定义该上下文标识的插件的清单中提供上下文文件。换而言之,上下文标识被解析为提供 XML 文件的插件的标识。  

插件使用 org.eclipse.help.contexts 扩展点来提供上下文文件。  

   <extension point="org.eclipse.help.contexts">
      <contexts name="myContextHelp.xml"  />
   </extension>

可以通过包括 plugin 属性来引用其它插件提供的上下文文件。这允许您将所有文档(包括内容相关帮助)分组到一个插件中,并从用户界面代码插件或其它一些相关插件中引用它。

   <extension point="org.eclipse.help.contexts">
      <contexts name="myContextHelp.xml" plugin="com.example.helpExample"  />
   </extension>

正如您看到的那样,您可以相当灵活地将上下文相关帮助组织到包含在一个或多个插件中的一个或多个文件中。主要的注意事项是要正确解析文件中的上下文标识。如果未对上下文标识进行完全限定,则必须在声明上下文标识的插件中提供上下文 XML 文件。如果在上下文 XML 文件中使用全限定的上下文标识,则您可以相当灵活地设置 XML 文件的位置以及由哪个插件提供这些上下文。

从多个插件提供上下文相关帮助

另一个灵活性级别是能够从不同插件为同一个上下文标识提供上下文相关帮助。此功能非常有用,例如,如果有几组不同的文档插件,在用户的配置中可能安装了也可能未安装这些插件时,就是这种情况。此功能允许每个文档插件独立地声明它的上下文。最终用户将看到所有为窗口小部件标识提供了上下文的插件的合并上下文相关帮助内容。

注意,由于没有任何文档插件声明了上下文标识,所以必须使用窗口小部件的全限定上下文标识。当多个插件为同一个上下文标识添加了上下文相关帮助时,将首先显示声明了上下文的插件(用户界面插件)中定义的内容。其他描述和链接按不确定的顺序追加。