操作集

标识: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>

此元素用来在新菜单中创建已命名组。它在新菜单中没有可视表示,这与 separator 元素不同。

   <!ATTLIST groupMarker
     name CDATA #REQUIRED
   >

   <!ELEMENT selection EMPTY>

此元素用来帮助确定基于当前选择是否启用操作。如果指定了 enablement 元素,则忽略它。

   <!ATTLIST selection
     class CDATA #REQUIRED
     name  CDATA #IMPLIED
   >

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

此元素用来对当前选择中的每个对象的类或接口进行求值。如果选择中的每个对象都实现指定的类或接口,则表达式求值为 true。

   <!ATTLIST objectClass
     name CDATA #REQUIRED
   >

   <!ELEMENT objectState EMPTY>

此元素用来对当前选择中的每个对象的属性状态求值。如果选择中的每个对象都具有指定的属性状态,则表达式求值为 true。要对此类型的表达式进行求值,选择中的每个对象都必须实现或采用 org.eclipse.ui.IActionFilter 接口。

   <!ATTLIST objectState
     name  CDATA #REQUIRED
     value CDATA #REQUIRED
   >

   <!ELEMENT pluginState EMPTY>

此元素用来对插件的状态进行求值。插件的状态可以是下列项之一:installedactivated

   <!ATTLIST pluginState
     id    CDATA #REQUIRED
     value (installed|activated) "installed"
   >

   <!ELEMENT systemProperty EMPTY>

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

   <!ATTLIST systemProperty
     name  CDATA #REQUIRED
     value CDATA #REQUIRED
   >
示例:以下是操作集的示例(注意子元素和使用属性的方法):

    <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 作为单选按钮菜单项出现。不管当前选择状态是什么,它们都一直启用。

API 信息: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 文件中以与现有的工作台菜单和工具栏进行精细的集成。

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

Copyright (c) 2000, 2003 IBM Corporation and others. All rights reserved. 该程序及附带提供的资料是基于“一般公共许可证”(Common Public License) v1.0 的条款提供的,本发行版中提供了该许可证条款,并且也可 在以下位置处找到该条款:http://www.eclipse.org/legal/cpl-v10.htm