V3.2
本文档通过一系列 DTD 片段(机器可读 XML 模式)来描述备忘单内容文件的结构。
cheatsheet
<!ELEMENT cheatsheet (intro, item+)> <!ATTLIST cheatsheet title CDATA #REQUIRED >
<cheatsheet> 元素定义备忘单内容文件的主体。<cheatsheet> 的属性如下所示:
intro
<!ELEMENT intro (description)> <!ATTLIST intro contextId CDATA #IMPLIED href CDATA #IMPLIED >
<intro> 元素用来描述所要显示的备忘单简介。<description> 子元素包含简介的主体。<intro> 的属性如下所示:
description
<!ELEMENT description EMPTY> <!ATTLIST description >
<description> 元素包含备忘单或备忘单项的描述。此描述由插入了简单格式化标记的文本组成。备忘单将自动格式化文本并对其进行布局,以使其在 UI 中以合理的方式显示。在文本中,成对的 <b>...</b> 标记导致其中的文本显示成粗体。可以使用 <br/> 元素来强制换行。目前,只支持这些格式化标记(但是,将来可能会添加其他格式化标记)。文本中的某些字符对于 XML 解析器来说具有特殊意义;尤其是,“<”、“>”、“&”、“'”和“'”(引号)应该分别写成 “<”、“>”、“&”、“'”和“"”。将把空格(空格和换行符)视为单词分隔符;并且将把相邻的空格和换行符视为单个单元并显示为单个空格或换行符。将忽略紧跟在 <description> 和 <br/> 标记后面的空格,并且将忽略 </description> 标记前面的空格。
item
<!ELEMENT item (description ([action|command|perform-when] | (subitem|repeated-subitem|conditional-subitem)*) [onCompletion])> <!ATTLIST item title CDATA #REQUIRED dialog ("true" | "false") "false" skip ("true" | "false") "false" contextId CDATA #IMPLIED href CDATA #IMPLIED >
每个 <item> 元素描述备忘单中的一个顶级步骤。<item> 可以包含 <subitem> 元素。<item> 的属性如下所示:
org.eclipse.ui.cheatsheets.cheatSheetItemExtension 允许对 UI 中要显示的项进行其他定制控制。此扩展点的添加项声明了附加的字符串值属性的名称,<item> 元素可以包含这些属性。
简单项具有描述以及可选的操作或命令。在典型的展示中,大部分时间会向用户显示备忘单项的标题。仅当步骤处于执行状态时,才会显示项的描述。所指定的 <action>、<command> 或 <perform-when> 元素与某个按钮相关联,用户可通过按下该按钮来执行该步骤的操作或命令。如果不存在任何操作或命令,则用户必须手工执行该步骤并明确指示他们已成功地完成该步骤。
可以将步骤分为多个由 <subitem> 子元素指定的子步骤。与要求用户严格遵循顺序的项不同,给定项的子项可以按任意顺序执行。在转到下一个项之前,必须先尝试(或跳过)当前项的所有子项。(这表示无法将必须按固定顺序执行的操作表示为子项)。
<conditional-subitem> 子元素允许步骤根据在先前步骤中获取了值的备忘单变量来定制子步骤的表示。<repeated-subitem> 子元素允许步骤包括一组类似的子步骤。同样,子步骤的确切集合可能基于在先前步骤中获取了值的备忘单变量。
subitem
<!ELEMENT subitem ( [action|command|perform-when] )> <!ATTLIST subitem label CDATA #REQUIRED skip ("true" | "false") "false" when CDATA #IMPLIED >
每个 <subitem> 元素描述备忘单中的一个子步骤。<subitem> 具有简单的文本标签,但没有详细的描述和进一步的子项。<subitem> 的属性如下所示:
子项可以具有可选的操作或命令。所指定的 <action>、<command> 或 <perform-when> 元素通常与某个按钮相关联,用户可通过按下该按钮来执行该子步骤的操作或命令。如果不存在任何操作或命令,则用户必须手工执行该子步骤并明确指示他们已成功地完成该步骤。
与要求严格遵循顺序的项不同,给定项的子项可以按任意顺序执行。在转到下一个项之前,必须先完成或跳过当前项的所有子项。(这表示不应该将必须按固定顺序执行的操作表示为子项)。
conditional-subitem
<!ELEMENT conditional-subitem (subitem+)> <!ATTLIST conditional-subitem condition CDATA #REQUIRED >
每个 <conditional-subitem> 元素描述单个子步骤。根据展开该项时已知条件的不同,此元素的格式也会有所变化。<conditional-subitem> 的属性如下所示:
<conditional-subitem> 元素的 condition 属性提供了一个字符串值(此值总是来自备忘单变量)。每个 <subitem> 子代的 when 属性必须是不同的字符串值。展开该项时,<conditional-subitem> 元素将被具有匹配值的 <subitem> 元素替换。如果没有具有匹配值的 <subitem> 元素,就会认为有错误。
例如,展开以下项时,如果名为“v1”的备忘单变量的值为“b”:
<item ...> <conditional-subitem condition="${v1}"> <subitem when="a" label="Step for A." /> <subitem when="b" label="Step for B." /> </conditional-subitem> </item>于是,将选择第二个子项。因此,该项将展开成等同于以下的内容:
<item ...> <subitem label="Step for B."/> </item>
repeated-subitem
<!ELEMENT repeated-subitem (subitem)> <!ATTLIST repeated-subitem values CDATA #REQUIRED >
每个 <repeated-subitem> 元素都描述一个子项,该子项将展开为 0 个、1 个或更多个类似的子步骤。<repeated-subitem> 的属性如下所示:
values 属性提供用逗号分隔的字符串列表;<subitem> 子代提供模板。展开该项时,<repeated-subitem> 元素将被 <subitem> 元素的副本替换,在该副本中,变量 "this" 已被替换为相应的字符串值。
例如,展开以下项时,如果名为“v1”的备忘单变量的值为“1,b,three”:
<item ...> <repeated-subitem values="${v1}"> <subitem label="Step ${this}."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/> </subitem> </repeated-subitem> </item>于是,该项将展开为与以下等同的内容:
<item ...> <subitem label="Step 1."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="1"/> </subitem> <subitem label="Step b."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="b"/> </subitem> <subitem label="Step three."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="three"/> </subitem> </item>
action
<!ELEMENT action EMPTY> <!ATTLIST action class CDATA #REQUIRED pluginId CDATA #REQUIRED param1 CDATA #IMPLIED ... param9 CDATA #IMPLIED confirm ("true" | "false") "false" when CDATA #IMPLIED >
每个 <action> 元素描述备忘单中的一个操作。<action> 的属性如下所示:
org.eclipse.jface.action.IAction
的
Java 类的标准名称。如果此操作还实现了
org.eclipse.ui.cheatsheets.ICheatSheetAction
,就会通过它的
run(String[],ICheatSheetManager) 方法来调用它,而且将传递备忘单管理器和操作参数。每当指定了此属性时,还必须指定
pluginId 属性。如果运行从备忘单调用的操作时可能会失败(这可能是因为用户从对话框中取消了该操作),则强烈建议该操作报告成功/失败结果。(请参阅 org.eclipse.jface.action.Action.notifyResult(boolean) 以了解详细信息。)org.eclipse.ui.cheatsheets.ICheatSheetAction
的操作类来说,将在调用该操作时把这些属性的字符串值传递给该操作。可以向备忘单操作传递多达
9 个参数(param1 和 param2 等等)。提供的参数必须从参数 1 开始并且连续;即,在未指定
param1 的情况下指定 param2 是不合法的。如果属性字符串的格式为“${var}”,就会将其视为对备忘单变量 var 的引用。此条件的值将是该备忘单变量在外层 <item> 元素开始执行时具有的值(或者,如果在当时未绑定此变量,则此条件的值将空字符串)。command
<!ELEMENT command EMPTY> <!ATTLIST command serialization CDATA #REQUIRED returns CDATA #IMPLIED confirm ("true" | "false") "false" when CDATA #IMPLIED >
每个 <command> 元素都描述备忘单中的一个命令。<command> 的属性如下所示:
在以下示例中,项带有一个命令,该命令打开一个对话框并将结果存储在备忘单变量“result”中。
<item title="View Selection"> <description>Select a view which will be opened in the next step.</description> <command returns = "result" serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Select View,buttonLabel0=Package Explorer,message=Select a view ,buttonLabel1=Search View)"/> <onCompletion> Selected the ${result}. </onCompletion> </item>
onCompletion
<!ELEMENT onCompletion EMPTY> <!ATTLIST onCompletion >
<onCompletion> 元素包含某个项完成时将要显示的文本。在备忘单的最终步骤中,可使用此元素来确认整个任务已完成,因此它特别有用。此描述由插入了简单格式化标记的文本组成,这些标记遵循的规则与 <description> 元素相同。<onCompletion> 元素还可以包含对备忘单变量的引用(格式为“"${var}”)。当此步骤完成时,将使用备忘单变量 var 的实际值来展开此格式。
perform-when
<!ELEMENT perform-when ((action|command)+)> <!ATTLIST perform-when condition CDATA #REQUIRED >
每个 <perform-when> 元素描述备忘单中的一个操作。<perform-when> 的属性如下所示:
<conditional-subitem> 元素的 condition 属性提供了一个字符串值(此值总是来自备忘单变量)。每个 <subitem> 子代的 when 属性必须是不同的字符串值。展开该项时,<conditional-subitem> 元素将被具有匹配值的 <subitem> 元素替换。如果没有具有匹配值的 <subitem> 元素,就会认为有错误。
例如,展开以下项时,如果名为“v1”的备忘单变量的值为“b”:
<item ...> <subitem label="Main step"> <perform-when condition="${v1}"> <action when="a" class="com.xyz.action1" pluginId="com.xyz" /> <action when="b" class="com.xyz.action2" pluginId="com.xyz" /> <command when="c" serialization="org.eclipse.search.ui.views.SearchView"/> </conditional-subitem> </subitem> </item>于是,将选择第二个操作。因此,该项将展开成等同于以下的内容:
<item ...> <subitem label="Main step"> <action class="com.xyz.action2" pluginId="com.xyz" /> </subitem> </item>
以下是一个简单备忘单内容文件的示例,它演示了如何使用 commands、perform-when 和 conditional 子项。
<?xml version="1.0" encoding="UTF-8"?> <cheatsheet title="Sample Cheat Sheet"> <intro> <description>A cheat sheet which demonstrates the use of perform-when and conditional subitems</description> </intro> <item title="View Selection"> <description>Select a view which will be opened in the following steps.</description> <command returns = "result" serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Select View,buttonLabel0=Package Explorer,message=Select a view ,buttonLabel1=Search View)"/> <onCompletion> Selected the ${result}. </onCompletion> </item> <item title="Close Views"> <description>Close the search view and package explorer if open</description> </item> <item title="Open the view from a perform when item" skip = "true"> <description>Uses perform when to open the view seleted previously.</description> <perform-when condition = "${result}"> <command when = "Package Explorer" serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.jdt.ui.PackageExplorer)"/> <command when = "Search View" serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.search.ui.views.SearchView)"/> </perform-when> </item> <item title="Close Views"> <description>Close the search view and package explorer if open</description> </item> <item title="Open the view from a perform when subitem"> <description>Uses perform when to open the view seleted previously.</description> <subitem label="Perform when subitem" skip = "true"> <perform-when condition = "${result}"> <command when = "Package Explorer" serialization="org.eclipse.jdt.ui.PackageExplorer"/> <command when = "Search View" serialization="org.eclipse.search.ui.views.SearchView"/> </perform-when> </subitem> </item> <item title="Close Views"> <description>Close the search view and package explorer if open</description> </item> <item title="Open the view from a conditional subitem"> <description>Uses perform when to open the view seleted previously.</description> <conditional-subitem condition="${result}"> <subitem when="Package Explorer" label="Open package explorer."> <command serialization = "org.eclipse.jdt.ui.PackageExplorer"/> </subitem> <subitem when="Search View" label="Open Search View"> <command serialization = "org.eclipse.search.ui.views.SearchView"/> </subitem> </conditional-subitem> </item> </cheatsheet>
Copyright (c) 2004, 2006 IBM Corporation and others.
All rights reserved. This program and the accompanying materials are made
available under the terms of the Eclipse Public License v1.0 which accompanies
this distribution, and is available at
http://www.eclipse.org/legal/epl-v10.html