当选择是多机种选择时,若有可能,将应用添加项(如果是针对公共选择类型注册)。如果不可能直接进行匹配,则会尝试针对超类和超接口进行匹配。
可通过使用名称过滤器进一步限制选择。如果使用了名称过滤器,则选择中的所有对象必须与过滤器匹配才可以应用添加项。
对象添加项中的个别的操作可使用属性 enablesFor 来指定它是应仅应用于单个选择类型、多个选择类型还是应该应用于任何其它选择类型。
如果这些过滤机制不足够,则操作添加项可使用 filter 机制。在这种情况下,将在一系列“名称 - 值”对中描述目标对象的属性。适用于选择的属性是特定于类型的,且超出了工作台本身的域,因此工作台将代表在此级别上过滤为实际选择的操作。
操作的启用和/或可视性分别可使用元素 enablement 和 visibility 定义。这两个元素包含进行求值来确定启用和/或可视性的布尔表达式。
enablement 和 visibility 元素的语法相同。两者都只包含一个布尔表达式子元素。在最简单的情况下,这将是 objectClass、objectState、pluginState 或 systemProperty 元素。在更复杂的情况下,可复合 and、or 和 not 元素来组成布尔表达式。and 和 or 元素必须包含 2 个子元素。not 元素一定只能包含 1 个子元素。
<!ELEMENT extension (objectContribution , viewerContribution)>
<!ATTLIST extension
point CDATA #REQUIRED
id CDATA #IMPLIED
name CDATA #IMPLIED>
<!ELEMENT objectContribution (filter* , visibility? , enablement? , menu* , action*)>
<!ATTLIST objectContribution
id CDATA #REQUIRED
objectClass CDATA #REQUIRED
nameFilter CDATA #IMPLIED
adaptable (true | false) "false">
此元素用来定义(为其选择了指定类型的对象的)任何查看器上下文菜单的一组操作和/或菜单。
<!ELEMENT viewerContribution (visibility? , menu* , action*)>
<!ATTLIST viewerContribution
id CDATA #REQUIRED
targetID CDATA #REQUIRED>
此元素用来定义特定视图或编辑器部件上下文菜单的一组操作和/或菜单。
<!ELEMENT action (selection* , enablement?)>
<!ATTLIST action
id CDATA #REQUIRED
label CDATA #REQUIRED
definitionId CDATA #IMPLIED
menubarPath CDATA #IMPLIED
icon CDATA #IMPLIED
helpContextId CDATA #IMPLIED
style (push|radio|toggle|pulldown)
state (true | false)
class CDATA #REQUIRED
enablesFor CDATA #IMPLIED
overrideActionId CDATA #IMPLIED
tooltip CDATA #IMPLIED>
此元素定义用户可在用户界面中调用的操作。
push | - 作为普通菜单项或工具项。 | |
radio | - 作为单选样式菜单项或工具项。同一菜单或工具栏组内具有单选样式的操作相当于单选按钮集。初始值由 state 属性指定。 | |
toggle | - 作为复选样式菜单项或切换工具项。初始值由 state 属性指定。 | |
pulldown | - 作为级联样式菜单项。 |
! | - 选择了零项 | |
? | - 选择了零项或一项 | |
+ | - 选择了一项或多项 | |
multiple, 2+ | - 选择了两项或多项 | |
n | - 选择了精确数目的项。例如:nablesFor=" 4" 仅当选择了 4 个项时才启用操作。 | |
* | - 选择了任意数目的项 |
操作扩展的启用标准最初是由 enablesFor、selection 和 enablement 定义的。但是,一旦操作代表被实例化,它就可以直接在它的 selectionChanged 方法中控制操作启用状态。
<!ELEMENT filter EMPTY>
<!ATTLIST filter
name CDATA #REQUIRED
value CDATA #REQUIRED>
此元素用来对当前选择中的每个对象的属性状态求值。仅当选择中的每个对象都具有指定的属性状态时才匹配。选择中的每个对象都必须实现或适用于 org.eclipse.ui.IActionFilter。
<!ELEMENT menu (separator+ , groupMarker*)>
<!ATTLIST menu
id CDATA #REQUIRED
label CDATA #REQUIRED
path CDATA #IMPLIED>
此元素用来定义新菜单。
<!ELEMENT separator EMPTY>
<!ATTLIST separator
name CDATA #REQUIRED>
此元素用于在新菜单中创建菜单分隔符。
<!ELEMENT groupMarker EMPTY>
<!ATTLIST groupMarker
name CDATA #REQUIRED>
此元素用来在新菜单中创建已命名组。它在新菜单中没有可视表示,这与 separator 元素不同。
<!ELEMENT selection EMPTY>
<!ATTLIST selection
class CDATA #REQUIRED
name CDATA #IMPLIED>
此元素用来帮助确定根据当前选择是否启用操作。如果指定了 enablement 元素,则忽略它。
<!ELEMENT enablement (and | or | not | objectClass | objectState | pluginState | systemProperty)>
此元素用来定义扩展的启用。
<!ELEMENT visibility (and | or | not | objectClass | objectState | pluginState | systemProperty)>
此元素用来定义扩展的可视性。
<!ELEMENT and (and | or | not | objectClass | objectState | pluginState | systemProperty)>
此元素表示对其两个子元素表达式求值的结果的布尔 AND 操作。
<!ELEMENT or (and | or | not | objectClass | objectState | pluginState | systemProperty)>
此元素表示对其两个子元素表达式求值的结果的布尔 OR 操作。
<!ELEMENT not (and | or | not | objectClass | objectState | pluginState | systemProperty)>
此元素表示对其子元素表达式求值的结果的布尔 NOT 操作。
<!ELEMENT objectClass EMPTY>
<!ATTLIST objectClass
name CDATA #REQUIRED>
此元素用来对当前选择中的每个对象的类或接口进行求值。如果选择中的每个对象都实现指定的类或接口,则表达式求值为 true。
<!ELEMENT objectState EMPTY>
<!ATTLIST objectState
name CDATA #REQUIRED
value CDATA #REQUIRED>
此元素用来对当前选择中的每个对象的属性状态求值。如果选择中的每个对象都具有指定的属性状态,则表达式求值为 true。要对此类型的表达式进行求值,选择中的每个对象都必须实现或采用 org.eclipse.ui.IActionFilter 接口。
<!ELEMENT pluginState EMPTY>
<!ATTLIST pluginState
id CDATA #REQUIRED
value (installed|activated) "installed">
此元素用来对插件的状态进行求值。插件的状态可以是下列其中一项:installed 或 activated。
<!ELEMENT systemProperty EMPTY>
<!ATTLIST systemProperty
name CDATA #REQUIRED
value CDATA #REQUIRED>
此元素用来对某些系统属性的状态进行求值。属性值是从 java.lang.System 中检索的。
<!ELEMENT enablement (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
通用根元素。可以在扩展点内使用该元素来定义它的支持表达式。支持表达式的子代是使用 AND 运算符来组合的。
<!ELEMENT not (not | and | or | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>
此元素表示对其子元素表达式求值的结果的 NOT 操作。
<!ELEMENT and (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
此元素表示对其所有子元素表达式求值的结果的 AND 操作。
<!ELEMENT or (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
此元素表示对其所有子元素表达式求值的结果的 OR 操作。
<!ELEMENT instanceof EMPTY>
<!ATTLIST instanceof
value CDATA #REQUIRED>
此元素用来对具有焦点的对象执行 instanceof 检查。如果对象的类型是由属性值指定的类型的子类型,则表达式将返回 EvaluationResult.TRUE。否则将返回 EvaluationResult.FALSE。
<!ELEMENT test EMPTY>
<!ATTLIST test
property CDATA #REQUIRED
args CDATA #IMPLIED
value CDATA #IMPLIED>
此元素用来对具有焦点的对象的属性状态求值。可以使用属性测试对象扩展点来扩展一组可以测试的属性。如果尚未装入执行实际测试的属性测试对象,则测试表达式将返回 EvaluationResult.NOT_LOADED。
<!ELEMENT systemTest EMPTY>
<!ATTLIST systemTest
property CDATA #REQUIRED
value CDATA #REQUIRED>
通过调用 System.getProperty 方法并将结果与通过 value 属性指定的值进行比较来测试系统属性。
<!ELEMENT equals EMPTY>
<!ATTLIST equals
value CDATA #REQUIRED>
此元素用来对具有焦点的对象执行相等检查。如果对象等于由属性 value 提供的值,则表达式将返回 EvaluationResult.TRUE。否则将返回 EvaluationResult.FALSE。
<!ELEMENT count EMPTY>
<!ATTLIST count
value CDATA #REQUIRED>
此元素用来测试集合中的元素数。
<!ELEMENT with (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST with
variable CDATA #REQUIRED>
此元素将要对它的所有子元素检查的对象更改为给定变量所引用的对象。如果不能解析该变量,则在对表达式求值时表达式将抛出 ExpressionException。with 表达式的子代是使用 AND 运算符来组合的。
<!ELEMENT resolve (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST resolve
variable CDATA #REQUIRED
args CDATA #IMPLIED>
此元素将要对它的所有子元素检查的对象更改为给定变量所引用的对象。如果不能解析该变量,则在对表达式求值时表达式将抛出 ExpressionException。with 表达式的子代是使用 AND 运算符来组合的。
<!ELEMENT adapt (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST adapt
type CDATA #REQUIRED>
此元素用来使具有焦点的对象适用于由属性 type 指定的类型。如果尚未装入适配器或引用的类型,则表达式返回 not loaded。如果类型名根本不存在,则在求值期间它将抛出 ExpressionException。adapt 表达式的子代是使用 AND 运算符来组合的。
<!ELEMENT iterate (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>
<!ATTLIST iterate
operator (or|and) >
此元素用来对类型为 java.util.Collection 的变量进行迭代。如果具有焦点的对象不具有 java.util.Collection 类型,则在对表达式求值时将抛出 ExpressionException。
在上面的示例中,指定的对象添加操作将仅支持单个选择(enablesFor 属性)。另外,选择中的每个对象还必须实现指定的接口(IFile)且必须是 Java 文件。将把此操作添加到先前创建的子菜单中。此添加项将在具有所需选择的任何视图中生效。<extension point=
"org.eclipse.ui.popupMenus"
>
<objectContribution id=
"com.xyz.C1"
objectClass=
"org.eclipse.core.resources.IFile"
nameFilter=
"*.java"
>
<menu id=
"com.xyz.xyzMenu"
path=
"additions"
label=
"&XYZ Java Tools"
>
<separator name=
"group1"
/>
</menu>
<action id=
"com.xyz.runXYZ"
label=
"&Run XYZ Tool"
style=
"push"
menubarPath=
"com.xyz.xyzMenu/group1"
icon=
"icons/runXYZ.gif"
helpContextId=
"com.xyz.run_action_context"
class=
"com.xyz.actions.XYZToolActionDelegate"
enablesFor=
"1"
>
</action>
</objectContribution>
<viewerContribution id=
"com.xyz.C2"
targetID=
"org.eclipse.ui.views.TaskList"
>
<action id=
"com.xyz.showXYZ"
label=
"&Show XYZ"
style=
"toggle"
state=
"true"
menubarPath=
"additions"
icon=
"icons/showXYZ.gif"
helpContextId=
"com.xyz.show_action_context"
class=
"com.xyz.actions.XYZShowActionDelegate"
>
</action>
</viewerContribution>
</extension>
相反,上述查看器添加项将仅出现在“任务”视图上下文菜单中,且不会受视图中的选择影响。
以下是过滤器机制的一个示例。在这种情况下,操作将仅对已完成且具有高优先级的 IMarkers 出现。
以下是使用 visibility 元素的另一个示例:<extension point=
"org.eclipse.ui.popupMenus"
>
<objectContribution id=
"com.xyz.C3"
objectClass=
"org.eclipse.core.resources.IMarker"
>
<filter name=
"done"
value=
"true"
/>
<filter name=
"priority"
value=
"2"
/>
<action id=
"com.xyz.runXYZ"
label=
"High Priority Completed Action Tool"
icon=
"icons/runXYZ.gif"
class=
"com.xyz.actions.MarkerActionDelegate"
>
</action>
</objectContribution>
</extension>
<extension point=
"org.eclipse.ui.popupMenus"
>
<viewerContribution id=
"com.xyz.C4"
targetID=
"org.eclipse.ui.views.TaskList"
>
<visibility>
<and>
<pluginState id=
"com.xyz"
value=
"activated"
/>
<systemProperty name=
"ADVANCED_MODE"
value=
"true"
/>
</and>
</visibility>
<action id=
"com.xyz.showXYZ"
label=
"&Show XYZ"
style=
"push"
menubarPath=
"additions"
icon=
"icons/showXYZ.gif"
helpContextId=
"com.xyz.show_action_context"
class=
"com.xyz.actions.XYZShowActionDelegate"
>
</action>
</viewerContribution>
</extension>
在上面的示例中,指定的操作将作为“任务”视图上下文菜单中的菜单项出现,但仅当“com.xyz”插件是活动的且指定的系统属性被设置为 true 时才出现。
注意:为了保持向后兼容性,可为对象添加项实现 org.eclipse.ui.IActionDelegate。
仅当目标部件发布供扩展的菜单时,部件内的上下文菜单扩展才有可能进行。我们极力鼓励这样做,原因是这样会提高产品的可扩展性。要完成此任务,每个部件都应该发布通过调用 IWorkbenchPartSite.registerContextMenu 来定义的任何上下文菜单。一旦完成此任务,则工作台将自动插入存在的任何操作扩展。
必须为每个已注册的菜单提供菜单标识。为获得各部件的一致性,所有部件实现器都应采用下列策略。
向工作台注册的任何上下文菜单还应该包含具有标识 IWorkbenchActionConstants.MB_ADDITIONS 的标准插入点。其它插件将把此值用作插入的参考点。可通过将 GroupMarker 添加至菜单的适当插入位置来定义插入点。
在上下文菜单中选择的工作台中的对象可定义 org.eclipse.ui.IActionFilter。这是可以执行特定于类型的过滤的过滤策略。工作台将通过测试以了解过滤器是否实现 IActionFilter 来检索供选择的过滤器。如果失败,则工作台将通过 IAdaptable 机制来请求过滤器。
在翻译文本中,操作和菜单标签可包含特殊字符,这些特殊字符对助记符进行编码,这些助记符是在所选字符前用和号(“&”)字符指定的。由于 XML 字符串中不允许有“与”符号,所以使用 & 字符实体。
如果通过单个扩展将两个或多个操作添加到了菜单中,则这些操作出现的顺序将与 plugin.xml 文件中列示它们的顺序相反。此行为很明显是不直观的。但是,这是在冻结“Eclipse 平台 API”之后才发现的。现在更改该行为将破坏依赖于现有行为的每个插件。
selection 和 enablement 元素是互斥的。enablement 元素可以使用子元素 objectClass 和 objectState 替换 selection 元素。例如,下面内容:
可使用以下内容表示:<selection class=
"org.eclipse.core.resources.IFile"
name=
"*.java"
>
</selection>
<enablement>
<and>
<objectClass name=
"org.eclipse.core.resources.IFile"
/>
<objectState name=
"extension"
value=
"java"
/>
</and>
</enablement>
Copyright (c) 2000, 2004 IBM Corporation and others.
All rights reserved. 本程序及所附带提供的资料依据 Common Public License v1.0 的条款方可使用,本发行中提供了该许可条款,并且在以下位置也可获得该条款:http://www.eclipse.org/legal/cpl-v10.html。