操作集
标识符:org.eclipse.ui.actionSets
描述:此扩展点用来将菜单、菜单项和工具栏按钮添加到工作台窗口中的公共区域。将这些添加项统称为操作集并按用户首选项依次出现在工作台窗口中。
配置标记:
<!ELEMENT actionSet (menu)* (action)* (description?)>
<!ATTLIST actionSet
id CDATA
#REQUIRED
label CDATA #REQUIRED
visible (true
| false) #IMPLIED
>
<!ELEMENT description (#PCDATA)>
-
id — 将用来标识此操作集的唯一名称。
-
label — 将在工作台窗口菜单中用来表示此操作集的可转换名称。
-
visible — 指示操作集最初在所有透视图中是否应为可视的可选属性。仅当用户打开未定制的新透视图时才将会使用此选项。用户可从“定制透视图对话框”中覆盖此选项。
-
description — 其主体应包含提供操作集简短描述的文本的可选子元素。
<!ELEMENT menu (separator)+ (groupMarker)*>
<!ATTLIST menu
id
CDATA #REQUIRED
label
CDATA #REQUIRED
path
CDATA #IMPLIED
>
-
id — 可用来引用此菜单的唯一标识符。
-
label — 新菜单的文本标号。标号应包括助记符信息。
-
path — 从菜单栏的根目录开始的菜单位置。如果省略了它,则会将菜单添加到菜单栏上“窗口”菜单前面。路径中的每个标记(最后一个标记除外)必须表示工作台中的现有菜单,最后一个标记则应表示路径中最后一个菜单中的命名组。
<!ELEMENT separator EMPTY>
<!ATTLIST separator
name
CDATA #REQUIRED
>
name — 可在以后作为操作路径中的最后一个标记引用的分隔符的名称。因此,分隔符充当可将操作和子菜单添加到其中的命名组。
<!ELEMENT groupMarker EMPTY>
<!ATTLIST groupMarker
name
CDATA #REQUIRED
>
name — 以后在操作路径中可以作为最后一个标记来引用的组标记的名称。
<!ELEMENT action (selection)* (enablement)?>
<!ATTLIST action
id
NMTOKEN #REQUIRED
label
CDATA #REQUIRED
accelerator
CDATA #IMPLIED
definitionId
CDATA #IMPLIED
menubarPath
CDATA #IMPLIED
toolbarPath
CDATA #IMPLIED
icon
CDATA #IMPLIED
disabledIcon
CDATA #OPTIONAL
hoverIcon
CDATA #OPTIONAL
tooltip
CDATA #IMPLIED
helpContextId
CDATA #IMPLIED
state
(true | false) #IMPLIED
pulldown
(true | false) #IMPLIED
class
CDATA #OPTIONAL
retarget
(true | false) #OPTIONAL
allowLabelUpdate
(true | false) #OPTIONAL
enablesFor
CDATA #IMPLIED
>
-
id — 可用作此操作的引用的唯一标识符。
-
label — 以各种方式使用的可转换名称,取决于上下文。在菜单中,它用作菜单文本。在工具栏中,它用作按钮标号。标号可包含 JFace 编码的助记符和加速键信息(参见示例)。
-
accelerator — 一个用来指定操作的键代码的整数。这是根据零个或更多个 SWT 键修饰符掩码(例如 SWT.CTRL 或 SWT.ALT)和字符代码的一位宽度 OR 生成的整数。例如,对于 Ctrl+Z,使用 SWT.CTRL | 'Z' = (1<<18)|'Z' = 262234。
-
definitionId — 在操作定义中指定的标识。仅当操作集通过键绑定服务来指定加速键时才需要该标识。参见扩展点操作定义和加速键集
-
menubarPath — 用来指定菜单栏中操作位置的以斜杠(“/”)定界的路径。路径中的每个标记(最后一个标记除外)都必须表示层次结构中现有菜单的有效标识。最后一个标记表示要将操作添加到其中的命名分隔符组。如果省略了路径,则操作将不会出现在菜单栏中。
-
toolbarPath — 用来指定工具栏中操作位置的以斜杠(“/”)定界的路径。第一个标记表示工具栏标识(“常规”则表示是缺省工具栏),而第二个标记是工具栏内的命名组。如果工具栏内不存在该组,则将会创建它。如果省略了工具栏路径(toolbarPath),则操作将不会出现在工具栏中。
-
icon — 将用来可视地表示其上下文中操作的图标的相对路径。如果省略了它而操作应出现在工具栏中,则工作台将使用占位符图标。该路径是相对于进行添加的 plugin.xml 文件的位置的。图标将出现在工具栏中但是不会出现在菜单中。已启用的操作在菜单中将用 hoverIcon 表示。
-
disabledIcon — 当禁用操作时,将用于在操作的上下文中可视地表示操作的图标的相对路径。如果省略了它,则正常图标将变灰。该路径是相对于进行添加的 plugin.xml 文件的位置的。禁用的图标将出现在工具栏中,但是不会出现在菜单中。菜单中已禁用的操作的图标将由 OS 提供。
-
hoverIcon — 当鼠标位于操作上时,将用来在操作的上下文中可视地表示操作的图标的相对路径。如果省略了它,则将使用正常图标。该路径是相对于进行添加的 plugin.xml 文件的位置的。
-
tooltip — 工具提示文本的值(如果操作将出现在工具栏中的话)。否则忽略它。
-
helpContextId — 一个指示此操作的帮助上下文标识的唯一标识符。如果操作作为菜单项出现,则在突出显示该菜单项时按 F1 键将显示给定上下文标识的帮助。
-
state — 一个指示操作应为切换类型的可选属性。当将该项添加至菜单时,它会显示为复选框项。当将该项添加至工具栏时,它将变成切换按钮。如果定义了该项,则属性值将用作初始状态(true
或 false)。此属性与 pulldown 是互斥的。
-
pulldown — 指示操作具有附加下拉菜单的可选属性。如果操作出现在工具栏中且属性值为 true,则下拉菜单将出现在操作旁边。如果操作出现在菜单中,则将忽略此属性。此属性与 state 是互斥的。
-
class — 实现 org.eclipse.ui.IWorkbenchWindowActionDelegate
或 org.eclipse.ui.IWorkbenchWindowPulldownDelegate
的类的全限定名。后者应在 pulldown 为 true 的情况下实现。如果 retarget 属性为 true,则不应提供此属性。
-
retarget — 如果此属性为 true,则将创建 retarget(全局)操作。部件可通过使用一个标准机制为此全局操作提供一个处理程序,该机制用于使用此操作的标识在它们的站点上设置全局操作处理程序。如果此属性为 true,则不应提供类属性。
-
allowLabelUpdates — 仅当 retarget 为 true 时才适用。如果此属性为 true,则 retarget 操作将从它的处理程序中更新其标号和工具提示。
-
enablesFor — 一个指示选择计数的值,必须满足该值才能启用操作。如果指定了此属性且满足条件,则启用该操作。如果条件不满足,则禁用该操作。如果未指定任何属性,则为任何数目的所选项启用该操作。支持下列属性格式:
! — 选择了零项
? — 选择了零项或一项
+ — 选择了一项或多项
multiple, 2+ — 选择了两项或更多项
n — 选择了精确数目个项。例如:4。
* — 选择了任意数目个项
<!ELEMENT selection EMPTY>
<!ATTLIST selection
class
CDATA #REQUIRED
name
CDATA #IMPLIED
>
-
class — 所选择的每个对象必须子类化或实现其以启用操作的类或接口的全限定名。
-
name — 可选择应用于所选择对象的名称的通配符过滤器。如果指定了此过滤器而匹配失败,则将禁用该操作。
<!ELEMENT enablement (and | or | not | objectClass
| objectState | systemProperty | pluginState)*>
<!ATTLIST enablement EMPTY>
在 Eclipse 的版本 2.0 中,启用元素可用来定义操作的启用。有关使用启用元素的更多信息,参考 actionExpressions.html。
示例: 下面是操作集的一个示例(注意子元素以及使用属性的方式):
<extension point = "org.eclipse.ui.actionSets">
<actionSet id="com.xyz.actionSet"
label="My Actions"
visible="true">
<menu id="com.xyz.xyzMenu"
label="XYZ Menu"
path="additions">
<separator name="group1"/>
</menu>
<action id="com.xyz.runXYZ"
label="&Run XYZ Tool"
menubarPath="com.xyz.xyzMenu/group1"
toolbarPath="Normal/XYZ"
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="&Run ABC Tool"
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">
</action>
</actionSet>
</extension>
在上面的示例中,指定的操作(名为“My Actions”)在每一个透视图内最初是可视的。它将仅支持单个选择(enablesFor 属性)。另外,选择中的对象还必须实现指定的接口(IFile)且必须是
Java 文件。
API 实现:class 属性的值必须是实现
org.eclipse.ui.IWorkbenchWindowActionDelegate 或
org.eclipse.ui.IWorkbenchWindowPulldownDelegate 的类的全限定名。后者应在
pulldown 为 true 的情况下实现。尽可能迟地装入此类以避免在真正需要整个插件之前就装入该插件。
操作扩展的启用标准最初是由 enablesFor,selection 和启用定义的。然而,一旦将操作委托实例化,它就可以直接在它的 selectionChanged 方法中控制操作启用状态。
注意,工作台不会为插件生成菜单:菜单路径必须引用已经存在的菜单,了解这一点是很重要的。
操作和菜单标号可包含使用以下规则编码助记符和加速键的特殊字符:
-
在转换的文本中,是在所选字符前面加与号(“&”)字符来指定助记符的。由于
XML 字符串中不允许有与号,所以使用 & 字符实体。
-
可选加速键是在名称字符串末尾指定的,其方法是使用 @ 后跟一系列修饰符,最后跟一个加速键字符(例如:&Save@Ctrl+S)。可将“+”号用作定界符来将修饰符链接起来(如 @Ctrl+Shift+S)。
如果通过单个扩展将两个或多个操作添加到了菜单或工具栏中,则这些操作出现的次序将与
plugin.xml 文件中列示它们的次序相反。此行为很明显不是直观的。然而,在冻结“Eclipse 平台 API”之后可以发现它。现在更改该行为将破坏依赖于现有行为的每个插件。
提供的实现:插件可使用此扩展点来添加新的顶级菜单(例如:调试)。插件还可定义允许其它插件将其操作添加到组中的命名组。
顶级菜单是通过使用 path 属性的下列值来创建的:
-
additions — 表示“窗口”菜单左边的组。
省略 path 属性会导致将新菜单添加到 additions 菜单栏组中。工作台窗口中的缺省组是在 IWorkbenchActionConstants
接口中定义的。这些常量可在用于动态添加的代码中使用。还可将这些值复制到 XML
文件中以与现有的工作台菜单和工具栏进行精细的集成。
工作台窗口中的各种菜单和工具栏项是从算法上定义的。在这些情况下,必须使用独立的机制来扩展窗口。例如,添加新的工作台视图将导致新的菜单项出现在“窗口”菜单中。还会自动将“导入”、“导出”和“新向导”扩展添加到窗口中。