简介部分配置

org.eclipse.ui.intro.config

3.0

此扩展点用来注册简介配置。此配置为给定简介添加项提供表示实现和内容。简介将在第一次启动工作台时出现并作为“帮助”菜单中的一个选项。简介通常用于向用户介绍在 Eclipse 上构建的产品。

简介分成若干页,通常会反映特殊类别的介绍性资料。例如,“新增内容”可能会介绍自先前版本以来新增的概念或功能。可使用 org.eclipse.ui.intro.configExtension 扩展点从其它插件引用并扩展一个简介配置定义的内容。

<!ELEMENT extension (handle? , config+)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT config (presentation)>

<!ATTLIST config

introId CDATA #REQUIRED

id      CDATA #REQUIRED

content CDATA #REQUIRED>

可用来配置可定制简介部分的配置元素。配置元素必须指定标识、简介标识和内容文件。简介内容文件是描述简介所具有的页面、组和链接的 XML 文件。



<!ELEMENT presentation (implementation+ , launchBar?)>

<!ATTLIST presentation

home-page-id    CDATA #REQUIRED

standby-page-id CDATA #IMPLIED>

定义简介部分的表示的所有可能实现的表示元素。它可能定义了一个或多个实现。根据实现的 os/ws 属性,启动时只会有一个实现被选中。否则,没有定义 os/ws 属性的第一项将会被选中。



<!ELEMENT implementation (head?)>

<!ATTLIST implementation

kind  (swt|html)

style CDATA #IMPLIED

os    CDATA #IMPLIED

ws    CDATA #IMPLIED>

平台的现成经验的表示具有两个实现。其中一项是基于 SWT 浏览器的,而另一项是基于用户界面表单的。可配置可定制简介部分以便根据当前操作系统和窗口系统选择这两个表示的其中一个。实现的类型可以是 SWT 或 HTML。



<!ELEMENT launchBar (handle? , shortcut*)>

<!ATTLIST launchBar

location (left|bottom|right|fastview) "fastview"

bg       CDATA #IMPLIED

fg       CDATA #IMPLIED>

启动栏与“switchToLaunchBar”命令配合工作。当命令执行时,它将关闭简介并在主窗口某一个贴面区域创建启动栏。启动栏将至少包含一个按钮,可允许用户返回到最后的简介页。(可选)它包含使用 shortcut 元素定义的其它按钮。这些按钮可用来快速转到某一特定简介页。起始版本为 3.1



<!ELEMENT shortcut EMPTY>

<!ATTLIST shortcut

tooltip CDATA #IMPLIED

icon    CDATA #REQUIRED

url     CDATA #REQUIRED>

将在简介启动栏中为每个 shortcut 元素创建按钮。当按该按钮时,将执行在快捷方式中定义的 URL。起始版本为 3.1



<!ELEMENT handle EMPTY>

<!ATTLIST handle

close (true | false) "true"

image CDATA #IMPLIED>

用来控制如何呈示启动栏把手的可选元素。起始版本为 3.1



<!ELEMENT introContent (page+ , group* , extensionContent*)>

introContent 元素定义简介内容文件的主体。内容文件包括页面、可包括在多个页面中的共享组以及在其它配置中定义的锚点的扩展。



<!ELEMENT page (group* | link* | text* | head* | img* | include* | html* | title? | anchor* | contentProvider*)>

<!ATTLIST page

url          CDATA #IMPLIED

id           CDATA #REQUIRED

style        CDATA #IMPLIED

alt-style    CDATA #IMPLIED

filteredFrom (swt|html)

content      CDATA #IMPLIED

style-id     CDATA #IMPLIED

shared-style (true | false) >

此元素用来描述要显示的页面。此简介可显示动态和静态页面。
动态页面的内容是从下面所述的页面的子元素生成的。将根据表示应用样式或 alt 样式。该样式可通过引用标识或类标识进一步增强。
静态页面允许在某项简介中重用现有 HTML 文档并可从任何静态或动态页面链接。静态页面未在页面元素中定义,它们只是可由其它页面链接的 HTML 文件。
其标识在简介配置扩展点的表示元素中指定的主页可能有一个 URL 指示它是静态页面。如果未指定任何 URL,则会假定主页是动态的。使用页面元素描述的所有其它页面都是动态的。
而且还要注意,在使用 SWT 表示且即将显示静态时,将启动外部浏览器而且当前页面仍然可视。
动态页面中使用的子元素如下所示:group 子元素用于组合相关内容并在组合内容间应用样式。link 子元素定义可用来链接至静态或动态页面的链接并运行简介操作/命令。链接通常是在页面级别定义的,用于在主页与页面中的链接之间进行导航。text 子元素在页面级别定义文本内容。head 子元素仅适用于基于 Web 的表示并允许将其它 HTML 添加至 HTML head 节。这在添加 java 脚本或其它样式表时特别有用。img 子元素定义页面级别的图像内容。include 子元素允许重用除页面以外的任何元素。html 子元素仅适用于基于 Web 的表示并允许在页面的内容中嵌入或包括 HTML。嵌入允许通过引用 HTML 文件将严格定义的文件嵌入到 HTML object 中。包括允许包括直接取自 HTML 文件的 HTML 片段。title 子元素定义页面的标题。anchor 子元素定义其中外部添加项可以通过 <extensionContent> 元素指定的点。



<!ELEMENT group (group* | link* | text* | img* | include* | html* | anchor* | contentProvider*)>

<!ATTLIST group

