Prohlížeče zdrojů a anotací

Editor a jemu příslušný textový prohlížeč jsou z velké části zodpovědné za implementaci prezentace dokumentu a konfiguraci všech potřebných nápovědných tříd.  (Viz Prohlížeče, pokud nejste dobře seznámeni s konceptem prohlížeče.)  

Textový prohlížeč (TextViewer) obsluhuje všechny nízkoúrovňové podrobnosti ohledně mapování modelu dokumentu a jeho oddílů na barevný a formátovaný text, který uživatel vidí.  Pro editory zdrojového kódu a podobné je poskytnuta třída SourceViewer.   Prohlížeč zdroje zavádí pojem anotací zdrojového kódu.   Tyto anotace lze zobrazit ve vertikálním pravítku na levé straně textu, v pravítku přehledu na pravé straně textu,  nebo jako barevné vlnovky pod textem.

Prohlížeč zdroje (SourceViewer) a jeho nápovědné třídy se používají v celé hierarchii tříd AbstractTextEditor.  Balíček org.eclipse.jface.text.source definuje tento prohlížeč a další třídy, které podporují prezentování anotací.

Anotace a pravítka

Anotace, podobně jako oddíly, značně závisí na typu dokumentu, který se upravuje. Rozhraní IAnnotationModel je pro dokument tím, co udržuje anotace, na žádost vytvoří jejich výčet a naslouchá změnám textu, aby udržovalo anotace aktuální vzhledem k textu. Modely anotací se registrují v rozšíření org.eclipse.core.filebuffers.annotationModelCreation. Tento bod rozšíření umožňuje modulům plug-in registrovat třídu, která vytvoří model anotací vhodný pro danou příponu souboru. Ukázkový editor jazyka Java tento bod rozšíření nepoužívá, takže zdědí model anotací definovaný platformou.

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

Dodaná třída továrny vytvoří model anotací ResourceMarkerAnnotationModel pro soubory s jakoukoliv příponou. Tato třída zobrazuje anotace, které představují značku na zdroji v pracovní ploše.   (Viz Značkovače prostředků, kde jsou další informace o značkovačích.)   Přiřazuje každému značkovači obrázek a popis a monitoruje její prostředek, zda ve značkovačích nejsou změny.

Abychom viděli, jak se model anotací zobrazí v textovém editoru, prozkoumáme textový editor platformy a jeho využití pravítek a anotací.  Podrobnosti zobrazování různých anotací v pravítkách a v textu může uživatel řídit předvolbami v nabídce Obecné > Editory > Textové editory > Anotace.

Vertikální pravítko

Vertikální pravítko vlevo od editační plochy používají textové editory platformy k zobrazení úseků textu a řádkově založených anotací vedle příslušného řádku textu.

Vertikální pravítko

Tyto anotace jsou popsány v dodaném modelu ResourceMarkerAnnotationModel.  Tento model je nastaven do prohlížeče SourceViewer, když editor inicializuje prohlížeč zdroje.  Následující úsek ze třídy AbstractTextEditor ukazuje, jak se dokument a model anotací přiřadí k prohlížeči.

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

Jakmile se prohlížeč zdroje zkonfiguruje s náležitým dokumentem a modelem anotací, má dostatek informací k prezentování dokumentu a k zajištění, aby se ve vertikálním pravítku vlevo zobrazovaly správné anotace.  Model se asociuje s pravítkem, když se dokument nastavuje.  Následující úsek ukazuje, co se stane, když se dokument nastaví do prohlížeče zdroje.  Oproti skutečnému kódu třídy SourceViewer byl pro přehlednost zjednodušen:

