Der Editor und seine entsprechende Textanzeigefunktion sind größtenteils für die Implementierung der Dokumentendarstellung 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 Dokumentenmodells und seiner Partitionen in dem farblich gestalteten und formatierten Text, der einem 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, wie auch Partitionen, hängen stark von der Art des Dokuments ab, das bearbeitet wird. Das Anmerkungsmodell IAnnotationModel eines Dokuments 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. Anmerkungsmodelle werden in der Erweiterung org.eclipse.core.filebuffers.annotationModelCreation registriert. Über diesen Erweiterungspunkt können Plug-ins eine Klasse registrieren, die ein geeignetes Anmerkungsmodell für eine bestimmte Dateierweiterung erstellt. Das Java-Editor-Beispiel verwendet diesen Erweiterungspunkt nicht und übernimmt somit das von der Plattform definierte Anmerkungsmodell.
<extension point="org.eclipse.core.filebuffers.annotationModelCreation"> <factory extensions="*" class="org.eclipse.ui.texteditor.ResourceMarkerAnnotationModelFactory"> </factory> </extension>
Die bereitgestellte Factoryklasse erstellt ein ResourceMarkerAnnotationModel für Dateien mit jeder beliebigen Erweiterung. Diese Klasse zeigt Anmerkungen an, 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 unterschiedlicher Anmerkungen in den Skalen und dem Text können vom Benutzer in den Benutzervorgaben Allgemein > Editoren > Texteditoren > Anmerkungen gesteuert werden.
Eine vertikale Skala links vom Bearbeitungsbereich wird von Texteditoren der Plattform verwendet, um Textbereiche und zeilenorientierte Anmerkungen direkt neben ihrer Textzeile anzuzeigen.
Diese Anmerkungen werden im bereitgestellten ResourceMarkerAnnotationModel beschrieben. Dieses Modell wird in den SourceViewer 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 Dokumenten- 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 aus SourceViewer 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 besitzt 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.
Eine Übersichtsskala auf der rechten Seite des Editierbereichs wird verwendet, um Anmerkungen über das gesamte Dokument anzuzeigen. Diese Anmerkungen werden im Verhältnis zu ihrer Position im Dokument angezeigt und bewegen sich nicht, wenn der Benutzer im Dokument blättert. Auf der vertikalen Skala ist normalerweise eine entsprechende Anmerkung zu sehen, wenn der entsprechende Abschnitt des Dokuments 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.
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 aus SourceViewerDecorationSupport 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 Objekt IAnnotationAccess 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 Objekt DefaultMarkerAnnotationAccess, 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 von DefaultMarkerAnnotationAccess und MarkerAnnotationnachlesen.
Eine Quellenanzeigefunktion kann nicht nur Anmerkungen in den Skalen anzeigen, sondern auch als Unterstreichungen mit bestimmten Farben im Text darstellen.
In diesem Zusammenhang soll erneut die Erstellung der Quellenanzeigefunktion in TextEditor 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 KlasseSourceViewerDecorationSupportverarbeitet 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 zu SourceViewerDecorationSupport und den zugehörigen Klassen, wie beispielsweise AnnotationPainter.). Wichtig ist lediglich, welche Dekoratoren verfügbar sind, damit der SourceViewer und sein entsprechendes Objekt SourceViewerDecorationSupport korrekt konfiguriert sind.
Die Unterstützung für Dekoratoren soll am Beispiel der Konfiguration veranschaulicht werden, die vonTextEditorverwendet 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.