Källkodsvisning och anteckningar

Redigeraren och motsvarande textvisningsprogram ansvarar i hög grad för implementeringen av dokumentets presentation och konfiguration av erforderliga hjälpklasser. (Se Visningsprogram om du vill ha mer information om konceptet för ett visningsprogram.)  

En TextViewer hanterar alla lågnivåsdetaljer för mappning av dokumentmodellen och dess partitioner till den färglagda och formaterade text som en användare kan se. För källkodsredigerare finns en SourceViewer. Ett källkodsvisningsprogram ger information om källkodsanteckningar. De här anteckningarna kan visas i en vertikal linjal på den vänstra sidan om texten och i en översiktslinjal på den högra eller så visas de färglagda och snirkliga under texten.

SourceViewer och dess hjälpklasser används överallt i AbstractTextEditor-hiearkin. Paketet org.eclipse.jface.text.source definierar det här visningsprogrammet och de andra klasserna med funktioner för anteckningspresentation.

Anteckningar och linjerader

Anteckningar, liksom partitioner, beror i hög grad på den typ av dokument som redigeras. IAnnotationModel för ett dokument lagrar anteckningarna, räknar upp dem mot begäran och lyssnar efter textändringar för att hålla anteckningarna uppdaterade med texten. Anteckningsmodeller registreras i utökningen org.eclipse.core.filebuffers.annotationModelCreation. Den här utökningspunkten gör att insticksprogram kan registrera en klass som skapar en anteckningsmodell som är lämplig för ett givet filtillägg. I exemplet med Java-redigeraren används inte denna utökningspunkt, därför ärvs anteckningsmodellen som är definierad i plattformen.

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

Den tillförda fabriksklassen skapar en ResourceMarkerAnnotationModel för filer med något tillägg. Den här klassen visar anteckningar som representerar en markör på en resurs på arbetsytan. (Mer information om markörer finns under Resursmarkörer.) Den tilldelar en bild och beskrivning till varje markör och övervakar sin resurs med avseende på förändringar i markörerna.

För att se hur en anteckningsmodell visas i en textredigerare, ska vi undersöka plattformens textredigerare och dess användning av linjerader och anteckningar.  Specifikationerna för hur olika anteckningar visas på linjerader och texten kan kontrolleras av användaren via inställningarna Allmänt > Redigerare > Textredigerare > Anteckningar .

Vertikal linjal

En vertikal linjal till vänster om redigeringsområdet används av plattformens textredigerare för att visa textstycken och radbaserade anteckningar bredvid tillhörande textrader.

Vertikal linjal

De här anteckningarna beskrivs i ResourceMarkerAnnotationModel. Den här modellen definieras i SourceViewer när källkodsvisningsprogrammet initieras av redigeraren. Följande kodstycke från AbstractTextEditor visar hur dokumentet och anteckningsmodellen associeras till 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 källkodsvisningsprogrammet konfigurerats med korrekt dokument och anteckningsmodell, kan dokumentet visas med korrekta anteckningar i den vertikala linjalen till vänster. Modellen associeras till linjalen när dokumentet definieras. Följande kodstycke visar vad som händer när ett dokument ställs in i källkodsvisningsprogrammet. Det har förenklats från den faktiska koden i SourceViewer för tydlighets skull:

public void setDocument(IDocument document, IAnnotationModel annotationModel) {
	...
	// skapa synlig anteckningsmodell från den tillförda modellen och lagra 
	// i fVisualAnnotationModel
	...
	if (fVerticalRuler != null)
		fVerticalRuler.setModel(fVisualAnnotationModel);

På detta sätt associeras linjalen med lämplig anteckningsmodell.  

Låt oss titta på själva linjalen. Den skapas av textredigeraren och kopplas därefter till redigerarens visningsprogram. Eftersom det inte definieras något speciellt beteende för linjaler i exemplet med Java-redigeraren, ärvs den linjal som definierats 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;
}