public void setDocument(IDocument document, IAnnotationModel annotationModel) {
	...
	// vytvoření vizuálního modelu anotací z dodaného modelu a paměti
	// ve fVisualAnnotationModel
	...
	if (fVerticalRuler != null)
		fVerticalRuler.setModel(fVisualAnnotationModel);

Tímto způsobem se pravítko asociuje s příslušným modelem anotací.   

Podívejme se na pravítko samotné.  Je vytvořeno textovým editorem a pak spojeno s prohlížečem editoru.  Protože ukázkový editor jazyka Java nedefinuje pro pravítka žádné speciální chování, zdědí pravítko tak, jak je definováno ve třídě TextEditor.

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

Textový editor používá CompositeRuler. Toto pravítko nemá vlastní vizuální prezentaci.   Prezentaci poskytuje seznam dekorátorů, které v pravítku zobrazují sloupce (IVerticalRulerColumn).   V tomto příkladu se vždy přidá sloupec pravítka, který zobrazuje anotace (AnnotationRulerColumn), a na základě uživatelských předvoleb se přidá sloupec pravítka s čísly řádků. Sloupec pravítka s anotacemi obsluhuje konkrétní podrobnosti ohledně zobrazování obrázků anotací v náležitých umístěních.

Povšimněte si, že navzdory množství tříd, které zasahují do zobrazení pravítka, musel ukázkový editor pouze vytvořit podtřídy rámcových tříd, aby získal chování pravítka.    JavaDocumentProvider  dědí příslušný model anotací od třídy FileDocumentProvider.  JavaTextEditor dědí prezentaci pravítka od třídy TextEditor.

Pravítko přehledu

Pravítko přehledu na pravé straně editační plochy se používá k zobrazení anotací, které se vztahují k celému dokumentu.  Tyto anotace ze zobrazují relativně vzhledem ke své pozici v dokumentu a nepřesouvají se, když se uživatel posouvá v dokumentu.  Ve vertikálním pravítku je obvykle odpovídající anotace, když je tato část dokumentu viditelná.  

Vertikální pravítko zobrazené níže ukazuje, že v dokumentu jsou dvě úlohy a jedna záložka.   Protože text označený záložkou je vidět, je jeho anotace zobrazena také vlevo.

Vertikální pravítko přehledu v editoru Java

Uživatel může navigovat na umístění anotace v kódu klepnutím na tuto anotaci.

Typy anotací zobrazené v přehledovém pravítku se určí přidáním typů anotací do pravítka.   V následujícím úseku ze třídy SourceViewerDecorationSupport se typy anotací dynamicky přidávají do pravítka. (Další informace o třídě SourceViewerDecorationSupport najdete v následujícím oddílu.)

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();
} }

Pravítku přehledu se rovněž dodává objekt typu IAnnotationAccess, který se používá k poskytnutí informací o konkrétní anotaci, například o jejím typu a způsobu, jak se má zobrazit.  Třída TextEditor používá třídu DefaultMarkerAnnotationAccess, která interpretuje anotace podle jejich typů značek a konzultuje uživatelské předvolby, aby zjistila, které typy značek se mají v pravítku přehledu zobrazit.

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

Další informace o zobrazování značek na pravítku přehledu získáte prostudováním implementace DefaultMarkerAnnotationAccess a MarkerAnnotation.

Anotace textu

Kromě zobrazování anotací v pravítkách může prohlížeč zdroje zobrazovat anotace jako barevné vlnovky v textu.   

Vlnovka v editoru Java

Znovu se podíváme na vytváření prohlížeče zdroje ve třídě 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;
}

Třída SourceViewerDecorationSupportošetřuje většinu zdobení zobrazeného v prohlížeči zdroje, včetně anotací textu, barevných okrajů, barevných kurzorových linek apod.  Konfiguruje se pomocí uživatelských předvoleb, takže může odpovídat na dynamické aktualizace změn uživatelských předvoleb.   Většina editorů se nemusí zabývat podrobnostmi, jak se toto zdobení vykresluje.  (Pokud opravdu chcete, podívejte se na SourceViewerDecorationSupporta související třídy, jako např. AnnotationPainter).  Důležité je vědět, jaká zdobení jsou k dispozici, aby se správně nakonfiguroval prohlížeč zdroje SourceViewer a jeho podpůrná třída SourceViewerDecorationSupport.

Konfigurace podpory SourceViewerDecorationSupport

Podívejme se na konfiguraci, kterou pro podporu zdobení používá 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());
}

Všimněte si, že předvolby anotací se používají k definici typů anotací pro všechny anotace zobrazené v uživatelských předvolbách.  To zahrnuje anotace, kterými přispěl libovolný modul plug-in, a neomezuje se na anotace dodané pracovní plochou.  Nechcete-li ve svém editoru zobrazovat všechny dostupné anotace, měli byste tuto metodu předefinovat a nastavit SourceViewerDecorationSupport jenom s těmi typy, které zobrazit chcete.