Kildevisningsprogrammer og annotasjoner

Redigeringsprogrammet og tekstvisningsprogrammet utfører i hovedsak implementeringen av dokumentpresentasjonen og konfigureringen av eventuelle hjelpeklasser. (Du finner mer informasjon om begrepet visningsprogram under Visningsprogrammer.)  

TextViewer håndterer alle detaljer på lavere nivå som gjelder tilordning av dokumentmodell og partisjoner for den fargede og formaterte teksten som en bruker ser.  Redigeringsprogrammer med kildekode har en SourceViewer.  Kildevisningsprogrammer innfører begrepet kildekodeannotasjoner. Disse annotasjonene kan vises i en loddrett linjal til venstre for teksten, en oversiktslinjal til høyre for teksten eller som fargede kruseduller under teksten.

SourceViewer og hjelpeklassene brukes i hele hierarkiet for AbstractTextEditor.  Pakken org.eclipse.jface.text.source definerer dette visningsprogrammet og andre klasser som støtter presentasjon av annotasjoner.

Annotasjoner og linjaler

På samme måte som med partisjoner, er annotasjoner avhengig av hva slags type dokument som redigeres. IAnnotationModel for et dokument inneholder annotasjonene, oppregner dem ved forespørsel og lytter til tekstendringer slik at annotasjonene oppdateres i forhold til teksten. Annotasjonsmodeller registreres i utvidelsen org.eclipse.core.filebuffers.annotationModelCreation. Dette utvidelsespunktet gjør det mulig for plugin-moduler å registrere en klasse som oppretter en annotasjonsmodell for en gitt filtype. Java-redigeringsprogrameksempelet bruker ikke dette utvidelsespunktet, men arver annotasjonsmodellen som er definert av plattformen.

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

Den oppgitte factory-klassen oppretter en ResourceMarkerAnnotationModel for alle typer filer. Denne klassen viser annotasjoner som representerer et merke i en ressurs i arbeidsområdet. (Du finner mer informasjon om merker under Ressursmerker.) Den tilordner et bilde og en beskrivelse til hvert merke og følger med på merkeendringer i ressursen.

Vi skal se hvordan en annotasjonsmodell vises i et tekstredigeringsprogram ved å se nærmere på tekstredigeringsprogrammet for plattformen og hvordan den bruker linjaler og annotasjoner.  Brukeren kan angi egenskaper for hvordan de ulike annotasjonene skal vises i linjalene og teksten, i preferansene under Generelt > Redigeringsprogrammer > Tekstredigeringsprogrammer > Annotasjoner.

Loddrett linjal

Plattformens tekstredigeringsprogrammer bruker en loddrett linjal til venstre for redigeringsområdet for å vise tekstområder og linjebaserte annotasjoner til en tilstøtende tekstlinje.

Loddrett linjal

Annotasjonene beskrives i den oppgitte ResourceMarkerAnnotationModel.  Denne modellen defineres i SourceViewer når kildevisningsprogrammet initialiseres av redigeringsprogrammet. Følgende snutt fra AbstractTextEditor viser hvordan dokumentet og annotasjonsmodellen tilknyttes visningsprogrammet.

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

Når kildevisningsprogrammet konfigureres med riktig dokument og annotasjonsmodell, er informasjonen tilstrekkelig til å presentere dokumentet og sørge for at riktige annotasjoner blir vist i den loddrette linjalen til venstre. Modellen tilknyttes linjalen når dokumentet defineres. Snutten nedenfor viser hva som skjer når et dokument defineres i kildevisningsprogrammet. Koden er forenklet i forhold til den reelle koden i SourceViewer for å tydeliggjøre det hele.

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

På denne måten knyttes linjalen til den riktige annotasjonsmodellen.  

La oss se på selve linjalen. Den opprettes av tekstredigeringsprogrammet og tilknyttes deretter redigeringsvisningsprogrammet. Siden Java-redigeringsprogrameksempelet ikke definerer bestemte funksjoner for linjaler, arves linjalen som er definert i TextEditor.

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

