公共查看器配置

org.eclipse.ui.navigator.viewer

3.2

查看器元素定义公共查看器的配置。扩展可以提供公共弹出菜单标识, 而不管查看器是否向链接提供编辑器支持、是否提供过滤器对话框和/或“可用的定制”对话框。另外,嵌套的配置元素可以对弹出上下文菜单的结构和行为进行全面的控制。

viewerContentBinding 将已定义的内容扩展(通过 navigatorContent 扩展点)绑定至查看器(通过 org.eclipse.ui.views 扩展点定义)。绑定到查看器的任何内容扩展都被描述为可视。 内容服务(org.eclipse.ui.navigator.INavigatorContentService) 将不返回其查看器标识不可视的任何扩展名。

<!ELEMENT extension (viewer* , viewerContentBinding* , viewerActionBinding* , dragAssistant)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT viewer (popupMenu? , options?)>

<!ATTLIST viewer

viewerId    CDATA #REQUIRED

popupMenuId CDATA #IMPLIED>

提供建立查看器特征的基本配置。客户机还必须定义 org.eclipse.ui.views 扩展名以创建视图部件。



<!ELEMENT viewerContentBinding (includes? , excludes?)>

<!ATTLIST viewerContentBinding

viewerId CDATA #REQUIRED>

客户机必须定义一个或多个 viwerContentBinding 元素以描述 查看器可视的内容扩展和公共过滤器。如果内容扩展或公共过滤器匹配 viewerContentBinding 下的 includes 语句,而且不被 excludes 语句排除,则 内容扩展或公共过滤器可视。如果内容扩展或公共过滤器对查看器不可视,则该查看器的内容服务将不再要求获取该扩展的内容,也不会在可用的过滤器对话框中将该扩展内容显示给用户。

客户机可以定义 includes 元素以选择对查看器可视的扩展,并为查看器不可视的扩展定义类似的 excludes 元素。 客户机可以进一步通过“isRoot”属性定义将对根元素明确查询的扩展(通过 ITreeContentProvider.getElements())。如果一个或多个 contentExtension 元素在 includes 语句中将“isRoot”设置为 true,则仅对根元素查询那些扩展。“isRoot”属性不影响排除。

查看器可以定义多个 viewerContentBindings,并且聚集它们的 includes/excludes 语句以产生最终行为。



<!ELEMENT viewerActionBinding (includes? , excludes?)>

<!ATTLIST viewerActionBinding

viewerId CDATA #REQUIRED>

客户机必须定义对其查看器可视的操作提供程序。客户机可以定义 includes 元素以选择对查看器可视的扩展,类似地,扩展的 excludes 元素将对查看器不可视。

查看器可以定义多个 viewerActionBinding,并且聚集它们的 includes/excludes 语句以产生最终行为。

对于没有嵌套在 navigatorContent 定义下的 actionProvider 定义,客户机可以指定定制标识。如果客户机没有指定标识,则标识缺省为“org.eclipse.ui.navigator.actionProvider.X”。 如果要获得不带特定标识的 actionProvider,则客户机必须对缺省标识定义 viewerActionBinding。请参阅示例部分,以了解操作详情。



<!ELEMENT includes ((contentExtension+) | (actionExtension+))>

定义在查找匹配“viewerId”属性的查看器的内容扩展时应该包括的一组模式。 当 includes 和 excludes 语句交叉使用时,将给予 includes 语句优先权。



<!ELEMENT excludes ((contentExtension+) | (actionExtension+))>

定义在查找匹配“viewerId”属性的查看器的内容扩展时应该排除的一组模式。 当 includes 和 excludes 语句交叉使用时,将给予 includes 语句优先权。



<!ELEMENT contentExtension EMPTY>

<!ATTLIST contentExtension

pattern CDATA #REQUIRED

isRoot  (true | false) >

指示内容扩展的标识(或匹配模式)。ITreeContentProvider.getElements()ITreeContentProvider.getChildren() 应该查询此内容扩展以获取应该在“可用的过滤器”对话框中提供给用户使用的查看器或公共过滤器的根。

客户机可以指定“isRoot”以选择特定根扩展来覆盖将不对查看器输入元素启用的扩展(基于查看器输入元素的匹配 triggerPoints 表达式)。

请参阅 viewerContentBinding 文档以了解更多信息。



<!ELEMENT actionExtension EMPTY>

<!ATTLIST actionExtension

pattern CDATA #REQUIRED>

指示操作扩展可以有上下文菜单和操作栏。

请参阅 viewerActionBinding 的文档以了解更多信息。



