文档和分区

平台文本框架为文本定义文档模型,并提供一个使用此模型来显示文本的查看器。我们将首先查看 Java 编辑器示例并了解它如何使用此模型。我们将不重点讨论注册编辑器扩展的基本结构,原因是我们已经在讨论 org.eclipse.ui.editors 的那一节中进行了讨论。但是,我们将了解示例中是如何实现编辑器类的细节。

文档提供程序和文档

在工作台中,当用户选择域元素(例如,一个文件或者存储在归档文件中的元素)并打开它时,编辑器通常是打开的。当创建编辑器时,编辑器就会与编辑器输入(IEditorInput)(它描述正在被编辑的对象)相关联。

当用户打开具有“*.jav”扩展的文件时,将打开 Java 编辑器示例。在这种情况中,编辑器的输入是 IFileEditorInput。平台文本框架很少对编辑器输入本身作出假设。它对输入使用称为 IDocument 的表示模型,因此,它可以有效地显示和处理文本。

这意味着必须具有一种方法从期望的域模型(编辑器输入)映射至表示模型。在 IDocumentProvider 中定义了此映射。只要给定编辑器输入,文档提供程序就会返回适当的 IDocument

Java 编辑器示例定义了 JavaDocumentProvider(它将返回适当的文档)。适当的文档提供程序与“*.jav”扩展之间的关系是如何建立的?这种关系是在 org.eclipse.ui.documentProviders 扩展中建立的。此扩展用来定义文件类型与文档提供程序之间的映射。该示例定义其文档提供程序,如下所示:

<extension
      point="org.eclipse.ui.documentProviders">
<provider 
         extensions="jav"
         class="org.eclipse.ui.examples.javaeditor.JavaDocumentProvider"
         id="org.eclipse.ui.examples.javaeditor.JavaDocumentProvider">
   </provider>
 </extension>

当用户打开具有指定扩展的文件时,工作台就会管理创建文档提供程序实例的详细信息。工作台只创建一次文档提供程序实例,然后在不同的编辑器中共享此实例。

您的插件不需要使用此扩展点来注册其文档提供程序。使文档提供程序与编辑器相关联的另一种方法是让插件自己管理文档提供程序。这通常是在插件类中完成的。当将输入元素设置到编辑器中时,编辑器就会要求其插件类提供适当的文档提供程序。插件可以管理文档提供程序的创建和引用。当文档提供程序涉及到特殊的初始化或其它处理时,采用此技术可能会比较好。有关示例,参见 JDT 工具中的 ClassFileEditor。 

一旦正确的文档提供程序已经与编辑器相关联,它的主要任务就是根据编辑器输入创建文档,并配置适当的对象以便将文档划分成多个分区。  

分区

让我们看一下 JavaDocumentProvider 中的文档和分区。当创建了文档时,就会创建一个 IDocumentPartitioner,并将它设置到文档中。  

protected IDocument createDocument(Object element) throws CoreException {
	IDocument document= super.createDocument(element);
	if (document != null) {
		IDocumentPartitioner partitioner= createJavaPartitioner();
		document.setDocumentPartitioner(partitioner);
		partitioner.connect(document);
	}
	return document;
}

分区程序负责将文档划分成不重叠的区域(称为分区)。分区(在 ITypedRegion 中表示)对于根据功能(例如,语法突出显示或格式化)来以不同方式处理文档的不同部分是很有用的。

对于 Java 编辑器示例,文档被划分成表示 javadoc 注释、多行注释和其它内容的分区。对每个区域都指定了内容类型以及它在文档中的位置。当用户编辑文本时,位置就会相应地更新。   

基于规则进行文档分区

由每个编辑器来确定文档分区程序的适当实现。在 org.eclipse.jface.text.rules 中提供了对基于规则进行文档扫描的支持。使用基于规则的扫描程序允许编辑器使用由框架提供的 DefaultPartitioner

private IDocumentPartitioner createJavaPartitioner() {
	return new DefaultPartitioner(getJavaPartitionScanner(), TYPES);
}

RuleBasedPartitionScanner 是基于规则的扫描程序的超类。子类负责枚举和实现一些规则,当扫描文档时,应当使用这些规则来区分标记(例如,行定界符、空格和类属模式)。示例的 JavaPartitionScanner 定义用于区分单行注释、字符常量、javadoc、多行注释和词语的规则。这是在扫描程序的构造函数中完成的:

public JavaPartitionScanner() {
	super();
	IToken javaDoc= new Token(JAVA_DOC);
	IToken comment= new Token(JAVA_MULTILINE_COMMENT);

	List rules= new ArrayList();
	// Add rule for single line comments.
	rules.add(new EndOfLineRule("//", Token.UNDEFINED)); 

	// Add rule for strings and character constants.
	rules.add(new SingleLineRule("\"", "\"", Token.UNDEFINED, '\\')); 
	rules.add(new SingleLineRule("'", "'", Token.UNDEFINED, '\\')); 

	// Add special case word rule.
	rules.add(new WordPredicateRule(comment));

	// Add rules for multi-line comments and javadoc.
	rules.add(new MultiLineRule("/**", "*/", javaDoc, (char) 0, true)); 
	rules.add(new MultiLineRule("/*", "*/", comment, (char) 0, true)); 

	IPredicateRule[] result= new IPredicateRule[rules.size()];
	rules.toArray(result);
	setPredicateRules(result);
}

有关定义规则以及可用的规则类型的更多详细信息,参见 org.eclipse.jface.text.rules 中的类。当我们查看语法着色时将再查看一下扫描程序。

注释模型

除了为编辑器输入提供适当的文档之外,文档提供程序的另一项重要任务是提供适当的 IAnnotationModel 以便与编辑器输入配合使用。此模型用来管理与文档相连的注释。通过让文档提供程序提供模型,编辑器可以使用适合于内容类型的模型。在下一节中,我们将更仔细地查看注释以及它们是如何显示的。

Copyright IBM Corporation and others 2000, 2003.