I textredigeraren används en CompositeRuler. Denna linjal har inte någon egen visuell presentation. Presentationen sker med hjälp av en lista med dekoratörer som visar kolumner (IVerticalRulerColumn) i linjalen. I detta exempel läggs en linjalkolumn med anteckningar (AnnotationRulerColumn) alltid till och en linjalkolumn med radnummer läggs till baserat på användarens inställningar. I linjalkolumnen för anteckningar hanteras visning av anteckningsbilderna så att de hamnar på rätt ställen.

Observera att exempelredigeraren behöver bara subklasser i ramverkets klasser för att få linjalbeteende, trots alla klasser som används för att visa en linjal.  JavaDocumentProvider ärver en lämplig marköranteckningsmodell från FileDocumentProvider.  JavaTextEditor ärver linjalpresentationen från TextEditor.

Översiktslinjal

En översiktslinjal på höger sida om redigeringsområdet används för att visa anteckningar som gäller för hela dokumentet. Dessa anteckningar visas i förhållande till sina positioner i dokumentet och flyttas inte om användaren rullar dokumentet.  Det finns normalt en motsvarande anteckning på den vertikala linjalen när den delen av dokumentet blir synlig.  

Den vertikala linjalen nedan visar att det finns två åtgärder i dokumentet och ett bokmärke. Eftersom den bokmärkta texten är synlig, visas även tillhörande anteckning på vänster sida.

Vertikal översiktslinjal i Java-redigerare

Användaren kan navigera till anteckningens position i koden genom att klicka på själva anteckningen.

De typer av anteckningar som visas i översiktslinjalen bestäms genom att man lägger till anteckningstyper i linjalen. I följande kodstycke från SourceViewerDecorationSupport, läggs anteckningstyper dynamiskt till i linjalen.(I nästa avsnitt finns mer information om 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();
} }

Översiktslinjalen tillförs även med en IAnnotationAccess som används för att ge information om en viss anteckning, som t.ex. dess typ och hur den ska visas. I TextEditor används en DefaultMarkerAnnotationAccess som tolkar anteckningar enligt tillhörande markörtyper och rådgör med användarinställningarna för att se vilka markörtyper som ska visas i översiktslinjalen.

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

Mer information om visning av markörer i översiktslinjalen finner du i implementeringen av DefaultMarkerAnnotationAccess och MarkerAnnotation.

Textanteckningar

Förutom att visa anteckningar i linjalerna kan ett källkodsvisningsprogram även visa anteckningar som färglagda, snirkliga markeringar i texten.  

Snirklig markering i Java-redigerare

Vi tittar igen på skapandet av källkodsvisningsprogrammet 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 hanterar många av de dekorationer som visas i ett källkodsvisningsprogram bl.a. textanteckningar, färglagda marginaler, färglagda markörrader o.dyl. Den konfigureras med användarinställningarna så att den kan svara på dynamiska uppdateringar när användarinställningarna ändras. De flesta redigerare behöver inga uppgifter om hur dessa dekorationer målas. (Se vid behovSourceViewerDecorationSupport och tillhörande klasser som t.ex. AnnotationPainter.). Det viktigaste är att känna till vilka dekorationer som finns tillgängliga så att SourceViewer och dess stödjande SourceViewerDecorationSupport konfigureras korrekt.

Konfiguration av en SourceViewerDecorationSupport

Låt oss titta på konfigurationen som används av TextEditor för dekorationsstödet.

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

Observera att anteckningsinställningarna används för att definiera anteckningstyper för alla anteckningar som visas i användarinställningarna. Detta innefattar även anteckningar som lagts till via ett insticksprogram och begränsas inte anteckningar från arbetsmiljön. Om du inte vill att alla tillgängliga anteckningar ska visas i din redigerare kan du ersätta denna metod och ställa in SourceViewerDecorationSupport så att bara önskade typer visas.