Quellenanzeigefunktionen und Anmerkungen

Das Textgerüst der Plattform stellt Klassen für Benutzerschnittstellen bereit, die die reichhaltige Darstellung eines Editordokuments implementieren.   

Der Editor und seine entsprechende Textanzeigefunktion sind größtenteils für die Implementierung der Dokumentdarstellung und die Konfiguration der ggfs. benötigten Helperklassen verantwortlich.   (Der Abschnitt Anzeigefunktionen liefert Ihnen grundlegende Informationen, wenn Sie mit dem Konzept einer Anzeigefunktion nicht vertraut sind.)   

Ein Objekt TextViewer verarbeitet alle untergeordneten Details für die Zuordnung des Dokumentmodells und seiner Partitionen in dem farblich gestalteten und formatierten Text, der für den Benutzer angezeigt wird.  Bei Editoren mit Quellcodedarstellung wird ein SourceViewer bereitgestellt.  Eine Anzeigefunktion für Quelldaten führt das Konzept der Quellcodeanmerkungen ein.  Diese Anmerkungen können in einer vertikalen Skala links vom Text, in einer Übersichtsskala rechts vom Text oder als Textunterstreichungen in bestimmten Farben angezeigt werden.

SourceViewer und seine Helperklassen werden in der gesamten Hierarchie von AbstractTextEditor verwendet.  Das Paket org.eclipse.jface.text.source definiert diese Anzeigefunktion und weitere Klassen, die die Darstellung von Anmerkungen unterstützen.

Anmerkungen und Skalen

Wie bereits erläutert, stellt ein Dokumentprovider neben dem eigentlichen Dokument auch ein Modell für die Anmerkungen im Dokument bereit, nämlich IAnnotationModel.   Dieses Anmerkungsmodell enthält die Anmerkungen, listet sie bei einer entsprechenden Anforderung auf und ist für Textänderungen empfangsbereit, damit die Anmerkungen jederzeit dem aktuellen Text entsprechen.  Der JavaDocumentProvider übernimmt das in FileDocumentProvider definierte Verhalten und somit auch das entsprechende Anmerkungsmodell.

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 definiert ein Modell für Anmerkungen, die eine Markierung für eine Ressource im Arbeitsbereich darstellen.  (Weitere Informationen zu Markierungen können Sie unter Ressourcenmarkierungen nachlesen.)  Es ordnet jeder Markierung ein Image und eine Beschreibung zu und überwacht seine Ressourcen auf Änderungen in den Markierungen.

Die Umsetzung eines Anmerkungsmodells in einem Texteditor soll nun anhand des Texteditors der Plattform und seiner Verwendung von Skalen und Anmerkungen veranschaulicht werden.  Die Spezifikationen für das Anzeigen unterschiedler Anmerkungen in den Skalen und dem Text können vom Benutzer auf der Registerkarte Anmerkungen in den Benutzervorgaben Workbench > Editoren > Texteditor gesteuert werden.

Vertikale Skala

Eine vertikale Skala links vom Bearbeitungsbereich wird von Texteditoren der Plattform verwendet, um Textbereiche und zeilenorientierte Anmerkungen direkt neben ihrer Textzeile anzuzeigen.

Diese Anmerkungen sind im bereitgestelltenResourceMarkerAnnotationModel beschrieben.  Dieses Modell wird in denSourceViewer gestellt, sobald die Quellenanzeigefunktion durch den Editor initialisiert wird.  Der folgende Ausschnitt aus AbstractTextEditor veranschaulicht, wie das Dokument- und das Anmerkungsmodell der Anzeigefunktion zugeordnet sind.

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

Sobald die Quellenanzeigefunktion mit dem richtigen Dokument- und Anmerkungsmodell konfiguriert ist, verfügt sie über genügend Informationen, um das Dokument darzustellen und das Anzeigen der korrekten Anmerkungen in der linken vertikalen Skala zu gewährleisten.  Das Modell wird der Skala beim Definieren des Dokuments zugeordnet.  Der folgende Ausschnitt zeigt, was passiert, wenn ein Dokument in die Quellenanzeigefunktion gestellt wird.  Der tatsächliche Code ausSourceViewer wurde der besseren Verständlichkeit halber vereinfacht:

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

Auf diese Weise wird der Skala das passende Anmerkungsmodell zugeordnet.   

Als Nächstes geht es um die eigentliche Skala.  Sie wird durch den Texteditor erstellt und dann mit der Anzeigefunktion des Editors verbunden.  Da der Java-Beispieleditor kein spezielles Verhalten für Skalen definiert, übernimmt er die Skala so, wie dies in TextEditor definiert ist.

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

Der Texteditor verwendet ein Objekt "CompositeRuler". Diese Skala hat keine eigene optische Darstellung.   Die Darstellung wird durch eine Liste von Dekoratoren bereitgestellt, die Spalten (IVerticalRulerColumn) in der Skala anzeigen.  Im verwendeten Beispiel wird immer eine Skalenspalte hinzugefügt, die Anmerkungen anzeigt(AnnotationRulerColumn). Außerdem wird basierend auf den Benutzervorgaben eine Skalenspalte für Zeilennummern hinzugefügt. Die Skalenspalte für Anmerkungen verarbeitet die Besonderheiten, die für das Anzeigen der Anmerkungsimages an den richtigen Positionen gelten.

