Bronviewers en annotaties

De editor en de bijbehorende tekstviewer zijn grotendeels verantwoordelijk voor de implementatie van de presentatie van het document en de configuratie van eventueel vereiste helperklassen. (Zie Viewers als u niet vertrouwd bent met het begrip 'viewer'.)  

Een TextViewer (tekstviewer) verwerkt alle toegewezen detailgegevens met betrekking tot het documentmodel en de bijbehorende partities in de gekleurde en opgemaakte tekst die zichtbaar is voor de gebruiker. Voor broncodestijleditors is er een SourceViewer. Een bronviewer werkt met broncode-annotaties. Deze annotaties kunnen worden afgebeeld in een verticale liniaal links van de tekst, een overzichtsliniaal rechts van de tekst of als gekleurde golflijntjes onder (gedeelten van de) tekst.

SourceViewer en de bijbehorende helperklassen worden overal in de hiërarchie van AbstractTextEditor gebruikt. Het pakket org.eclipse.jface.text.source definieert deze viewer en de overige klassen met ondersteuning voor de presentatie van annotaties.

Annotaties en linialen

Annotaties, evenals partities, zijn hoofdzakelijk afhankelijk van het soort document dat wordt bewerkt. Het IAnnotationModel voor een document dient als opslagplaats voor de annotaties, somt deze op aanvraag op, en luistert naar tekstwijzigingen om de annotaties up-to-date te houden. Annotatiemodellen worden geregisteerd in de extensie org.eclipse.core.filebuffers.annotationModelCreation. Met dit extensiepunt kunnen plugins een klasse registreren die een geldig annotatiemodel maakt voor een bepaalde bestandsextensie. In het voorbeeld van de Java-editor wordt dit extensiepunt niet gebruikt. Daarom wordt het annotatiemodel van het platform overgenomen.

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

De gegeven factoryklasse maakt een ResourceMarkerAnnotationModel voor bestanden met een extensie. Deze klasse geeft annotaties weer die een merkteken voor een resource in het werkgebied vertegenwoordigen. (Zie Resourcemerktekens voor meer informatie over merktekens.) Deze wijst een afbeelding en een beschrijving toe aan elk merkteken en controleert de resource op eventuele wijzigingen in de merktekens.

Om te zien hoe een annotatiemodel wordt weergegeven in een teksteditor, gaan we hier wat dieper in op de teksteditor van het platform en het gebruik van linialen en annotaties.  De specifieke instellingen voor de weergave van annotaties op de linialen en tekst kunnen door de gebruiker worden gedefinieerd op de voorkeurenpagina Algemeen > Editors > Teksteditors > Annotaties .

Verticale liniaal

Links van het werkgebied bevindt zich een verticale liniaal die door platformteksteditors wordt gebruikt om tekstbereik- en regelannotaties af te beelden naast de desbetreffende tekstregels.

Verticale liniaal

Deze annotaties worden beschreven in ResourceMarkerAnnotationModel. Dit model wordt in de SourceViewer opgenomen wanneer de bronviewer door de editor wordt geïnitialiseerd. In de volgende snippet van AbstractTextEditor ziet u hoe het document en het annotatiemodel aan de viewer worden gekoppeld.

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

Als de bronviewer eenmaal is geconfigureerd met het juiste document en annotatiemodel, is er voldoende informatie om het document af te beelden met de juiste annotaties op de verticale liniaal aan de linkerkant van het scherm. Het model wordt aan de liniaal gekoppeld bij plaatsing van het document. In de volgende snippet ziet u wat er gebeurt wanneer een document in de bronviewer wordt geplaatst. Voor de duidelijkheid is hier een vereenvoudigde versie van de daadwerkelijke code in SourceViewer weergegeven:

