源查看器和注释

平台文本框架提供了实现编辑器的文档的丰富表示的用户界面类。   

编辑器及其相应的文本查看器主要负责任何必需的 helper 类的文档的表示和配置的实现。(如果您不熟悉查看器的概念,则参见查看器。)  

TextViewer 处理将文档模型及其分区映射为用户看到的已设置格式的彩色文本的所有低级详细信息。对于源代码样式编辑器,提供了 SourceViewer。源查看器提出了源代码注释这一概念。这些注释可以显示在文本左边的垂直标尺中、文本右边的概述标尺中或显示为文本下面的彩色波浪线。

SourceViewer 及其 helper 类在整个 AbstractTextEditor 层次结构中都使用。org.eclipse.jface.text.source 包定义此查看器以及支持注释表示的其它类。

注释和标尺

我们很早就知道除了文档本身之外,文档提供程序还为它的文档注释提供了一种模型 IAnnotationModel。此注释模型保存注释、在请求时枚举注释并且侦听文本更改以便使注释知道文本的最新情况。JavaDocumentProvider 继承在 FileDocumentProvider 中定义的行为及其注释模型。

protected IAnnotationModel createAnnotationModel(Object element) throws CoreException {
	if (element instanceof IFileEditorInput) {
		IFileEditorInput input= (IFileEditorInput) element;
		return new ResourceMarkerAnnotationModel(input.getFile());
	}
	return super.createAnnotationModel(element);
}

ResourceMarkerAnnotationModel 为表示工作区中资源上的标记的注释定义了一种模型。(有关标记的更多信息,参见资源标记。)它为每个标记指定图像和描述,并监视它的资源是否发生了标记更改。

为了了解在文本编辑器中如何显示注释模型,我们将检查平台文本编辑器以及它的标尺和注释的用法。在标尺和文本中如何显示不同的注释可以由用户在注释选项卡上的工作台 > 编辑器 > 文本编辑器首选项中来控制。

垂直标尺

平台文本编辑器使用编辑区左边的垂直标尺来显示文本范围以及与它们的文本行相邻的一行一行的注释。

在所提供的 ResourceMarkerAnnotationModel 中描述了这些注释。当编辑器对源查看器进行了初始化时,就将此模型设置到 SourceViewer 中了。AbstractTextEditor 中的以下片段说明文档和注释模型如何与查看器相关联。

