简介支持是一组扩展点和工作台部件,它们允许插件定义一些专用页面,这些页面用来向新用户介绍平台产品。通常,首次启动产品时就会显示简介信息。虽然各个插件都可以将简介信息添加到已知的产品简介配置中,但简介支持通常是在产品级别配置的。
从工作台的角度来看,简介支持的根在简介部件中。此部件是在扩展定义中指定的。当工作台进行初始化时,它将创建一个简介站点,该站点为简介页面保留了空间。该站点的简介部件实现是使用产品配置信息来确定的。一旦显示了简介部件,它就可以在两种方式之间进行切换:
一旦建立了简介部件,就必须为它配置简介信息。这是使用简介配置来完成的,简介配置也是使用扩展来添加的。各个插件可以使用它们自己的扩展来添加至基本产品简介配置。
我们将查看一个平台 SDK 简介页面的示例,以便更好地理解这些概念。
IIntroPart 接口和 org.eclipse.ui.intro 扩展点组成了可以用来为给定产品创建您自己的简介支持的通用机制。此扩展的主要用途是定义实现 IIntroPart 的类和指定产品标识与简介部件之间的绑定。例如,以下添加项定义工作台启动时将显示的假想简介部件:
<extension point="org.eclipse.ui.intro"> <intro class="com.example.SampleIntroPart" id="someId"> icon="someIcon.gif" </intro> <introProductBinding introId="someId" productId="com.example.someProductId"> </introProductBinding> </extension>此添加项首先定义简介部件并为它指定标识“someId”。然后,它将此简介部件绑定至标识为“com.example.someProductId”的产品。当平台启动时,在 class 属性中指定的类将被工作台实例化,并被作为对产品的简介显示给用户。这是对 IIntroPart 接口的最低级别的集成。
平台提供它自己的 IIntroPart 实现,称为 CustomizableIntroPart,该实现允许定制简介的内容和表示。以下是为工作台定义简介部件的片段。因为我们想主要讲述定义简介内容,所以我们将不查看实现简介部件的机制。(如果您需要了解更多详细信息,请参阅以上引用的扩展点文档和 javadoc。)
<extension point="org.eclipse.ui.intro"> <intro class="org.eclipse.ui.intro.config.CustomizableIntroPart" id="org.eclipse.platform.intro"> </intro> <introProductBinding introId="org.eclipse.platform.intro" productId="org.eclipse.platform"> </introProductBinding> </extension>以上添加项将 CustomizableIntroPart 定义为要用于 Eclipse SDK 平台的简介部件。本讨论的其余部分说明如何使用和扩展此部件。
平台的 CustomizableIntroPart 允许使用 org.eclipse.ui.intro.config 扩展点来定制简介的内容和表示。(可以使用 org.eclipse.ui.intro.configExtension 扩展点来扩展此简介配置。)这种结构使产品插件开发者可以集中精力开发简介内容,而不需要从头开始实现简介部件方案。如果指定了另一个简介类,则不会利用这两个扩展点,而指定的类必须为简介内容格式和配置实现它自己的方案。
org.eclipse.ui.intro.config 描述要显示我们的内容的简介配置的标识,还描述了包含简介内容的特定定义的 XML 文件的名称。期望只为给定的 CustomizableIntroPart 定义一个简介配置。(只能将找到的第一个简介配置显示在 CustomizableIntroPart 中。)
<extension id="intro" point="org.eclipse.ui.intro.config"> <config introId="org.eclipse.platform.intro" id="org.eclipse.platform.introConfig" content="$nl$/introContent.xml"> <presentation home-page-id="root" standby-page-id="standby"> <implementation ws="win32" style="css/shared.css" kind="html" os="win32"> </implementation> <implementation kind="swt"> </implementation> </presentation> </config> </extension>该文件的路径相对于插件的目录。(注意目录名中 $nl$ 变量的使用,该变量表示该文件将位于特定于目标环境的本地语言的目录中。)
配置扩展允许您指定内容以及内容的表示。content 元素主要用于定义页面,而 presentation 元素描述与表示相关的属性,这些属性描述将如何显示页面。必须指定简介主页(在完整方式下)的页面标识,而备用页面标识(在备用方式下)则是可选的。主页就是第一次启动产品时所显示的页面。表示可以指定一个或多个用来显示页面的实现。每个平台和窗口系统都要指定实现,从而允许您利用特定于平台的功能部件来显示页面内容。例如,Windows 平台具有健壮的 HTML 浏览器窗口小部件,因此将基于 HTML 的实现用于简介内容。没有此功能的其它平台使用基于 SWT 的实现,该实现将页面描述映射至基于 SWT 的表单。未指定窗口系统或操作系统的实现将被认为是通用实现;要确保简介显示在所有平台上,定义这样一种实现是很重要的。工作台将首先查找与当前操作系统和窗口系统相匹配的实现。如果找不到这样一种实现,它将选择通用实现。大多数这些详细信息都是在产品配置级别处理的,因此,在此处将不再进一步讨论它们。
现在,我们可以看一下内容本身。内容是按页面来描述的。所有页面都具有 id 属性。这是定义主页和备用页面以及引用了页面的其它位置时所使用的标识。否则,相关属性取决于所定义的页面种类。有两种基本类型的页面:
获得关于内容定义格式的感性知识的最好办法就是在 SDK 中浏览实现。以下片段只显示了 SDK 根页(它是所显示的第一个简介页面)的内容的第一部分。
<introContent> <page alt-style="css/root_swt.properties" style="css/root.css" id="root" style-id="page"> <title style-id="intro-header">Welcome to Eclipse Platform 3.0</title> <group id="links-background"> <group id="page-links"> <link label="Overview" url="http://org.eclipse.ui.intro/showPage?id=overview" id="overview" style-id="left"> <text>Find out what Eclipse is all about</text> </link> <link label="Tutorials" url="http://org.eclipse.ui.intro/showPage?id=tutorials" id="tutorials" style-id="left"> <text>Let us guide you through Eclipse end-to-end tutorials</text> </link> <link label="Samples" url="http://org.eclipse.ui.intro/showPage?id=samples" id="samples" style-id="right"> <text>Explore Eclipse development through code samples</text> </link> <link label="Whats New" url="http://org.eclipse.ui.intro/showPage?id=news" id="news" style-id="right"> <text>Find out what is new in this release</text> </link> </group> </group>
页面上的元素还可以从特定实现过滤(filteredFrom)。这允许页面设计者针对特定平台进行设计。当描述页面及其内容时,可以使用许多功能更强大的属性。有关有效元素、子元素及其属性的完整参考,请参阅 org.eclipse.ui.intro.config 的扩展点文档及其相关联的简介内容文件格式规范。
可以采用三种方法来扩展简介配置:
插件可以将简介内容添加至在别处定义的页面。但是,定义页面必须定义一个充当新内容的位置占位符的 anchor 属性。SDK 概述页定义两个锚,用于在概述页上添加与 JDT 和 PDE 相关的元素。
<group id="page-content"> <text style-id="page-title" id="page-title">OVERVIEW</text> <text style-id="page-description" id="page-description">Eclipse is a kind of universal tool platform - an open extensible IDE for anything and nothing in particular. It provides a feature-rich development environment that allows the developer to efficiently create tools that integrate seamlessly into the Eclipse Platform.</text> <group id="overview-links"> <link label="Workbench basics" url="http://org.eclipse.ui.intro/showHelpTopic?id=/org.eclipse.platform.doc.user/concepts/concepts-2.htm" id="basics"> <text>Learn about basic Eclipse workbench concepts</text> </link> <link label="Team support" url="http://org.eclipse.ui.intro/showHelpTopic?id=/org.eclipse.platform.doc.user/concepts/concepts-26.htm" id="team"> <text>Find out how to collaborate with other developers</text> </link> <anchor id="jdtAnchor"/> <anchor id="pdeAnchor"/> </group> </group>向页面中添加内容的插件可以引用这些锚。内容是使用 org.eclipse.ui.intro.configExtension 扩展添加的。除了扩展页面内容之外,此扩展点还允许用户添加备用内容部件和定制操作。
要扩展现有的简介配置,可以使用 configExtension 元素。在此元素中,您指定正在被扩展的简介配置的 configId 以及用来描述新内容的内容文件。
<extension point="org.eclipse.ui.intro.configExtension"> <configExtension configId="org.eclipse.platform.introConfig" content="$nl$/overviewExtensionContent.xml"/> ... </extension>内容文件的格式与简介配置内容的格式相似,只不过内容文件必须包含 extensionContent 元素,该元素定义指向应该插入扩展内容的锚的路径。
<introContent> <extensionContent alt-style="css/swt.properties" style="css/overview.css" path="overview/page-content/overview-links/jdtAnchor"> <link label="Java development" url="http://org.eclipse.ui.intro/showHelpTopic?id=/org.eclipse.jdt.doc.user/gettingStarted/qs-BasicTutorial.htm" id="java"> <text>Get familiar with developing Java programs using Eclipse</text> </link> </extensionContent> </introContent>在将定制内容添加至简介的预定义锚点之后,给定的产品就可以使用以上讨论的 org.eclipse.ui.intro 来将它自己绑定至该简介。当产品运行时,扩展的简介将显示附加内容。这允许产品具有它自己的标记和其它特定于产品的信息,同时重用紧密相关的产品的简介以及它自己的键内容。
给定的简介还可以选择性地包括相关产品的一些简介。在此情况下,产品可以定义它自己的简介和简介配置,然后通过在内容文件中使用 include 来引用在另一个简介的配置中定义的重要元素。对于彼此在对方基础上构建的相关产品并且需要向用户介绍更高级别产品中的关键概念时,这种机制很有价值。
插件还可以实现用于在简介页面处于备用方式时显示备用内容的部件。例如,平台定义一个将显示相关简介内容的备忘单的备用部件。部件是使用具有专用 URL 的页面链接来启动的。备用部件是使用一个 URL 来启动的,该 URL 包含用于显示备用部件的特殊命令,例如 http://org.eclipse.ui.intro/showStandby?partId=somePartId。部件是在 org.eclipse.ui.intro.configExtension 扩展中的 standbyContentPart 子元素中定义的。必须为部件指定 id、pluginId 和 class。该类必须实现 IStandbyContentPart。以下片段显示平台如何定义用于显示备忘单的备用部件。
<extension point="org.eclipse.ui.intro.configExtension"> <standbyContentPart id="org.eclipse.platform.cheatsheet" class="org.eclipse.platform.internal.CheatSheetStandbyContent" pluginId="org.eclipse.platform"/> </extension>可以从简介页面中使用其 URL 为 http://org.eclipse.ui.intro/showStandby?partId=org.eclipse.platform.cheatsheet&input=org.eclipse.pde.helloworld 的 link 子元素来启动此备忘单。此 IntroURL 将启动 org.eclipse.platform.cheatsheet 备用内容部件并将它的输入设置为“org.eclipse.pde.helloworld”。有关实现备用部件的详细机制超出了我们的讨论范围。有关更多信息,请参阅 IStandbyContentPart 及其相关类。
通过使用 org.eclipse.ui.intro.configExtension 扩展点,插件可以添加它们自己的定制操作,可以将这些定制操作用作页面中的 link 元素的 URL 值。例如,考虑以下链接:
http://org.eclipse.ui.intro/runAction?pluginId=org.eclipse.pde.ui&class=org.eclipse.pde.ui.internal.samples.ShowSampleAction&id=org.eclipse.sdk.samples.swt.examples
此 IntroURL 将运行一个称为 ShowSampleAction 的操作类,该操作类位于“org.eclipse.pde.ui”插件的“org.eclipse.pde.ui.internal.samples”包中。要运行的样本的标识为“org.eclipse.sdk.samples.swt.examples”。
要定义此简介 URL 的定制版本,可以使用以下标记:
<extension point="org.eclipse.ui.intro.configExtension"> <action name="myCommand" replaces="runAction?pluginID=org.eclipse.pde.ui&class=org.eclipse.pde.ui.internal.samples.ShowSampleAction"> </action> </extension>借助以上的扩展,您现在可以使用以下 URL 来运行同一操作:
http://org.eclipse.ui.intro/myCommand?id=org.eclipse.sdk.samples.swt.examples
“myCommand”操作将被替换为 replaces 属性的值,并且将把其余任何 URL 参数追加至末尾。一旦进行了替换,所获得的 URL 将被扩展回到:
http://org.eclipse.ui.intro/runAction?pluginId=org.eclipse.pde.ui&class=org.eclipse.pde.ui.internal.samples.ShowSampleAction&id=org.eclipse.sdk.samples.swt.examples