Ungeachtet aller Klassen, die am Anzeigen einer Skala beteiligt sind, müssen Sie beachten, dass der Beispieleditor lediglich Gerüstklassen als Unterklassen definieren muss, um das Skalenverhalten zu erreichen.    JavaDocumentProvider übernimmt ein geeignetes Anmerkungsmodell für Markierungen aus FileDocumentProvider.  "JavaTextEditor" übernimmt die Skalendarstellung aus TextEditor.

Übersichtsskala

Eine Übersichtsskala auf der rechten Seite des Bearbeitungsbereichs wird für das Anzeigen von Anmerkungen verwendet, die das gesamte Dokument betreffen.  Diese Anmerkungen werden in Relation zu ihrer Position im Dokument angezeigt und verschieben sich nicht, wenn der Benutzer im Dokument blättert.  Normalerweise enthält die vertikale Skala eine korrespondierende Anmerkung, wenn der entsprechende Dokumentteil sichtbar ist.  

Die unten dargestellte vertikale Skala zeigt, dass das Dokument zwei Tasks und ein Lesezeichen enthält.   Da der mit dem Lesezeichen versehene Text sichtbar ist, werden auch die entsprechenden Anmerkungen auf der linken Seite angezeigt.

Vertikale Skala im Java-Editor

Der Benutzer kann zu der Position der Anmerkung im Code navigieren, indem er auf die Anmerkung klickt.

Die Typen der in der Übersichtsskala angezeigten Anmerkungen werden durch das Hinzufügen von Anmerkungstypen zur Skala bestimmt.  Im folgenden Ausschnitt, der ausSourceViewerDecorationSupport stammt, werden Anmerkungstypen dynamisch zur Skala hinzugefügt. (Weitere Informationen zu SourceViewerDecorationSupport finden Sie im nächsten Abschnitt.)

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

Die Übersichtsskala ist außerdem mit einem ObjektIAnnotationAccess ausgestattet, mit dem Informationen zu einer bestimmten Anmerkungen bereitgestellt werden, z. B. ihr Typ und die Art und Weise, in der sie angezeigt werden soll.  Der TextEditor verwendet ein ObjektDefaultMarkerAnnotationAccess, das Anmerkungen anhand ihrer Markierungstypen interpretiert und in den Benutzervorgaben feststellt, welche Markierungstypen in der Übersichtsskala angezeigt werden sollen.

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

Weitere Einzelheiten über die Darstellung von Markierungen in der Übersichtsskala können Sie in der Implementierung vonDefaultMarkerAnnotationAccess und MarkerAnnotation nachlesen.

Textanmerkungen

Eine Quellenanzeigefunktion kann nicht nur Anmerkungen in den Skalen anzeigen, sondern auch als Unterstreichungen mit bestimmten Farben im Text darstellen.   

Unterstreichungsmarkierung im Java-Editor

In diesem Zusammenhang soll erneut die Erstellung der Quellenanzeigefunktion inTextEditor betrachtet werden.

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

Die KlasseSourceViewerDecorationSupport verarbeitet viele der in einer Quellenanzeigefunktion dargestellten Dekoratoren, wie beispielsweise Textanmerkungen, farbige Ränder, farbige Cursorzeilen usw.   Sie wird mit den Benutzervorgaben konfiguriert, damit sie auf dynamische Aktualisierungen der Benutzervorgaben reagieren kann.   Die meisten Editoren benötigen keine besonderen Informationen dazu, wie diese Dekoratoren farblich gekennzeichnet werden.  (Wenn Sie zu diesem Punkt weitere Informationen nachlesen möchten, lesen Sie hierzu die Angaben zuSourceViewerDecorationSupport und den zugehörigen Klassen wie beispielsweiseAnnotationPainter.)   Wichtig ist lediglich, welche Dekoratoren verfügbar sind, damit der SourceViewer und sein entsprechendes ObjektSourceViewerDecorationSupport korrekt konfiguriert sind.

"SourceViewerDecorationSupport" konfigurieren

Die Unterstützung für Dekoratoren soll am Beispiel der Konfiguration veranschaulicht werden, die vonTextEditor verwendet wird.

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

Bitte beachten Sie, dass die Benutzervorgaben für Anmerkungen verwendet werden, um Anmerkungstypen für alle in den Benutzervorgaben dargestellten Anmerkungen zu definieren.  Dies schließt auch Anmerkungen ein, die durch Plug-ins ergänzt werden, und ist nicht auf die von der Workbench bereitgestellten Anmerkungen beschränkt.  Wenn im Editor nicht alle verfügbaren Anmerkungen angezeigt werden sollen, sollten Sie diese Methode überschreiben und SourceViewerDecorationSupport nur mit den gewünschten Typen definieren.

Copyright IBM Corporation und Andere 2000, 2003.