操作集

org.eclipse.ui.actionSets

此扩展点用来将菜单、菜单项和工具栏按钮添加到“工作台”窗口中的公共区域。将这些添加项统称为操作集并由定制透视图的用户安排出现在“工作台”窗口中。

操作的启用和/或可视性分别可使用元素 enablementvisibility 定义。这两个元素包含进行求值来确定启用和/或可视性的布尔表达式。

enablementvisibility 元素的语法相同。两者都只包含一个布尔表达式子元素。在最简单的情况下,这将是 objectClassobjectStatepluginStatesystemProperty 元素。在更复杂的情况下,可复合 andornot 元素来组成布尔表达式。andor 元素必须包含 2 个子元素。not 元素一定只能包含 1 个子元素。

<!ELEMENT extension (actionSet+)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT actionSet (menu* , action*)>

<!ATTLIST actionSet

id          CDATA #REQUIRED

label       CDATA #REQUIRED

visible     (true | false)

description CDATA #IMPLIED>

此元素用来定义一组操作和/或菜单。



<!ELEMENT action (selection* | enablement?)>

<!ATTLIST action

id               CDATA #REQUIRED

label            CDATA #REQUIRED

accelerator      CDATA #IMPLIED

definitionId     CDATA #IMPLIED

menubarPath      CDATA #IMPLIED

toolbarPath      CDATA #IMPLIED

icon             CDATA #IMPLIED

disabledIcon     CDATA #IMPLIED

hoverIcon        CDATA #IMPLIED

tooltip          CDATA #IMPLIED

helpContextId    CDATA #IMPLIED

style            (push|radio|toggle|pulldown) "push"

state            (true | false)

pulldown         (true | false)

class            CDATA #IMPLIED

retarget         (true | false)

allowLabelUpdate (true | false)

enablesFor       CDATA #IMPLIED>

此元素定义用户可在用户界面中调用的操作。



<!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(相当于 OSGi 概念中的“resolved”)或者 activated(相当于 OSGi 概念中的“active”)。



<!ELEMENT systemProperty EMPTY>

<!ATTLIST systemProperty

name  CDATA #REQUIRED

value CDATA #REQUIRED>

此元素用来对某些系统属性的状态进行求值。属性值是从 java.lang.System 中检索的。



以下是操作集的示例(注意子元素和使用属性的方法):

    

<extension point =

"org.eclipse.ui.actionSets"

>

<actionSet id=

"com.xyz.actionSet"

label=

"My Actions"

>

<menu id=

"com.xyz.xyzMenu"

label=

"XYZ Menu"

path=

"additions"

>

<separator name=

"group1"

/>

<separator name=

"option1"

/>

</menu>

<action id=

"com.xyz.runXYZ"

label=

"&amp;Run XYZ Tool"

style=

"toggle"

state=

"false"

menubarPath=

"com.xyz.xyzMenu/group1"

icon=

"icons/runXYZ.gif"

tooltip=

"Run XYZ Tool"

helpContextId=

"com.xyz.run_action_context"

class=

"com.xyz.actions.RunXYZ"

enablesFor=

"1"

>

<selection class=

"org.eclipse.core.resources.IFile"

name=

"*.java"

/>

</action>

<action id=

"com.xyz.runABC"

label=

"&amp;Run ABC Tool"

style=

"push"

menubarPath=

"com.xyz.xyzMenu/group1"

toolbarPath=

"Normal/XYZ"

icon=

"icons/runABC.gif"

tooltip=

"Run ABC Tool"

helpContextId=

"com.xyz.run_abc_action_context"

retarget=

"true"

allowLabelUpdate=

"true"

>

<enablement>

<and>

<objectClass name=

"org.eclipse.core.resources.IFile"

/>

<not>

<objectState name=

"extension"

value=

"java"

/>

</not>

</and>

</enablement>

</action>

<action id=

"com.xyz.runDEF"

label=

"&amp;Run DEF Tool"

style=

"radio"

state=

"true"

menubarPath=