<!ELEMENT popupMenu (insertionPoint*)>

<!ATTLIST popupMenu

id                          CDATA #IMPLIED

allowsPlatformContributions (true | false) >

如果未指定 viewer 元素的“popupMenuId”属性,则仅能定义 popupMenu 元素。

popupMenu 元素允许进一步定制与查看器相关联的上下文菜单。 为了正确应用选项,查看器的实例必须代表 org.eclipse.ui.navigator.NavigatorActionService,其行为类似于正常的 org.eclipse.ui.ActionGroup。有关开发此功能的更多信息,请参阅此 API 类的文档。 对于使用 org.eclipse.ui.navigator.CommonNavigator 实例的客户机,不需要执行任何额外工作。

popupMenu 声明一个或多个 insertionPoints,添加程序将使用它们以将添加项组织到有意义的、对用户更友好的一致性列表中。
如果客户机仅指定 viewer 元素的 “popupMenuId”属性,则上下文菜单使用的一组 insertionPoints 将按给定的顺序缺省为以下列表:

"group.new"             separator="true"
"group.goto"            
"group.open"            separator="true"
"group.openWith"
"group.show"            separator="true"
"group.edit"            separator="true"
"group.reorganize"
"group.port"
"group.generate"        separator="true"
"group.search"          separator="true"
"group.build"           separator="true"
"additions"             separator="true" 
"group.properties"      separator="true"


需要以程序方式引用这些值的客户机可以使用 org.eclipse.ui.navigator.ICommonMenuConstants 中相应的常量。

鼓励要定制菜单的客户机使用此列表启动,并根据需要添加或除去插入点。此外,还鼓励客户机遵循每个组名以“group.”开头的模式。

如果指定了 popupMenu 元素并且该元素不包含 insertionPoint 子元素,则上下文菜单不具有已发布的插入点。当然,不会限制编程客户机 根据需要添加自己的插入点。 鼓励定义查看器的客户机为文档发布插入点,并使它们的查看器/导航器清楚下游扩展,或者 显式记录哪些插入点作为 API,哪些作为内部插入点。



<!ELEMENT insertionPoint EMPTY>

<!ATTLIST insertionPoint

name      CDATA #REQUIRED

separator (true | false) >

定义上下文菜单的插入点。包括客户机要引用的点的名称,以及是否将插入点作为分隔符或组标记。



<!ELEMENT options (property+)>

向查看器提供选项,以定制查看器显示给用户的外观。请参阅 org.eclipse.ui.navigator.INavigatorViewerDescriptor 以了解可用的属性。



<!ELEMENT property EMPTY>

<!ATTLIST property

name  CDATA #REQUIRED

value CDATA #REQUIRED>

提供 name=value 对。将按此样式向查看器提供值(所以空字符串将按空字符串进行传播)。请参阅 org.eclipse.ui.navigator.INavigatorViewerDescriptor 以了解可用的属性及其描述。



<!ELEMENT dragAssistant EMPTY>

<!ATTLIST dragAssistant

class    CDATA #REQUIRED

viewerId CDATA #REQUIRED>

拖放助手提供轻量级挂钩以提供额外的传输类型和逻辑来设置拖放数据。由于 org.eclipse.ui.navigator.CommonViewer 提供了 org.eclipse.ui.jface.util.LocalSelectionTransfer 类型,所以不需要此元素。

客户机将仅在轻量级插件中使用浅依赖关系树定义此扩展。在创建查看器时必须预先装入拖动助手,这将强制装入受影响的插件。



以下示例配置查看器的弹出菜单。


   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewer id=

"org.eclipse.testViewer"

popupMenuId=

"org.eclipse.testViewer#PopupMenu"

/>

</extension>

因为没有在以上示例中使用查看器的 popupMenu 子元素, 所以将使用 insertionPoints 的缺省组。此组定义如下所示。 有关更多信息,请参阅 popupMenu 元素的文档。

"group.new"             separator="true"
"group.goto"            
"group.open"            separator="true"
"group.openWith"
"group.show"            separator="true"
"group.edit"            separator="true"
"group.reorganize"
"group.port"
"group.generate"        separator="true"
"group.search"          separator="true"
"group.build"           separator="true"
"additions"             separator="true" 
"group.properties"      separator="true"

以下示例演示了声明定制 popupMenu/insertionPoints 的查看器配置,但使用“allowsPlatformContributions”属性限制对象和查看器添加项。客户机仅可以通过为查看器 (顶级或关联的内容扩展)声明的 org.eclipse.ui.navigator.CommonActionProvider 添加已定义的菜单。