private void initializeSourceViewer(IEditorInput input) {
		
	IAnnotationModel model= getDocumentProvider().getAnnotationModel(input);
	IDocument document= getDocumentProvider().getDocument(input);
		
	if (document != null) {
		fSourceViewer.setDocument(document, model);
		...

一旦使用正确的文档和注释模型配置了源查看器,它就具有足够的信息来显示文档并确保将正确的注释显示在左边的垂直标尺中。当设置文档时,模型就与标尺相关联。以下片段说明当将文档设置到源查看器中时会发生的情况。已经对 SourceViewer 中的实际代码进行了简化以便更清楚地说明问题:

public void setDocument(IDocument document, IAnnotationModel annotationModel) {
	...
	// create visual annotation model from the supplied model and store 
	// in fVisualAnnotationModel
	...
	if (fVerticalRuler != null)
		fVerticalRuler.setModel(fVisualAnnotationModel);

这样,标尺就与适当的注释模型相关联了。  

让我们看一下标尺本身。它是由文本编辑器创建的,然后与编辑器的查看器连接。由于 Java 编辑器示例不会为标尺定义任何特殊行为,因此,它继承 TextEditor 中定义的标尺。

protected IVerticalRuler createVerticalRuler() {
	CompositeRuler ruler= new CompositeRuler();
	ruler.addDecorator(0, new AnnotationRulerColumn(VERTICAL_RULER_WIDTH));
	if (isLineNumberRulerVisible())
		ruler.addDecorator(1, createLineNumberRulerColumn());
	return ruler;
}

文本编辑器使用 CompositeRuler。此标尺没有它自己的可视表示。表示是由显示标尺中的列(IVerticalRulerColumn)的修饰符列表提供的。在此示例中,始终要添加显示注释的标尺列(AnnotationRulerColumn),并且会根据用户首选项来添加行号标尺列。注释标尺列处理在正确位置显示注释图像的详细说明。

不管显示标尺所涉及到的所有类,要注意,示例编辑器只需要子类化框架类以获取标尺行为。JavaDocumentProviderFileDocumentProvider 中继承适当的标记注释。JavaTextEditor 从 TextEditor 中继承标尺表示。

概述标尺

编辑区域右边的概述标尺用来显示与整个文档有关的注释。这些注释是相对于它们在文档中的位置来显示的,当用户滚动文档时,这些注释不会移动。当可以看见这一部分文档时,垂直标尺上通常具有相应的注释。  

下面的垂直标尺显示文档中有两个任务和一个书签。由于可以看见带有书签的文本,因此,它的注释也会显示在左边。

Java 编辑器中的垂直标尺

用户可以通过单击注释本身来浏览至该注释在代码中的位置。

显示在概述标尺中的注释类型是通过将注释类型添加至标尺来确定的。在 SourceViewerDecorationSupport 中的以下片段中,动态地将注释类型添加至标尺了。(有关 SourceViewerDecorationSupport 的更多信息,参见下一节。)

private void showAnnotationOverview(Object annotationType) {
if (fOverviewRuler != null) { Color c= getAnnotationTypeColor(annotationType);
fOverviewRuler.setAnnotationTypeColor(annotationType, c); int l= getAnnotationTypeLayer(annotationType);
fOverviewRuler.setAnnotationTypeLayer(annotationType, l);
fOverviewRuler.addAnnotationType(annotationType);
fOverviewRuler.update();
} }

还随 IAnnotationAccess(它用来提供有关特定注释的信息,例如,该注释的类型以及如何显示它)提供了概述标尺。TextEditor 使用 DefaultMarkerAnnotationAccess,后者根据注释的标记类型来解释注释,并且参考用户首选项来查看哪些标记类型应当显示在概述标尺中。

protected IAnnotationAccess createAnnotationAccess() {
	return new DefaultMarkerAnnotationAccess(fAnnotationPreferences);
}

有关在概述标尺中显示标记的更多详细信息,参考 DefaultMarkerAnnotationAccessMarkerAnnotation 的实现。

文本注释

除了在标尺中显示注释之外,源查看器还可以在文本中使用彩色波浪线标记来显示注释。  

Java 编辑器中的波浪线标记

我们将再次看一下 TextEditor 中源查看器的创建。

protected ISourceViewer createSourceViewer(Composite parent, IVerticalRuler ruler, int styles) {
		
	... 
	ISourceViewer sourceViewer= new SourceViewer(parent, ruler, fOverviewRuler, isOverviewRulerVisible(), styles);
	fSourceViewerDecorationSupport= new SourceViewerDecorationSupport(sourceViewer, fOverviewRuler, fAnnotationAccess, sharedColors);
	configureSourceViewerDecorationSupport();
		
	return sourceViewer;
}

SourceViewerDecorationSupport 处理源查看器中显示的许多修饰,包括文本注释、彩色页边距、彩色光标行和类似的东西。它是使用用户首选项配置的,以便它可以响应用户首选项更改的动态更新。大多数编辑器不需要考虑如何对这些修饰进行着色的详细信息。(在需要时参见 SourceViewerDecorationSupport 和相关类,例如,AnnotationPainter!)。需要知道哪些修饰可用,以便正确配置 SourceViewer 及其支持 SourceViewerDecorationSupport

配置 SourceViewerDecorationSupport

让我们看一下 TextEditor 用于修饰支持的配置。

protected void configureSourceViewerDecorationSupport() {

	Iterator e= fAnnotationPreferences.getAnnotationPreferences().iterator();
	while (e.hasNext())
		fSourceViewerDecorationSupport.setAnnotationPreference((AnnotationPreference) e.next());
	fSourceViewerDecorationSupport.setAnnotationPainterPreferenceKeys(DefaultMarkerAnnotationAccess.UNKNOWN, UNKNOWN_INDICATION_COLOR, UNKNOWN_INDICATION, UNKNOWN_INDICATION_IN_OVERVIEW_RULER, 0);
		
	fSourceViewerDecorationSupport.setCursorLinePainterPreferenceKeys(CURRENT_LINE, CURRENT_LINE_COLOR);
	fSourceViewerDecorationSupport.setMarginPainterPreferenceKeys(PRINT_MARGIN, PRINT_MARGIN_COLOR, PRINT_MARGIN_COLUMN);
	fSourceViewerDecorationSupport.setSymbolicFontName(getFontPropertyPreferenceKey());
}

注意,注释首选项用于为用户首选项中显示的所有注释定义注释类型。这些注释包括任何插件添加的注释,并不限于由工作台提供的注释。如果不想在编辑器中显示所有可用注释,则应覆盖此方法,并只使用想要显示的那些类型来设置 SourceViewerDecorationSupport

Copyright IBM Corporation and others 2000, 2003.