菜单

org.eclipse.ui.menus

3.2

此扩展点允许插件开发者定义菜单、分隔线、逻辑组和菜单项 - 它们可以显示在应用程序中的任何位置,这些位置既包括状态行,也包括上下文菜单。它还允许定义此类添加项的集合(即操作集);最终用户可以打开和关闭这些操作集。简而言之,菜单扩展点包含所有用于添加到 Eclipse 中的任何菜单或修剪区的表示元素(图标除外)。

此扩展点中的每个元素都具有唯一标识。因此,可以在其他位置引用这些元素,而不必重新声明它们。例如,在对操作集进行定义或排序时,可能需要使用此标识。并且,这还使第三方插件开发者能够适当地将这些元素放到接口中的新位置。

注意:对于 3.2 来说,在此扩展机制中,只实现了与“trim”添加项相关联的部分。添加项、菜单、工具栏或状态行条目的尝试将作为 NO-OP 工作。

<!ELEMENT extension (item* , menu* , group* , widget*)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT item (parameter* , location* , visibleWhen?)>

<!ATTLIST item

id        CDATA #REQUIRED

commandId CDATA #REQUIRED

menuId    CDATA #IMPLIED>

根据项所在位置的不同,它可以是菜单项或修剪项。与该项相关联的文本和图像将从命令中获取。



<!ELEMENT menu (location* , visibleWhen?)>

<!ATTLIST menu

id    CDATA #REQUIRED

label CDATA #IMPLIED>

菜单可以显示成与工具项相连接,也可以显示在视图菜单、上下文菜单或顶级菜单栏中的某个位置。为了方便地进行开发,插件开发者可以假定每个视图都有菜单和工具栏,并假定存在顶级菜单栏。在使用上下文菜单前,必须以编程方式注册它们(请参阅 API 信息)。

菜单只能包含组。



<!ELEMENT group (location*)>

<!ATTLIST group

id                CDATA #REQUIRED

separatorsVisible (true | false) "true">

逻辑组。此组可以是可视的(例如,适当地在前面和后面绘制分隔线),也可以是不可视的。缺省情况下,逻辑组是可视的。

组可以包含菜单、项和其他组。



<!ELEMENT widget (location* , class? , visibleWhen? , layout?)>

<!ATTLIST widget

id    CDATA #REQUIRED

class CDATA #REQUIRED>

能够直接访问窗口小部件的 menu 或 trim 元素。例如,此元素可用于显示组合框。不幸的是,这意味着如果某个窗口小部件元素变为在用户界面中可视,就会导致装入插件。由于此元素可能会引起性能问题,所以,使用时务必谨慎。这还将导致宏支持、脚本编制和许多其他基于命令的机制发生问题。当窗口小部件用作 trim 时,仅当该窗口小部件在 UI 中变为可视时才会导致插件装入。



<!ELEMENT layout EMPTY>

<!ATTLIST layout

fillMajor (true | false)

fillMinor (true | false) >

此元素可用来为添加到 trim 位置的元素指定各种布局选项。



<!ELEMENT location (order? , (bar | part | popup))>

<!ATTLIST location

mnemonic   CDATA #IMPLIED

imageStyle CDATA #IMPLIED>

可以显示菜单窗口小部件的位置。此元素用来控制特定于位置的信息。



<!ELEMENT bar EMPTY>

<!ATTLIST bar

type (menu|trim)

path CDATA #IMPLIED>

位置中的叶子元素。此元素可以是菜单栏或修剪区。如果未对此元素进行限定,则它指示顶级菜单栏或修剪区。如果使用 part 元素对此元素进行了限定,则此元素指示该部件的菜单或修剪区。



<!ELEMENT class (parameter*)>

<!ATTLIST class

class CDATA #REQUIRED>

一个 class 元素,它支持 widgetdynamic 元素的可执行文件扩展解析语法。



<!ELEMENT visibleWhen (not | or | and | instanceof | test | systemTest | equals | count | with | resolve | adapt | iterate)>

<!ATTLIST visibleWhen

checkEnabled (true | false) "false">

控制给定元素的可视性。



<!ELEMENT part (popup | bar)>

<!ATTLIST part

id    CDATA #IMPLIED

class CDATA #IMPLIED>

位置中的元素。此元素对位置进行限定以引用特定的工作台部件。此部件可以是视图或编辑器。此限定可以使用部件的类名(包括继承)来进行,也可以引用该视图或编辑器的标识。

只能指定 idclass,不能同时指定这两者。



<!ELEMENT parameter EMPTY>

<!ATTLIST parameter

name  CDATA #REQUIRED

value CDATA #REQUIRED>

可执行文件扩展或命令的参数 - 这取决于它在扩展中的出现位置。



<!ELEMENT order EMPTY>

<!ATTLIST order

