程式檔檢視器和附註

編輯器及其對應文字檢視器主要負責實作文件呈現方式及配置任何必要的 Helper 類別。(如果您還不熟悉檢視器的概念,請參閱檢視器。)  

TextViewer 處理所有低階詳細資料,這些資訊用以說明如何將文字模型及其分割區對映至使用者看到的格式化文字(以顏色標出)。對於程式碼樣式編輯器,提供有 SourceViewer。 程式檔檢視器引入了程式碼附註的概念。 這些附註可以顯示在文字左側的垂直尺規、顯示在文字右側的概觀尺規,或在文字之下顯示成有顏色的彎曲線。

SourceViewer 及其 Helper 類別是用在整個 AbstractTextEditor 階層中。 org.eclipse.jface.text.source 套件定義這個檢視器和其他支援呈現附註的類別。

附註和尺規

註釋(比如說,分割)與編輯的文件種類有很大的關係。文件的 IAnnotationModel 會保留註釋、依要求列舉它們,以及接聽文字變更,以便保有最新的註釋與文字。註釋模型是在 org.eclipse.core.filebuffers.annotationModelCreation 延伸規格中登錄的。 延伸點可允許外掛程式登錄類別來建立適合給定副檔名的註釋模型。「Java 編輯器」範例不使用這個延伸點,所以會繼承平台定義的註釋模型。

   <extension
	point="org.eclipse.core.filebuffers.annotationModelCreation">
	<factory
		extensions="*"
		class="org.eclipse.ui.texteditor.ResourceMarkerAnnotationModelFactory">
	</factory>
</extension>

提供的 Factory 類別將會對任何副檔名的檔案建立 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) {
	...
	// 從提供的模型建立視覺化附註模型,並儲存在
	// 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) 的尺規直欄, 而且會依據使用者喜好設定來新增行號尺規直欄。 附註尺規直欄處理在適當位置顯示附註影像的特殊情況。

儘管在顯示尺規時包括了所有類別,但是請注意,範例編輯器僅需要建立組織架構類別的子類別,以取得尺規行為。 JavaDocumentProvider 會從 FileDocumentProvider 繼承適當的標記註釋模型。  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