备忘单

备忘单是一些特殊视图,这些视图可用来指导用户完成一系列复杂的任务以实现整体目标。例如,可以使用备忘单来指导用户完成创建、编译和运行简单 Java 程序所需的所有步骤。备忘单是从帮助 > 备忘单... 菜单项启动的。还可以从简介页面启动备忘单。

备忘单是使用 org.eclipse.ui.cheatsheets.cheatSheetContent 扩展点来定义的。备忘单内容本身是在一个单独的文件中定义的,以便可以更容易地将它翻译成其它语言。

添加备忘单

添加备忘单非常简单。让我们看一下 JDT 为了构建简单的 Java 应用程序而添加的备忘单。

<extension point="org.eclipse.ui.cheatsheets.cheatSheetContent">
	<cheatsheet
		name="%cheatsheet.helloworld.name"
		contentFile="$nl$/cheatsheets/HelloWorld.xml"
		id="org.eclipse.jdt.helloworld">
		<description>%cheatsheet.helloworld.desc</description>
	</cheatsheet>
	...
与其它工作台添加项很相似,可以为备忘单指定名称、描述和标识。当用户访问帮助 > 备忘单... 列表时就会显示名称和描述。如果想要将几个备忘单放入一个逻辑分组中,则还可以定义备忘单的类别。如果未指定类别,则备忘单将出现在其它类别中。

备忘单对话框

备忘单项

备忘单的实际工作是在内容文件中完成的。内容文件是一个 XML 文件,其名称和位置是在 contentFile 属性中指定的。该文件的路径相对于插件的目录。(注意目录名中 $nl$ 变量的使用,该变量表示该文件将位于特定于目标环境的本地语言的目录中。)

文件格式本身包括有关备忘单的概述信息,接着是对用户将执行的每个步骤(称为)的描述。在最简单的情况下,项只是对用户应该执行的步骤的详细描述。但是,一个项还可以指定一种操作,可以运行该操作来代表用户执行步骤。让我们看一下 Java 备忘单的内容文件(HelloWorld.xml)的第一部分。

<?xml version="1.0" encoding="UTF-8" ?>
<cheatsheet title="Simple Java Application">
	<intro
		href="/org.eclipse.ui.cheatsheets.doc/tasks/tcheatst.htm">
		<description>
Welcome to the Hello, World Java tutorial.
It will help you build the famous "hello world" application and try it out. You will create a java project, and a java class that will print "hello world" in the console when run.
Let's get started!
		</description>
</intro>
	<item
		href="/org.eclipse.platform.doc.user/concepts/concepts-4.htm"
		title="Open the Java Perspective">
		<action
			pluginId="org.eclipse.ui.cheatsheets"
			class="org.eclipse.ui.internal.cheatsheets.actions.OpenPerspective"
			param1="org.eclipse.jdt.ui.JavaPerspective"/>
		<description>
Select Window->Open Perspective->Java in the menu bar at the top of the workbench.
This step changes the perspective to set up the Eclipse workbench for Java development.
You can click the "Click to Perform" button to have the "Java" perspective opened automatically.
		</description>
</item>
...

简单 java 备忘单

标题和简介信息显示在备忘单的顶部。然后,描述了各个项。此备忘单的第一个项描述如何打开 Java 透视图。而且,action 属性指定了一个类,可以使用该类来代表用户运行操作。该类必须实现 IAction。这是相当方便的,因为它允许您重用为菜单或工具栏添加项编写的操作类。

如果操作使用参数或者需要了解备忘单及其状态,则该操作的类可以选择实现 ICheatSheetAction。在本例中,将向操作传递参数的数组以及对 ICheatSheetManager 的引用,以便它可以请求有关备忘单的更多信息。可以使用 paramN 属性将任何必需的参数传递给操作的 run 方法。

如果运行操作可能失败,强烈建议从备忘单中调用的操作能够报告一个成功/失败的结果。(例如,用户可能从其对话框中取消操作)。有关更多详细信息,请参阅 IAction.notifyResult(boolean)

项不一定要定义操作。如果用户必须手工执行该项,您就根本不需要指定操作。以下是 Java 备忘单的第三个步骤,它只不过是告诉用户如何编写简单的应用程序。当未指定操作时,项描述必须指示用户在完成任务之后按适当的按钮。