id           CDATA #REQUIRED

label        CDATA #IMPLIED

style-id     CDATA #IMPLIED

filteredFrom (swt|html) >

用于组合相关内容、应该应用类似样式的内容或者应一起包括在其它页面中的内容。



<!ELEMENT head EMPTY>

<!ATTLIST head

src      CDATA #REQUIRED

encoding CDATA #IMPLIED>

指示要将 HTML 包括在页面在的 HEAD 内容区域中。它允许将其它 HTML 添加至 HTML HEAD 节。这在添加 java 脚本或其它样式表时特别有用。此标记仅将与基于 HTML 的简介部分实现配合使用。只是在用户界面表单实现的情况下会忽略它。一个页面可有多个头元素。实现可有且只能有一个头元素(因为它是在所有页面间共享的)。



<!ELEMENT title EMPTY>

<!ATTLIST title

id           CDATA #IMPLIED

style-id     CDATA #IMPLIED

filteredFrom (swt|html) >

可选择包含转义 HTML 标记的文本片段。它仅被用作页面标题,所以给定页面最多只能有一个标题元素。



<!ELEMENT link (text? , img?)>

<!ATTLIST link

id           CDATA #IMPLIED

label        CDATA #IMPLIED

url          CDATA #REQUIRED

style-id     CDATA #IMPLIED

filteredFrom (swt|html) >

可链接至静态 HTML 文件、外部 Web 站点或可运行简介 URL 操作。



<!ELEMENT text EMPTY>

<!ATTLIST text

id           CDATA #IMPLIED

style-id     CDATA #IMPLIED

filteredFrom (swt|html) >

可选择包含转义 HTML 标记的文本片段。它可以包括 b 和 li 标记。它还可以包含 URL 的锚点。如果需要多个段落,就可以将文本分成多个部分,每个部分以 p 标记开头和结尾。



<!ELEMENT img EMPTY>

<!ATTLIST img

id           CDATA #REQUIRED

src          CDATA #REQUIRED

alt          CDATA #IMPLIED

style-id     CDATA #IMPLIED

filteredFrom (swt|html) >

表示简介内容和不表示的图像(与样式中定义的修饰图像相反)。



<!ELEMENT html (img | text)>

<!ATTLIST html

id           CDATA #REQUIRED

src          CDATA #REQUIRED

type         (inline|embed)

style-id     CDATA #IMPLIED

filteredFrom (swt|html)

encoding     CDATA #IMPLIED>

指示 HTML 通过嵌入整个文档或在适当位置直接插入 HTML 片段来包括在页面中。必须定义回退图像或文本以便呈示备用 SWT 表示。
嵌入允许在动态页面的内容中嵌入严格定义的 HTML 文件。将创建引用 HTML 文件的 HTML object 元素。
包括允许在动态 HTML 页面中包括直接取自文件的 HTML 片段。



<!ELEMENT include EMPTY>

<!ATTLIST include

configId    CDATA #IMPLIED

path        CDATA #REQUIRED

merge-style (true | false) >

展开给定路径指向的元素和可选 configId 属性。路径应该唯一指向指定配置中的某个元素。它可能指向在配置级别定义的共享组或页面中的任何元素。



<!ELEMENT anchor EMPTY>

<!ATTLIST anchor

id CDATA #REQUIRED>

锚点是用来声明可扩展性的元素。它是配置中允许有外部添加项的位置。只有锚点才是 extensionContent 中的路径属性的有效值。



<!ELEMENT extensionContent (text | group | link | html | include)>

<!ATTLIST extensionContent

style     CDATA #IMPLIED

alt-style CDATA #IMPLIED

path      CDATA #REQUIRED

content   CDATA #IMPLIED>

要添加至目标锚点的内容。在给定 configExtension 中只允许一个 extensionContent,这是因为如果未能解决此扩展 (如果找不到配置或者找不到目标锚点元素),就需要忽略扩展中的页面和/或组。



<!ELEMENT contentProvider (text?)>

<!ATTLIST contentProvider

id       CDATA #REQUIRED

pluginId CDATA #IMPLIED

class    CDATA #REQUIRED>

简介内容提供商的代理允许简介页从各种来源(Web 和 eclipse 等)动态拉出数据,并根据此动态数据在运行时提供内容。如果不能装入在类属性中指定的 IIntroContentProvider 类,则将代以呈示文本元素的内容。这是 html 简介页的动态版本。当该 html 标记允许将静态 html 内容嵌入或直接插入到所生成的 html 简介页中,则 contentProvider 标记允许在运行时动态创建内容。这些标记之间的不同之处是 html 标记仅支持 HTML 显示,而此 contentProvider 标记同时支持 HTML 和 SWT 显示。起始版本为 3.0.1



以下是配置扩展点的样本用法。

<extension id=

"intro"

point=

"org.eclipse.ui.intro.config"

>

<config introId=

"com.org.xyz.intro"

id=

"com.org.xyz.introConfig"

content=

"introContent.xml"

>

<presentation home-page-id=

"root"

title=

"%intro.title"

>

<implementation ws=

"win32"

style=

"css/shared.css"

kind=

"html"

os=

"win32"

>

</implementation>

<implementation style=

"css/shared_swt.properties"

kind=

"swt"

>

</implementation>

</presentation>

</config>

</extension>

有关进一步的详细信息,请参阅 org.eclipse.ui.intro.config API 包的细节。

org.eclipse.platform plugin 提供的简介是 Eclipse 中的唯一实现。