編輯器及其對應文字檢視器主要負責呈現文件及配置任何必要的 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) { ... // 從提供的模型建立視覺化附註模型,並儲存在 // 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。這個尺規沒有自己的視覺化呈現方式。 呈現方式是由 Decorator 清單所提供,這些 Decorator 顯示尺規中的直欄 (IVerticalRulerColumn)。 在這個範例中,恆會新增一個顯示附註 (AnnotationRulerColumn) 的尺規直欄, 而且會依據使用者喜好設定來新增行號尺規直欄。 附註尺規直欄處理在適當位置顯示附註影像的特殊情況。
儘管在顯示尺規時包括了所有類別,但是請注意,範例編輯器僅需要建立組織架構類別的子類別,以取得尺規行為。 JavaDocumentProvider 會從 FileDocumentProvider 繼承適當的標示元附註模型。 JavaTextEditor 會從 TextEditor 繼承尺規呈現方式。
編輯區右側的總覽尺規是用來顯示關於整份文件的附註。 這些附註會相對於其位置顯示在文件中,因此當使用者捲動文件時, 附註並不會移動。當看到該文件部份時,通常在垂直尺規上會有一個對應的附註。
底下的垂直尺規顯示文件中有兩個作業,以及一個書籤。既然看得到已建立書籤的文字, 那麼它的附註也會顯示在左邊。
使用者可以按一下附註本身,導覽至程式碼中附註的位置。
哪些類型的附註會顯示在總覽尺規中,是藉由新增附註類型至尺規來判定。 在下列來自 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); }
如需如何在總覽尺規中呈現標示元的詳細資料,請參閱 DefaultMarkerAnnotationAccess 和 MarkerAnnotation 的實作方式。
除了在尺規中顯示附註之外,原始檔檢視器還可以在文字中將附註顯示成有顏色的彎彎曲曲符號。
我們將再次查看如何在 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。
讓我們查看 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。