public void setDocument(IDocument document, IAnnotationModel annotationModel) {
	...
	// visueel annotatiemodel maken op basis van het aangeleverde model en dit opslaan
	// in fVisualAnnotationModel
	...
	if (fVerticalRuler != null)
		fVerticalRuler.setModel(fVisualAnnotationModel);

Op deze manier wordt de liniaal gekoppeld aan het bijbehorende annotatiemodel.  

In dit gedeelte wordt dieper ingegaan op de liniaal. De liniaal wordt gemaakt door de teksteditor en vervolgens gekoppeld aan de bijbehorende viewer. Omdat in het Java-editorvoorbeeld geen aangepast gedragspatroon voor linialen wordt gedefinieerd, wordt de liniaal overgenomen zoals deze is gedefinieerd in TextEditor.

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

De teksteditor maakt gebruik van een CompositeRuler. Deze liniaal heeft geen eigen visuele presentatie. De presentatie wordt aangeleverd door een lijst met decoratieprogramma's voor de weergave van kolommen (IVerticalRulerColumn) in de liniaal. In dit voorbeeld wordt altijd een liniaalkolom met annotaties (AnnotationRulerColumn) toegevoegd. Afhankelijk van de gebruikersvoorkeuren kan ook een liniaalkolom voor regelnummers worden toegevoegd. De instellingen om annotatie-afbeeldingen weer te geven op de juiste locaties worden verwerkt door de liniaalkolom voor annotaties.

U ziet dat, ondanks alle klassen die betrokken zijn bij de weergave van een liniaal, voor de voorbeeldeditor alleen maar subklassen van frameworkklassen hoeven te worden gebruikt om liniaalgedrag te realiseren. JavaDocumentProvider neemt een toepasselijk merktekenannotatiemodel over van FileDocumentProvider.  De JavaTextEditor neemt de liniaalpresentatie over van TextEditor.

Overzichtsliniaal

Rechts van het werkgebied wordt een overzichtsliniaal afgebeeld met annotaties die betrekking hebben op het hele document. Deze annotaties worden afgebeeld in relatie tot hun positie in het document en veranderen niet als de gebruiker door het document bladert. Meestal wordt een overeenkomstige annotatie afgebeeld op de verticale liniaal wanneer dat gedeelte van het document zichtbaar is.  

De verticale liniaal hieronder kunt u zien dat het document twee taken en één bladwijzer bevat. Omdat de tekst met de bladwijzer zichtbaar is, wordt links ook een annotatie afgebeeld.

Verticale overzichtsliniaal in Java-editor

De gebruiker kan naar de locatie van de annotatie in de code springen door op de annotatie te klikken.

Welke typen annotaties op de overzichtsliniaal worden afgebeeld, is afhankelijk van welke annotatietypen er aan de liniaal zijn toegevoegd. In de volgende snippet van SourceViewerDecorationSupport worden annotatietypen dynamisch aan de liniaal toegevoegd.(Zie de volgende sectie voor meer informatie over 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();
} }

De overzichtsliniaal wordt ook aangeleverd bij een IAnnotationAccess, die wordt gebruikt om informatie aan te leveren over een bepaalde annotatie, zoals het annotatietype en de bijbehorende weergave-instellingen. De TextEditor maakt gebruik van een DefaultMarkerAnnotationAccess. Hiermee worden annotaties geïnterpreteerd op merktekentype en de gebruikersvoorkeuren geraadpleegd om te bepalen welke soorten merktekens op de overzichtsliniaal moeten worden afgebeeld.

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

Raadpleeg de implementatie van DefaultMarkerAnnotationAccess en MarkerAnnotation voor meer informatie over de presentatie van merktekens op de overzichtsliniaal.

Tekstannotaties

In een bronviewer kunnen annotaties niet alleen worden afgebeeld op de linialen, maar ook als gekleurde golflijntjes in de tekst.  

Golflijntje in Java-editor

We kijken nogmaals naar de aanmaak van de bronviewer in 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;
}

De klasse SourceViewerDecorationSupport zorgt voor de afhandeling van veel afgebeelde decoraties in een bronviewer, waaronder tekstannotaties, gekleurde marges, gekleurde cursorregels, enzovoort. Deze wordt geconfigureerd met de gebruikersvoorkeuren zodat deze kan reageren op dynamische updates van wijzigingen in gebruikersvoorkeuren. Voor de meeste editors is het irrelevant hoe deze decoraties precies worden gekleurd (zie desgewenst SourceViewerDecorationSupport en gerelateerde klassen zoals AnnotationPainter). Het belangrijkste om te weten is welke decoraties beschikbaar zijn zodat de bronviewer (SourceViewer) en de bijbehorende ondersteuning (SourceViewerDecorationSupport) op de juiste wijze kunnen worden geconfigureerd.

SourceViewerDecorationSupport configureren

Hieronder ziet u de configuratie die door TextEditor wordt gebruikt om decoraties te ondersteunen.

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

U ziet dat dat de annotatievoorkeuren worden gebruikt om annotatietypen te definiëren voor alle annotaties die worden afgebeeld in de gebruikersvoorkeuren. Hieronder vallen ook annotaties die door plugins worden aangeleverd en dus niet alleen annotaties die door de workbench worden aangeleverd. Als u niet wilt dat alle beschikbare annotaties in uw editor worden afgebeeld, moet u deze methode vervangen en SourceViewerDecorationSupport instellen met alleen die typen die u wilt afbeelden.