级别： 中级 Philipp Tiedt (philipp_tiedt@de.ibm.com), 软件工程师, IBM
2006 年 11 月 02 日 备忘单（Eclipse 用户的重要生产力工具）在 Eclipse V3.2 中变得更加完善。本文是 “在 Eclipse 中构建备忘单” 教程的后续部分，在本文中，IBM 的软件工程师 Philipp Tiedt 概述了备忘单的新特性，并通过示例展示了其使用方法。
备忘单使 Eclipse 用户能够从 Eclipse Workbench 中查看交互式教程，从而学习如何执行复杂的 Eclipse 任务。（参见 “在 Eclipse 中构建备忘单”，其中有如何创建备忘单的全面介绍。）备忘单引导用户完成使用软件时必须遵循的步骤，因而是一种指导用户使用 Eclipse 插件或基于 Eclipse 的产品的出色途径。Eclipse V3.2 加强了备忘单技术，使用户可以更请轻松地构建用途更为多样化的备忘单。
搜索备忘单内容
Eclipse Help 搜索引擎的功能得到了显著增强。改进之一是现在的备忘单都作了索引，所以用 Help 搜索的结果包含了匹配的备忘单内容。例如，如果您需要有关创建新插件的帮助，搜索词汇 “plug-in”，Help 搜索就会返回一系列同查询相匹配的内容——包括备忘单和其他的内容。在 Eclipse V3.2 的基本安装中，对“plug-in”的搜索返回了近 500 条有关的结果，如图 1 所示。
图 1. 搜索 “plug-in”
这么多的结果，要在其中找到跟插件相关的备忘单内容还是很困难的。但如果在查询中添加 “cheat sheet” 对结果加以过滤，会使结果的范围过于狭窄，丢掉某些有用的内容。幸运地是，如果使用图 2 中的分类按钮，按分类显示搜索结果，就能够很明白地显示包含备忘单的结果。
图 2. 对搜索结果进行分类
从内容文件中打开备忘单
直到现在，备忘单都是从欢迎页或是从 Cheat Sheet Selection 对话框中的列表打开。Cheat Sheet Selection 对话框被更新，使您能够直接从文件系统（参见图 3）打开一个内容文件。这对于您编写或回顾一个备忘单特别有帮助。您无需将其作为一个插件来部署，也不需要启动运行时工作台以查看工作结果。您只需要按原样打开它，提供内容文件在工作空间中的完整路径即可。
图 3. 从内容文件中打开备忘单
尽管这是一个查看您所开发内容结果的出色特性，但仍有一个限制是：您在这样一个内容文件中引用的所有命令和行为都必需装载到您从中打开内容的 Eclipse 实例中。也就是说，如果您在备忘单插件中开发您自己的备忘单行为和 Eclipse 命令，那么您就无法通过打开内容文件直接装载并使用它们。平台会显示出一个错误，提示您所引用的插件或类尚未装载，如图 4 所示。
图 4. 当您试图运行一个行为时的错误
在这种情况下，您需要回到原来的方式：部署您的插件或启动一个运行时工作台以装载代码。
在用户辅助内容中嵌入命令链接
用 Eclipse V3.2，您可以在备忘单中嵌入 Eclipse 命令。这为自动化您的教程添加了另一种可选方式。清单 1 展示了如何嵌入一条命令。
清单 1. 嵌入命令
<?xml version="1.0" encoding="UTF-8"?>
<cheatsheet title="Open Browser">
<intro>
<description>This cheat sheet helps you to launch a browser via an
embedded command.</description>
</intro>
<item title="Open Browser">
<description>Use the following embedded command to launch the Eclipse Web site
in a browser</description>
<command serialization=
"org.eclipse.ui.browser.openBrowser(url=http://www.eclipse.org)"/>
</item>
</cheatsheet>>
|
 |