注意,“popupMenuId”属性不能与 popupMenu 元素同时指定。只有一个是有效的配置,但两者不同时有效。

   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewer viewerId=

"org.eclipse.ui.navigator.resourceContent"

>

<popupMenu allowsPlatformContributions=

"false"

id=

"org.eclipse.ui.navigator.resourceContent#PopupMenu"

>

<insertionPoint name=

"group.new"

/>

<insertionPoint name=

"group.open"

separator=

"true"

/>

<insertionPoint name=

"group.openWith"

/>

<insertionPoint name=

"group.port"

separator=

"true"

/>

<insertionPoint name=

"additions"

separator=

"true"

/>

<insertionPoint name=

"group.properties"

separator=

"true"

/>

</popupMenu>

</viewer>

<viewerContentBinding viewerId=

"org.eclipse.ui.navigator.resourceContent"

>

<includes>

<contentExtension pattern=

"org.eclipse.ui.navigator.resourceContent"

/>

</includes>

</viewerContentBinding>

</extension>

以下示例声明将一个内容扩展(标识:“org.eclipse.ui.navigator.resourceContent”)绑定到与标识“org.eclipse.ui.navigator.resourceContent”匹配的查看器。(在此示例中,内容扩展和查看器标识匹配,但这不是必需的。)此外,将忽略标识以“org.eclipse.ui.navigator.tests.”开头的任何内容扩展。

   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewerContentBinding viewerId=

"org.eclipse.ui.navigator.resourceContent"

>

<includes>

<contentExtension pattern=

"org.eclipse.ui.navigator.resourceContent"

/>

</includes>

<excludes>

<contentExtension pattern=

"org.eclipse.ui.navigator.tests.*"

/>

</excludes>

</viewerContentBinding>

</extension>

以下示例对所有匹配正则表达式“org.acme.actions.*”但不匹配“org.acme.actions.tests.*”的 actionProvider(没有嵌套在 navigatorContent 扩展下)声明 viewerActionBinding。此表达式将使 标识以“org.acme.actions.”而非“org.acme.actions.tests.”开头的任何 actionProvider 对标识为“org.acme.viewer”的查看器可视。 当然,viewerActionBindings 仅适用于没有嵌套在 navigatorContent 元素下的 actionProvider 元素。嵌套的 actionProvider 元素的可视性是由外层的 navigatorContent 元素的 viewerContentBindings 控制的。

   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewerActionBinding viewerId=

"org.acme.viewer"

>

<includes>

<actionExtension pattern=

"org.acme.actions.*"

/>

</includes>

<excludes>

<actionExtension pattern=

"org.acme.actions.tests.*"

/>

</excludes>

</viewerActionBinding>

</extension>

以下示例使任何不带“id”属性的 actionProvider 对查看器“org.acme.viewer”可视。 不带“id”属性的 actionProvider 具有缺省标识“org.eclipse.ui.navigator.actionProvider.X”。当然,viewerActionBindings 仅适用于没有嵌套在 navigatorContent 元素下的 actionProvider 元素。嵌套的 actionProvider 元素的 visibility 是由 外层 navigatorContent 元素的 viewerContentBinding 控制的。

   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewerActionBinding viewerId=

"org.acme.viewer"

>

<includes>

<actionExtension pattern=

"org.eclipse.ui.navigator.actionProvider.*"

/>

</includes>

</viewerActionBinding>

</extension>

以下示例演示了可用于查看器的标准属性。

   

<extension point=

"org.eclipse.ui.navigator.viewer"

>

<viewer popupMenuId=

"org.eclipse.ui.tests.navigator.TestView#PopupMenu"

viewerId=

"org.eclipse.ui.tests.navigator.TestView"

>

<options>

<!-- Hide the

"Available Extensions"

tab in the

"Available Customizations"

dialog (available from the

"Filters"

action -->

<property name=

"org.eclipse.ui.navigator.hideAvailableExtensionsTab"

value=

"true"

/>

<!-- Hide the

"Available Customizations"

dialog completely. This includes hiding the filters and the available content extensions. -->

<property name=

"org.eclipse.ui.navigator.hideAvailableCustomizationsDialog"

value=

"true"

/>

<!-- Hide the

"Link with Editor"

action from the toolbar of the viewer -->

<property name=

"org.eclipse.ui.navigator.hideLinkWithEditorAction"

value=

"true"

/>

<!-- Hide the

"Collapse All"

action from the toolbar of the viewer -->

<property name=

"org.eclipse.ui.navigator.hideCollapseAllAction"

value=

"true"

/>

</options>

</viewer>

</extension>