<item
	href="/org.eclipse.jdt.doc.user/tasks/tasks-54.htm"
	title="Add a System.out.println line in your main method">
	<description>
Now that you have your HelloWorld class,
In the "public static void main" method, add the following statement:  System.out.println("Hello world!"); and save your changes.  Press the "click when done" button below when finished.
	</description>
</item>
附加属性控制是否可以彻底跳过该项以及如果用户在执行步骤期间请求帮助,则应该启动哪个文档。有关可以在备忘单中定义的所有属性的描述,请参阅 org.eclipse.ui.cheatsheets.cheatSheetContent 扩展点文档。
子项

可以定义子项来进一步组织项的表示。与项不同的是,不必按任何特定顺序来访问子项。子项还可以定义一些操作来自动执行用户的子任务。描述子项操作的方式与描述项操作的方式相同。

条件表达式和备忘单变量

可以使用条件表达式来定义其内容或行为取决于特定条件是否成立的备忘单元素。条件是在子项的 condition 元素中使用与每个选项的 when 属性相匹配的任意字符串值来描述的。条件通常使用 ${var} 格式来引用备忘单变量,其中 var 表示备忘单变量的名称。几个简单的示例将帮助演示条件表达式是如何工作的。

条件子项可以用来从可能的子项列表中选择一个子项。只有其 when 属性与 condition 属性相匹配的第一个子项才会被包括在备忘单中。例如:

<item ...>
	<conditional-subitem condition="${v1}">
		<subitem when="a" label="Step for A." />
		<subitem when="b" label="Step for B." />
	</conditional-subitem>
</item>
此项指定依赖于 v1 变量值的两个可能的子项。如果变量值为 a,则将包括第一个子项。如果变量值为 b,则将包括第二个子项。如果变量值不是上述两个值,则认为发生了错误。

条件操作与条件子项类似。perform-when 元素指定执行可能的操作列表中的一项操作的条件。条件是按相同的方式描述的,即,使用通常会引用变量的任意字符串来描述。其 when 属性与该条件相匹配的操作就是将被执行的操作。例如:

<item ...>
	<perform-when condition="${v1}">
		<action when="a" class="com.example.actionA" pluginId-"com.example" />
		<action when="b" class="com.example.actionB" pluginId-"com.example" />
	</perform-when>
</item>
根据 v1 变量的值来选择要执行的操作。如果变量值既不是 a 也不是 b,则认为它发生了错误。
重复的子项

重复的子项描述可以扩展到 0、1 或更多相似子步骤中的子项。各个子步骤是使用特殊变量 ${this} 来实现个性化的。此变量将被替换为 values 属性中指定的值。values 属性是用逗号隔开的一串值。可以在 values 属性中使用扩展到值列表中的变量。例如:

<item ...>
	<repeated-subitem values="${v1}">
		<subitem label="Step ${this}" />
	</repeated-subitem>
</item>
如果变量的值为 1,b,three,则三个子项将出现在备忘单中,每个子项都具有唯一的标签(“Step 1”、“Step b”和“Step three”)。可以在标签或操作参数值中使用该变量。执行操作时,还可以从 ICheatSheetManager 中访问该变量。

备忘单侦听器

在某些情况下,如果备忘单是活动的,您可能要更改用户界面的其它部件。例如,如果备忘单正在指导用户完成编辑任务,则您可能具有显示特殊注释的编辑器。在这种情况下,可以将 listener 指定为备忘单的一种属性。listener 属性必须是做为 CheatSheetListener 的子类的 Java 类的标准名称。当备忘单的生命周期中发生更改时(例如,当它打开、关闭或完成时),侦听器将接收到通知以及 ICheatSheetEvent

将属性添加至现有备忘单

可以使用 org.eclipse.ui.cheatsheets.cheatSheetItemExtension 扩展来将任意属性添加至预先存在的备忘单。此扩展点的用途是允许插件添加附加按钮,这些按钮将帮助用户完成给定步骤。这些附加按钮将显示在帮助图标的旁边。

要使用此机制,可以在备忘单 XML 文件的项定义中定义任何属性。属性名将与 org.eclipse.ui.cheatsheets.cheatSheetItemExtension 的扩展中添加的任何属性相匹配。有关更多详细信息,请参阅扩展点文档。