版本 3.0
本文档将备忘单内容文件结构描述为一系列 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> 元素容纳备忘单或备忘单项的描述。该描述由插入了简单格式化标记的文本组成。备忘单自动格式化文本并对其进行布局以使其在用户界面中显示时更为合理。在文本中,平衡的 <b>...</b> 标记导致封闭的文本以粗体字体呈现,而 <br/> 元素可用来强制换行。这些是此时支持的唯一格式化标记(但是,未来可能会添加其它格式化标记)。文本中的某些字符对 XML 解析器具有特殊意义;特别是要分别写为“<”、“>”、“&”和“'”(引号)而不是写为 “<”、“>”、“&”、“'”和“"”。空格(空格和换行符)被视作字分隔符;相邻空格和换行符被视作单个单元且呈现为单个空格或换行符。紧跟在 <description> 和 <br/> 标记之后的空格会被忽略,紧跟在 </description> 标记之前的空格也一样。
item
<!ELEMENT item (description ([action|perform-when] | (subitem|repeated-subitem|conditional-subitem)*))> <!ATTLIST item title CDATA #REQUIRED skip ("true" | "false") "false" contextId CDATA #IMPLIED href CDATA #IMPLIED >
每个 <item> 元素描述备忘单中的一个顶级步骤。<item> 为单一或组合体。<item> 属性如下所示:
org.eclipse.ui.cheatsheets.cheatSheetItemExtension 允许对要显示在用户界面中的项进行附加定制控制。此扩展点的添加项声明附加字符串值的属性的名称,这些属性可能会出现在 <item> 元素上。
简单项具有描述和可选操作。在典型表示中,大部分时间会对用户显示备忘单项的标题。仅当步骤正在执行时,才会显示项的描述。<action>(或 <perform-when>)元素的存在通常与某个按钮相关联,用户可按下该按钮来执行该步骤的操作。如果不存在任何操作,用户必须手工执行该步骤并公共指示他们已经成功完成该步骤。
组合步骤被分为若干子步骤,就象 <subitem> 子元素指定的那样。与项不同,用户必须严格遵循项的顺序,而给定项的子项可以任意顺序执行。在进至下一项之前,必须先尝试(或跳过)该项的所有子项。(这表示必须按必需顺序执行的操作不能被表示为子项)。
<conditional-subitem> 子元素允许步骤根据从之前步骤中获取值的备忘单变量定制子步骤的表示。<repeated-subitem> 子元素允许步骤包括一组类似子步骤。而且,子步骤的确切集合可能基于从之前步骤获取值的备忘单变量。
subitem
<!ELEMENT subitem ( [action|perform-when] )> <!ATTLIST subitem label CDATA #REQUIRED skip ("true" | "false") "false" when CDATA #IMPLIED >
每个 <subitem> 元素描述备忘单中的一个子步骤。<subitem> 具有简单文本标签,不过没有长度描述和进一步的子项。<subitem> 属性如下所示:
子项具有可选操作。<action>(或 <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> 元素会替换为带有被对应字符串值的变量 "this" 的 <subitem> 元素。
例如,如果名为“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>
元素的执行开始时备忘单的变量的值(或者为空字符串,如果该变量在当时未被绑定)。perform-when
<!ELEMENT perform-when (action+)> <!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" /> </conditional-subitem> </subitem> </item>于是第二个操作被选中而该项展开为与以下等效的内容:
<item ...> <subitem label="Main step"> <action class="com.xyz.action2" pluginId="com.xyz" /> </subitem> </item>
以下是非常简单的备忘单内容文件的示例:
<?xml version="1.0" encoding="UTF-8" ?> <cheatsheet title="Example"> <intro> <description>Example cheat sheet with two steps.</description> </intro> <item title="Step 1"> <description>This is a step with an action.</description> <action class="com.xyz.myaction" pluginId="com.xyz"/> </item> <item title="Step 2"> <description>This is a fully manual step.</description> </item> </cheatsheet>
Copyright (c) 2004, 2005 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