参数化命令
参数化命令 是能够被序列化为 String 的 Eclipse 命令。序列化命令字符串包含了命令 ID 和可选参数值对。要了解更多的信息，请阅读 ParameterizedCommand 的 API 规范（参见 参考资料）。
|
|
command 元素是 item 元素的一个新的子元素。它使您能够使用 serialization 属性指定一个序列化命令。通常，这只是命令 ID 的 String 序列化。序列化所能有的附加参数取决于这个命令。command 元素能够指定 confirm 和 when 属性，这和在 action 元素中的处理方式相同。
通过将 URL 作为参数传递，清单 1 中的嵌入式命令轻易地启动了 Eclipse 浏览器并打开了 Eclipse.org 网站。有些命令可有返回值，您可以通过使用 returns 属性将这个值赋给备忘单变量。返回值随后被用作条件输入或呈现给用户。想了解更多有关 command 元素的知识，请参阅备忘单内容文件格式规范（参见 参考资料）。
添加完成消息
现在，备忘单支持项（item）和任务的完成消息。这特别有助于向用户显示一个复杂的程序已经完成。完成消息是一个简单的文本字符串，它能够包含格式标记，诸如 <b>/</b>。请参阅备忘单文件格式规范以了解更多信息（参见 参考资料）。
消息能够包含对备忘单变量的引用以便显示它们的内容。下列代码显示了一个简单的展示变量内容的完成消息。
<onCompletion>The content of the \
cheat sheet variable is ${variableName}.</onCompletion>
|
构建复合备忘单
Eclipse V3.2 的一个奇妙的新特性就是构建复合备忘单的能力，这使您能够以树的结构组织备忘单。复合备忘单由任务 组成，每一个任务代表一个备忘单。任务可以组成任务组。
注册复合备忘单
注册复合备忘单的扩展点同简单备忘单一样。然而，出现了一个新的 composite 属性，用以标记备忘单是简单备忘单还是复合备忘单。
清单 2. 注册复合备忘单
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.2"?>
<plugin>
<extension
point="org.eclipse.ui.cheatsheets.cheatSheetContent">
<cheatsheet>
composite="true"
contentFile="content/content.xml"
id="devworks.tutorial.cheatsheets.updated.composite"
name="Composite Cheat Sheet"/>
</extension>
</plugin>
|
同简单备忘单一样，复合备忘单拥有 ID、名称和内容文件。需要将 composite 属性设为 true。然而，复合备忘单的内容文件遵循了截然不同的 XML 模式规范。
复合性内容
清单 3 显示了如何在复合备忘单中使用任务和任务组，同时也解释了额外的属性和元素。
清单 3. 复合备忘单
<?xml version="1.0" encoding="UTF-8"?>
<compositeCheatsheet name="Work with the Eclipse Platform">
<taskGroup name="Work with the Eclipse Platform" kind="choice">
<intro>
This cheat sheet offers different groups of tasks. Choose
one or more groups and complete them.
</intro>
<onCompletion>
Great! You have completed one or more task groups.
</onCompletion>
<taskGroup name="Java Development Tools" kind="sequence">
<intro>
Creating a Java project and a SWT Application.
<br />
You need to first complete the Java project task before
you can start with the SWT Application.
</intro>
<onCompletion>
Congratulations you have built both Java applications.
</onCompletion>
<task kind="cheatsheet" name="A Java project"
id="createJavaProject">
...
</task>
<task kind="cheatsheet" name="A simple SWT application"
id="createSWTApplication">
...
</task>
</taskGroup>
<taskGroup name="Other tutorials" kind="set">
<intro>
This group contains several different tutorials. Just
complete them in any order.
</intro>
<onCompletion>
Great! You have completed all tutorials
</onCompletion>
<task kind="cheatsheet" name="Simple Plug-in tutorial"
skip="true">
...
</task>
<task kind="cheatsheet" name="An other tutorial">
...
</task>
</taskGroup>
</taskGroup>
</compositeCheatsheet>
|
清单 3 中的备忘单内容定义了包含两个子任务组的根任务组，每一个子任务组包含两个任务。您可以使用 taskgroup 元素定义任务组。任务组通常用于对一套相关联的备忘单进行分组。您可以使用 kind 属性将任务组设置为以下三种之一：
set —— 任务组中的备忘单可以用任何顺序完成。然而，必需完成全部的备忘单才能完成任务组。sequence —— 任务组中的备忘单必需全部以其所列的顺序来完成。choice —— 可以用任何顺序完成任何备忘单。
如果整个任务组能够被跳过，应将 skip 属性设为 true。name 属性指定了任务组的显示名称。额外的 intro 和 onCompletion 元素的用法和在简单备忘单项中一样，并会分别为每个任务组产生一个介绍消息及完成消息。
清单 3 合成的备忘单通过一些关于 Eclipse 平台不同领域的教程对用户进行了指导。一个主题是在第一个任务组中的 Java™ Development Tool，另一个主题是用户可能感兴趣的其他教程。（请注意，这只是一个样例，而并不是对 Eclipse 教程的完整概述。）
根任务组的种类属于 choice，这意味着用户能够选择任何子任务组并完成它。Java Development Tool 任务组被定义为 sequence，所以用户在创建一个简单 SWT 应用程序前必需首先完成 Java Project 教程。最后一个任务组被定义为 set，所以用户可以用任何顺序随意地完成子任务。图 5 显示了备忘单的树结构。
图 5. 复合备忘单的结构
在图 5 中，请注意不同的图标代表不同种类的任务组。而且，Java Development Tool 组的第二个任务是灰的，因为在第一个任务完成之前该任务不能开始。
任务
一个任务代表一个备忘单，并使用 task 元素实现。清单 4. 更具体解释了这一点。
清单 4. task 元素
<task kind="cheatsheet" name="A Java project"
id="createJavaProject">
<param name="id" value="org.eclipse.pde.helloworld" />
<param name="showIntro" value="false" />
<intro>
This tutorial guides you through the creation of a Java project.
</intro>
<onCompletion>
Finished creating a Java project.
</onCompletion>
</task>
|
给每个任务一个名称和一个 ID。名称在备忘单树中显示，如上图 5 中所显示。您使用 id 属性的值引用一个任务，例如，当声明任务或任务组间的依赖项时。如果用户可以跳过这个任务，您可以将 skip 选项设为 true。对于任务组来说，您可以使用 intro and onCompletion 元素为任务显示介绍消息和完成消息。parameter 元素被用于引用备忘单。备忘单通常通过其 ID 引用，如清单 4 所示。parameter 元素包含一个 name 属性和一个 value 属性。
表 1 显示了当前定义的参数。
表 1. 参数| 名称 | 值 |
|---|
id | 备忘单中应于任务关联的 ID（如 org.eclipse.ui.cheatsheets.cheatSheetContent 扩展中的定义） | path | 这可以是一个绝对 URL，指向另一个备忘单内容文件，或是与复合内容文件的内容文件相对的内容文件的URL。请注意 id 和 path 参数中，只应该指定一个，而不是两个 | showIntro | 如果该参数被设为 false，备忘单的介绍不会显示出来 |
依赖
如果一个任务或任务组依赖于另一个任务或任务组的完成，您可以使用 dependency 元素达到效果。该元素仅包含 task 属性，该属性指定了必须在启动该任务或任务组前完成的任务或任务组的 ID。
一个例子是：只有先创建一个 Java 项目后方能执行任务。此任务将依赖于 清单 4 中的任务。下列代码显示了 dependency 元素，该元素引用了创建一个 Java 项目的任务。
<dependency task="createJavaProject"/>
|
结束语
本文对 Eclipse V3.2 中出现的新特征进行了简短的概述，包括复合备忘单特性。备忘单是 Eclipse 用户辅助中的关键概念，而且重要性还在日益增强。这一技术将会经历更进一步的改善。在 Eclipse V3.2 中，一些额外的新特性还处于临时阶段。
参见 org.eclipse.ui.cheatsheets.cheatSheetContent 扩展点文档，以获取更多有关 taskEditor 和 taskExplorer 的概念（参见 参考资料）。
参考资料 学习
获得产品和技术
讨论
关于作者 | 
| | Philipp Tiedt 是德国 Boeblingen 的 IBM 开发实验室的软件工程师。他从 Open University 获得了计算机科学的学士学位。在 2004 年加入 IBM 德国公司之前，他在纽约 Hawthorne 的 IBM T.J. Watson Research Center 完成了毕业设计。他感兴趣的领域是 Eclipse、用户界面设计、Java 技术和面向服务的架构。 |
对本文的评价
| 
