弹出菜单

标识:org.eclipse.ui.popupMenus

描述:此扩展点用来将新操作添加至其它插件拥有的上下文菜单。可针对特定对象类型进行操作添加(objectContribution)或针对视图或编辑器部件的特定上下文菜单进行操作添加(viewerContribution)。当使用 objectContribution 时,添加项将出现在选择了指定类型的对象的所有视图或编辑器部件上下文菜单中。相反,若使用 viewerContribution,则添加项将仅出现在指定的视图或编辑器部件上下文菜单中,而与选择无关。

当选择是多机种选择时,若有可能,将应用添加项(如果是针对公共选择类型注册的话)。如果不可能直接进行匹配,则会尝试针对超类和超接口进行匹配。

可通过使用名称过滤器进一步限制选择。如果使用了名称过滤器,则选择中的所有对象必须与过滤器匹配才可以应用添加项。

对象添加项中的个别的操作可使用属性 enablesFor 来指定它是应仅应用于单个选择类型、多个选择类型还是应该应用于任何其它选择类型。

如果这些过滤机制不足够,则操作添加项可使用 filter 机制。在这种情况下,将在一系列名称值对中描述目标对象的属性。适用于选择的属性是特定于类型的,且超出了工作台本身的域,因此工作台将代理在此级别上过滤为实际选择的操作。

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

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

配置标记:

   <!ELEMENT extension (objectContribution , viewerContribution)>

   <!ATTLIST extension
     point CDATA #REQUIRED
     id    CDATA #IMPLIED
     name  CDATA #IMPLIED
   >

   <!ELEMENT objectContribution (filter* , visibility? , 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
     menubarPath      CDATA #IMPLIED
     icon             CDATA #IMPLIED
     helpContextId    CDATA #IMPLIED
     style            (push|radio|toggle)
     state            (true | false)
      class            CDATA #REQUIRED
     enablesFor       CDATA #IMPLIED
     overrideActionId CDATA #IMPLIED
     tooltip          CDATA #IMPLIED
   >

   <!ELEMENT filter EMPTY>

此元素用来对当前选择中的每个对象的属性状态求值。仅当选择中的每个对象都具有指定的属性状态时才匹配。选择中的每个对象都必须实现或适用于 org.eclipse.ui.IActionFilter

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

   <!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.popupMenus">
      <objectContribution
         id="com.xyz.C1"
            objectClass="org.eclipse.core.resources.IFile" 
         nameFilter="*.java">
         <menu
            id="com.xyz.xyzMenu" 
            path="additions"
            label="&amp;XYZ Java Tools">
            <separator name="group1"/>
         </menu>
         <action
            id="com.xyz.runXYZ" 
            label="&amp;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="&amp;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> 

在上面的示例中,指定的对象添加操作将仅支持单个选择(enablesFor 属性)。另外,选择中的每个对象还必须实现指定的接口(IFile)且必须是 Java 文件。将把此操作添加到先前创建的子菜单中。此添加项将在具有所需选择的任何视图中生效。

相反,上述查看器添加项将仅出现在“任务”视图上下文菜单中,且不会受视图中的选择影响。

以下是过滤器机制的一个示例。在这种情况下,操作将仅对已完成且具有高优先级的 IMarkers 出现。

   <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="&amp;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 时才出现。

API 信息:操作属性 class 的值必须是实现 org.eclipse.ui.IObjectActionDelegate(适用于操作添加项的情况)、org.eclipse.ui.IViewActionDelegate(适用于属于视图的上下文菜单的添加项的情况)或 org.eclipse.ui.IEditorActionDelegate(适用于属于编辑器的上下文菜单的添加项)的 Java 类的全限定类名。在所有情况下,尽可能迟地装入实现的类以避免在真正需要整个插件之前就装入该插件。

注意:对于向下兼容,可为对象添加项实现 org.eclipse.ui.IActionDelegate

仅当目标部件发布供扩展的菜单时,部件内的上下文菜单扩展才有可能进行。我们极力鼓励这样做,原因是这样会提高产品的可扩展性。要完成此任务,每个部件都应该发布通过调用 IWorkbenchPartSite.registerContextMenu 来定义的任何上下文菜单。一旦完成此任务,则工作台将自动插入存在的任何操作扩展。

必须为每个已注册的菜单提供菜单标识。为获得各部件的一致性,所有部件实现器都应采用下列策略。

向工作台注册的任何上下文菜单还应该包含具有标识 IWorkbenchActionConstants.MB_ADDITIONS 的标准插入点。其它插件将把此值用作插入的引用点。可通过将 GroupMarker 添加至菜单的适当插入位置来定义插入点。

在上下文菜单中选择的工作台中的对象可定义 org.eclipse.ui.IActionFilter。这是可以执行特定于类型的过滤的过滤策略。工作台将通过测试以了解过滤器是否实现 IActionFilter 来检索供选择的过滤器。如果失败,则工作台将通过 IAdaptable 机制来请求过滤器。

在翻译文本中,操作和菜单标号可包含特殊字符,这些特殊字符对助记符进行编码,这些助记符是在所选字符前用和号(“&”)字符指定的。由于 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>

所提供的实现:工作台视图具有内置上下文菜单,这些上下文菜单是使用若干操作装入的。插件可向这些菜单进行添加。如果查看器为这些添加项保留了槽且它们是公共的,则槽名可用作路径。否则,会将操作和子菜单添加到弹出菜单的末尾。

Copyright (c) 2000, 2003 IBM Corporation and others.