"com.xyz.xyzMenu/option1"

icon=

"icons/runDEF.gif"

tooltip=

"Run DEF Tool"

class=

"com.xyz.actions.RunDEF"

helpContextId=

"com.xyz.run_def_action_context"

>

</action>

<action id=

"com.xyz.runGHI"

label=

"&amp;Run GHI Tool"

style=

"radio"

state=

"false"

menubarPath=

"com.xyz.xyzMenu/option1"

icon=

"icons/runGHI.gif"

tooltip=

"Run GHI Tool"

class=

"com.xyz.actions.RunGHI"

helpContextId=

"com.xyz.run_ghi_action_context"

>

</action>

<action id=

"com.xyz.runJKL"

label=

"&amp;Run JKL Tool"

style=

"radio"

state=

"false"

menubarPath=

"com.xyz.xyzMenu/option1"

icon=

"icons/runJKL.gif"

tooltip=

"Run JKL Tool"

class=

"com.xyz.actions.RunJKL"

helpContextId=

"com.xyz.run_jkl_action_context"

>

</action>

</actionSet>

</extension>

在上面的示例中,指定的操作集(名为“My Actions”)在每一个透视图中最初是不可视的,原因是未指定 visible 属性。

XYZ 操作将作为复选框菜单项出现,最初是未选择的。仅当选择计数为 1 并且选择包含一个 Java 文件资源时才会启用它。

ABC 操作将同时出现在菜单中和工具栏上。仅当选择不包含任何 Java 文件资源时才会启用它。另外也请注意,这是一个标签重定向目标操作,因此它不提供 class 属性。

操作 DEF、GHI 和 JKL 作为单选按钮菜单项出现。不管当前选择状态是什么,它们都一直启用。

class 属性的值必须是实现 org.eclipse.ui.IWorkbenchWindowActionDelegateorg.eclipse.ui.IWorkbenchWindowPulldownDelegate 的类的标准名称。后者应在 style 属性具有值 pulldown 的情况下实现。此类是负责执行操作的处理程序。如果 retarget 属性为 true,则忽略并且不应提供此属性。尽可能迟地装入此类以避免在真正需要整个插件之前就装入该插件。

操作扩展的启用条件最初由 enablesFor 定义,也可以是 selectionenablement。但是,一旦将操作代表实例化,它就可以直接在它的 selectionChanged 方法中控制操作启用状态。

请一定注意,工作台不会代表插件生成菜单。菜单路径必须引用已经存在的菜单。

操作和菜单标签可包含使用以下规则编码助记符的特殊字符:

  1. 在翻译的文本中,是在所选字符前面加“与”符号(“&”)字符来指定助记符的。由于 XML 字符串中不允许有“与”符号,所以使用 &amp; 字符实体。
如果通过单个扩展将两个或多个操作添加到了菜单或工具栏中,则这些操作出现的顺序将与 plugin.xml 文件中列示它们的顺序相反。此行为很明显是不直观的。但是,这是在冻结“Eclipse 平台 API”之后才发现的。现在更改该行为将破坏依赖于现有行为的每个插件。

selectionenablement 元素是互斥的。enablement 元素可以使用子元素 objectClassobjectState 替换 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>

插件可使用此扩展点来添加新的顶级菜单。插件还可定义允许其它插件将其操作添加到组中的命名组。

顶级菜单是通过使用 path 属性的下列值来创建的:

省略 path 属性将会导致将新菜单添加到 additions 菜单栏组中。

工作台窗口中的缺省组是在 IWorkbenchActionConstants 接口中定义的。这些常量可在用于动态添加的代码中使用。还可将这些值复制到 XML 文件中以与现有的工作台菜单和工具栏进行细粒度的集成。

工作台窗口中的各种菜单和工具栏项是依据算法定义的。在这些情况下,必须使用独立的机制来扩展窗口。例如,添加新的工作台视图将导致新的菜单项出现在“透视图”菜单中。还会自动将“导入”、“导出”和“新建向导”扩展添加到窗口中。