position   (start|end|before|after)

relativeTo CDATA #IMPLIED>

控制菜单、组、项或窗口小部件在特定位置中的位置。



<!ELEMENT popup EMPTY>

<!ATTLIST popup

id   CDATA #IMPLIED

path CDATA #IMPLIED>

位置的部件。它指示菜单、组、项或窗口小部件应该显示在弹出菜单中。



<!ELEMENT enablement (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

通用根元素。可以在扩展点内使用该元素来定义它的支持表达式。将使用 and 运算符来组合 enablement 表达式的子代。



<!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 方法来测试系统属性并将结果与通过值属性指定的值进行比较。



<!ELEMENT equals EMPTY>

<!ATTLIST equals

value CDATA #REQUIRED>

此元素用来对焦点中的对象执行等于检查。如果对象等于由属性值提供的值,则表达式返回 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。将使用 and 运算符来组合 with 表达式的子代。



<!ELEMENT resolve (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST resolve

variable CDATA #REQUIRED

args     CDATA #IMPLIED>

此元素将把要检查以获取其所有子元素的对象更改为由给定变量引用的对象。如果不能解析变量,则表达式将在对变量求值时抛出 ExpressionException。将使用 and 运算符来组合 with 表达式的子代。



<!ELEMENT adapt (not , and , or , instanceof , test , systemTest , equals , count , with , resolve , adapt , iterate)*>

<!ATTLIST adapt

type CDATA #REQUIRED>

此元素用来使焦点中的对象适用于由属性类型指定的类型。如果尚未装入适配器或引用的类型,则表达式返回 not loaded。如果类型名称根本不存在,则表达式在求值期间将抛出 ExpressionException。将使用 and 运算符来组合 adapt 表达式的子代。



<!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。



基本菜单定义如下所示:

<menu id=

"com.mycompany.myplugin.projection"

label=

"%Folding.label"

>

<location mnemonic=

"%Folding.label.mnemonic"

>

<part id=

"AntEditor"

>

<popup id=

"#RulerContext"

path=

"rest"

/>

</part>

</location>

</menu>

在本示例中,插件开发者对所有创建给定类型的子类或实现给定类型的部件添加内容。例如,这将允许将某些添加项添加到所有文本编辑器中。

<menu id=

"com.mycompany.myplugin.textEditorMenu"

label=

"Text Commands"

>

<location mnemonic=

"X"

>

<part class=

"AbstractTextEditor"

>

<popup id=

"#RulerContext"

path=

"rest"

/>

</part>

</location>

</menu>

可以使帮助与菜单相关联。

<menu id=

"com.mycompany.myplugin.RunWithConfigurationAction"

label=

"Run With Configuration"

helpContextId=

"run_with_configuration_context"

>

<location>

<bar />

</location>

</menu>

在菜单中,可以定义逻辑组。这些逻辑组可以是可视的(例如,适当地在前面和后面绘制分隔线),也可以是不可视的。缺省情况下,逻辑组是可视的。

<group id=

"com.mycompany.myplugin.stepGroup"

>

<location>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</group>

<group id=

"com.mycompany.myplugin.stepIntoGroup"

separatorsVisible=

"false"

>

<location>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</group>

可以将菜单、组、项和窗口小部件放在多个位置。

<item id=

"com.mycompany.myplugin.ToggleStepFilters"

commandId=

"com.mycompany.myplugin.ToggleStepFilters"

>

<location mnemonic=

"%mnemonic"

>

<bar path=

"org.eclipse.ui.run/emptyStepGroup"

/>

</location>

<location>

<part id=

"org.eclipse.debug.ui.DebugView"

>

<bar type=

"trim"

path=

"renderGroup"

/>

</part>

</location>

<location mnemonic=

"%mnemonic"

>

<part id=

"org.eclipse.debug.ui.DebugView"

>

<popup path=

"renderGroup"

/>

</part>

</location>

</item>

如果指定的弹出元素不带标识和父部件元素,则它将应用于向工作台注册的任何上下文菜单。这与旧对象添加项的行为类似。同样,具有标识的顶级弹出元素将影响任何使用给定名称注册的上下文菜单。

<item id=

"com.mycompany.myplugin.ObjectContribution"

commandId=

"com.mycompany.myplugin.ObjectContribution"

>

<location>

<popup path=

"additions"

/>

</location>

</item>

有时,您可能想控制某个项的可视性。虽然通常最好保持菜单和工具栏布局稳定,但有时您可能希望隐藏某些并不直接相关的项。对于上下文菜单,当空间有限时,情况尤其如此。在这种情况下,可以定义 visibleWhen 元素。此元素几乎与处理程序扩展点中定义的 activeWhenenabledWhen 元素完全相同。

<item id=

"com.mycompany.myplugin.ConvertToWatchExpression"

commandId=

"com.mycompany.myplugin.ConvertToWatchExpression"

>

<location mnemonic=

"%mnemonic"

>

<part id=

"org.eclipse.debug.ui.DebugView"

>

<popup path=

"additions"

/>

</part>

</location>

<visibleWhen>

<with variable=

"selection"

>

<iterate operator=

"and"

>

<not>

<instanceof value=

"IWatchExpression"

/>

</not>

<instanceof value=

"IExpression"

/>

</iterate>

</with>

</visibleWhen>

</item>

最常见的情况仅仅是在某些内容的处理程序处于启用状态时使那些内容可视。这是通过一些语法修饰处理的。visibleWhen 元素有一个 checkEnabled 属性。

<item id=

"com.mycompany.myplugin.compareWithPatch"

commandId=

"com.mycompany.myplugin.compareWithPatch"

>

<location mnemonic=

"%mnemonic"

>

<part id=

"MyPart"

>

<popup path=

"additions"

/>

</part>

</location>

<visibleWhen checkEnabled=

"true"

/>

</item>

任何与命令相关联的项都可以包含参数值。如果未定义给定标识的参数,就会发生错误。如果该项没有命令,也会发生错误。

<item id=

"com.mycompany.myplugin.RunHistory"

commandId=

"com.mycompany.myplugin.RunHistory"

>

<location>

<bar path=

"org.eclipse.ui.run"

/>

</location>

<parameter name=

"index"

value=

"1"

/>

</item>

也可以指定相对排序。这是使用 location 元素的 order 属性实现的。order 属性接受下列值:start(将元素放在容器开头)、end(将元素放在容器末尾)、after(将元素放在标识与 ref 匹配的同代元素之后)和 before(将元素放在标识与 ref 匹配的同代元素之前)。可以对任何类型的菜单元素应用相对排序。

<item id=

"com.mycompany.myplugin.MyFirstItem"

commandId=

"com.mycompany.myplugin.MyFirstCommand"

>

<location>

<order position=

"start"

/>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</item>

<item id=

"com.mycompany.myplugin.MySecondItem"

commandId=

"com.mycompany.myplugin.MySecondCommand"

>

<location>

<order position=

"after"

relativeTo=

"com.mycompany.myplugin.MyFirstItem"

/>

<bar path=

"org.eclipse.ui.run"

/>

</location>

</item>

如果需要直接访问窗口小部件(例如,以便显示组合框),则可使用 widget 元素。不幸的是,这意味着如果某个窗口小部件元素变为在用户界面中可视,就会导致装入插件。

<widget id=

"com.mycompany.myplugin.MyComboBoxSimple"

class=

"com.mycompany.myplugin.MyComboBox"

>

<location>

<bar type=

"trim"

path=

"myGroup"

/>

</location>

</widget>

<widget id=

"com.mycompany.myplugin.MyComboBoxParameterized1"

class=

"com.mycompany.myplugin.MyComboBox:a,b,c"

>

<location>

<bar type=

"trim"

path=

"myGroup"

/>

</location>

</widget>

<widget id=

"com.mycompany.myplugin.MyComboBoxParameterized2"

>

<class class=

"com.mycompany.myplugin.MyComboBox"

>

<parameter name=

"list"

value=

"a,b,c"

/>

<parameter name=

"selected"

value=

"c"

/>

<parameter name=

"editable"

value=

"false"

/>

</class>

<location>

<bar type=

"trim"

path=

"myGroup"

/>

</location>

</widget>

还可以使用窗口小部件来对工作台修剪区添加内容。以下示例定义了新的“HeapStatus”窗口小部件。缺省情况下,应该将其刚好放在状态行修剪区后面(即,放在工作台窗口底部)。请参阅“bar”元素的描述以了解有关预定义组的更多信息。

注意,可以将修剪“组”重新定位到其他修剪区。位置信息的 relativeTo 在确定新修剪区的位置时将假定所引用的组在缺省位置。通常,此类型的添加程序将创建它们自己的组来存放新窗口小部件,从而允许独立于其他修剪元素来重新定位该修剪元素。一个值得注意的例外情况是“status”组。

   

<extension point=

"org.eclipse.ui.menus"

>

<group id=

"TestTrimAPI.heapStatusGroup"

separatorsVisible=

"true"

>

<location>

<bar type=

"trim"

/>

<order position=

"after"

relativeTo=

"status"

/>

</location>

</group>

<widget class=

"HeapStatusWidget"

id=

"TestTrimAPI.HeapStatus"

>

<location>

<bar path=

"heapStatusGroup"

type=

"trim"

/>

</location>

<layout fillMajor=

"false"

fillMinor=

"true"

/>

</widget>

</extension>

要注册上下文菜单,请使用 IWorkbenchPartSite.registerContextMenu 方法。