Tekstredigeringsprogrammet bruker en CompositeRuler. Denne linjalen har ikke en egen visuell presentasjon.  Presentasjonen besørges av listen med dekoratører som viser kolonnene (IVerticalRulerColumn) i linjalen. I dette eksempelet legges det alltid til en linjalkolonne som viser annotasjoner (AnnotationRulerColumn), og det legges til en linjalkolonne for linjenummer basert på brukerpreferanser. Linjalkolonnen for annotasjon sørger for at annotasjonsbilder vises på riktig sted.

Til tross for alle klassene som inngår i en linjalvisning, bør du merke deg at eksempelredigeringsprogrammets linjalfunksjonalitet tilveiebringes via subklasser for rammeverksklasser.    JavaDocumentProvider arver en egnet merkeannotasjonsmodell fra FileDocumentProvider.   JavaTextEditor arver linjalpresentasjonen fra TextEditor.

Oversiktslinjal

En oversiktslinjal til høyre i redigeringsområdet blir brukt for å vise annotasjoner for hele dokumentet. Disse annotasjonene vises i forhold til posisjonen i dokumentet og flyttes ikke selv om brukeren ruller nedover i dokumentet.  Det finnes vanligvis en tilsvarende annotasjon i den loddrett linjalen når den delen av dokumentet vises.  

Den loddrette linjalen nedenfor viser at det er to oppgaver i dokumentet og ett bokmerke. Siden teksten med bokmerke er synlig, vises også annotasjonen for teksten til venstre.

Loddrett oversiktslinjal i Java-redigeringsprogram

Brukeren kan navigere seg frem til annotasjonsplasseringen i koden ved å klikke på selve annotasjonen.

De ulike typene annotasjoner som vises i oversiktslinjalen fastsettes ved å legge til annotasjonstyper i linjalen. I snutten nedenfor fra SourceViewerDecorationSupport legges annotasjonstyper dynamisk til i linjalen.(Du finner mer informasjon om SourceViewerDecorationSupport. i neste avsnitt)

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

Oversiktslinjalen oppgis også med en IAnnotationAccess som brukes til å oppgi informasjon om en bestemt annotasjon, for eksempel annotasjonstypen og hvordan den skal vises.  TextEditor bruker en DefaultMarkerAnnotationAccess til å tolke annotasjoner i henhold til merketyper og sjekker brukerpreferansene for å se hvilke merketyper som skal vises i oversiktslinjalen.

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

Les om implementeringen av DefaultMarkerAnnotationAccess og MarkerAnnotation hvis du vil ha mer informasjon om presentasjon av merker i oversiktslinjalen.

Tekstannotasjoner

I tillegg til å vise annotasjoner i linjalene kan et kildevisningsprogram vise annotasjoner som fargede krusedullmerker i teksten.  

Krusedullmerke i Java-redigeringsprogram

Vi skal nok en gang se nærmere på opprettelsen av kildevisningsprogrammet i 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;
}

Klassen SourceViewerDecorationSupport håndterer mange av dekorasjonene som vises i kildevisningsprogrammet, for eksempel tekstannotasjoner, fargede marger og fargede markørlinjer. Klassen konfigureres via brukerpreferansene slik at den kan tilpasses dynamiske oppdateringer i henhold til endringer i brukerpreferansene. Som regel er ikke redigeringsprogrammene involvert i malingen av dekorasjonene.  (Du finner mer informasjon under SourceViewerDecorationSupport og beslektede klasser, for eksempel AnnotationPainter).  Det er viktig å være klar over hvilke dekorasjoner som er tilgjengelig slik at SourceViewer og den tilhørende SourceViewerDecorationSupport, blir konfigurert på riktig måte.

Konfigurere en SourceViewerDecorationSupport

La oss se nærmere på konfigurasjonen som brukes av TextEditor for dekorasjonsstøtte.

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

Merk at annotasjonspreferansene blir brukt til å definere annotasjonstyper for alle annotasjonene som vises i brukerpreferansene. Dette gjelder annotasjoner fra enhver plugin-modul og er ikke begrenset til annotasjonene fra arbeidsbenken. Hvis du vil vise alle tilgjengelige annotasjoner i redigeringsprogrammet, må du overstyre denne metoden og konfigurere SourceViewerDecorationSupport bare med de typene du vil vise.