Edytor oraz odpowiadająca mu przeglądarka tekstu w wysokim stopniu odpowiadają za implementację prezentacji dokumentu oraz konfigurację niezbędnych klas pomocniczych. Więcej informacji na temat pojęcia przeglądarki zawiera sekcja Przeglądarki.
Klasa TextViewer obsługuje wszystkie szczegóły niskiego poziomu odwzorowania modelu dokumentu oraz jego partycji na kolorowy i sformatowany tekst oglądany przez użytkownika. Na potrzeby edytorów stylu kodu źródłowego udostępniana jest klasa SourceViewer. Przeglądarka kodu źródłowego wprowadza pojęcie adnotacji kodu źródłowego. Adnotacje mogą być wyświetlane na pionowej linijce z lewej strony tekstu, na linijce przeglądu z prawej strony tekstu lub jako kolorowe falki pod tekstem.
Klasa SourceViewer i jej klasy pomocnicze są używane w całej hierarchii klasy AbstractTextEditor. Przeglądarkę oraz inne klasy obsługujące prezentację adnotacji definiuje pakiet org.eclipse.jface.text.source.
Adnotacje, podobnie jak partycje, w wysokim stopniu zależą od rodzaju edytowanego dokumentu. Interfejs IAnnotationModel utrzymuje adnotacje w dokumencie, numeruje je na żądanie i nasłuchuje zmian w tekście, aby były one na bieżąco uwzględniane w adnotacjach. Modele adnotacji są zarejestrowane w rozszerzeniu org.eclipse.core.filebuffers.annotationModelCreation. Ten punkt rozszerzenia umożliwia modułom dodatkowym zarejestrowanie klasy, która utworzy odpowiedni model adnotacji dla danego rozszerzenia pliku. Przykładowy edytor Java nie używa tego punktu rozszerzenia, w związku z czym dziedziczy model adnotacji zdefiniowany przez platformę.
<extension point="org.eclipse.core.filebuffers.annotationModelCreation"> <factory extensions="*" class="org.eclipse.ui.texteditor.ResourceMarkerAnnotationModelFactory"> </factory> </extension>
Dostarczona klasa metody fabrycznej utworzy klasę ResourceMarkerAnnotationModel dla plików o dowolnym rozszerzeniu. W klasie tej będą wyświetlane adnotacje reprezentujące znacznik zasobu w obszarze roboczym. Więcej informacji na temat znaczników zawiera sekcja Znaczniki zasobów. W tej klasie do każdego znacznika zostanie przypisany obraz i opis, a jej zasób będzie monitorowany pod kątem zmian w znacznikach.
W celu pokazania, jak model adnotacji jest wyświetlany w edytorze tekstu, przedstawiony zostanie edytor tekstu platformy i sposób korzystania w nim z linijek i adnotacji. Sposób wyświetlania różnych adnotacji na linijkach i w tekście może określać użytkownik w preferencjach Ogólne > Edytory > Edytory tekstu > Adnotacje.
Linijka pionowa z lewej strony obszaru edycji służy edytorom tekstu platformy do pokazywania zakresów tekstu oraz adnotacji dotyczących konkretnych wierszy tekstu na wysokości tych wierszy.
Opis adnotacji znajduje się w dostarczonym modelu ResourceMarkerAnnotationModel. Model ten zostanie wstawiony do klasy SourceViewer, gdy przeglądarka kodu zostanie zainicjowana przez edytor. Poniższy fragment kodu klasy AbstractTextEditor pokazuje, jak dokument i model adnotacji są powiązane z przeglądarką.
private void initializeSourceViewer(IEditorInput input) { IAnnotationModel model= getDocumentProvider().getAnnotationModel(input); IDocument document= getDocumentProvider().getDocument(input); if (document != null) { fSourceViewer.setDocument(document, model); ...
Przeglądarka kodu źródłowego skonfigurowana z odpowiednim dokumentem i modelem adnotacji ma wystarczająco dużo informacji, aby zaprezentować dokument i zapewnić, że na linijce pionowej z lewej strony będą wyświetlane prawidłowe adnotacje. Powiązanie modelu z linijką następuje w momencie powstania dokumentu. Poniższy fragment kodu pokazuje, co się stanie, gdy dokument zostanie wstawiony do przeglądarki kodu źródłowego. W celu zwiększenia przejrzystości uproszczono rzeczywisty kod klasy SourceViewer:
public void setDocument(IDocument document, IAnnotationModel annotationModel) { ... // utworzenie modelu adnotacji wizualnych na podstawie dostarczonego modelu // i zapisanie go w elemencie fVisualAnnotationModel ... if (fVerticalRuler != null) fVerticalRuler.setModel(fVisualAnnotationModel);
W ten sposób linijka zostanie powiązana z odpowiednim modelem adnotacji.
Przyjrzyjmy się samej linijce. Linijka jest tworzona przez edytor tekstu, a następnie łączona z przeglądarką edytora. Ponieważ przykładowy edytor Java nie definiuje specjalnych zachowań dla linijek, dziedziczy on linijki zdefiniowane w klasie TextEditor.
protected IVerticalRuler createVerticalRuler() { CompositeRuler ruler= new CompositeRuler(); ruler.addDecorator(0, new AnnotationRulerColumn(VERTICAL_RULER_WIDTH)); if (isLineNumberRulerVisible()) ruler.addDecorator(1, createLineNumberRulerColumn()); return ruler; }
Edytor tekstu używa linijki CompositeRuler. Ta linijka nie ma wizualnej prezentacji samej siebie. Prezentacja jest udostępniana przez listę dekoracji, które pokazują kolumny na linijce (interfejs IVerticalRulerColumn). W tym przykładzie kolumna linijki, w której są wyświetlane adnotacje (klasa AnnotationRulerColumn), jest dodawana zawsze, a kolumna linijki z numerami wierszy jest dodawana w zależności od preferencji użytkownika. Kolumna linijki z adnotacjami obsługuje wyświetlanie obrazów adnotacji we właściwych położeniach.
Mimo wszystkich klas związanych z wyświetlaniem linijki, do uzyskania zachowania linijki przykładowy edytor potrzebował jedynie podklas klas środowiska. Podklasa JavaDocumentProvider dziedziczy odpowiedni model adnotacji znaczników z klasy FileDocumentProvider. Podklasa JavaTextEditor dziedziczy prezentację linijki z klasy TextEditor.
Linijka przeglądu z prawej strony obszaru edycji służy do wyświetlania adnotacji dotyczących całego dokumentu. Adnotacje te są wyświetlane względnie swoich położeń w dokumencie i nie są przenoszone, gdy użytkownik przewija dokument. Zwykle wtedy, gdy jest widoczny odpowiedni fragment dokumentu, na linijce pionowej jest wyświetlana właściwa adnotacja.
Na linijce pionowej poniżej jest wyświetlane, że w dokumencie są dwie czynności i jedna zakładka. Ponieważ fragment tekstu opatrzony zakładką jest widoczny, z lewej strony widać również jego adnotację.
Klikając adnotację, można przejść do jej położenia w kodzie.
Typy adnotacji wyświetlane na linijce przeglądu są określane przez dodawanie typów adnotacji do linijki. W poniższym fragmencie kodu klasy SourceViewerDecorationSupport typy adnotacji są dodawane do linijki dynamicznie. Więcej informacji na temat klasy SourceViewerDecorationSupport zawiera następna sekcja.
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();
} }
Linijka przeglądu jest również wyposażona w interfejs IAnnotationAccess, który służy do wyświetlania informacji o adnotacji, takich jak typ czy sposób wyświetlania. Klasa TextEditor używa klasy DefaultMarkerAnnotationAccess, która interpretuje adnotacje stosownie do ich typów znaczników i sprawdza preferencje użytkownika, aby ustalić, które typy znaczników powinny być wyświetlane na linijce przeglądu.
protected IAnnotationAccess createAnnotationAccess() { return new DefaultMarkerAnnotationAccess(fAnnotationPreferences); }
Aby uzyskać więcej informacji na temat prezentowania znaczników na linijce przeglądu, należy zapoznać się z implementacją klas DefaultMarkerAnnotationAccess i MarkerAnnotation.
W przeglądarce kodu źródłowego adnotacje można wyświetlać nie tylko na linijkach, ale i jako kolorowe falki w tekście.
Teraz jeszcze raz pokazany zostanie sposób tworzenia przeglądarki kodu źródłowego w klasie 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; }
Klasa SourceViewerDecorationSupport obsługuje wiele dekoracji wyświetlanych w przeglądarce kodu źródłowego, takich jak adnotacje w tekście, kolorowe marginesy, kolorowe wiersze z kursorem itp. Klasa ta jest skonfigurowana z preferencjami użytkownika, aby mogła dynamicznie reagować na ich zmiany. W większości edytorów nie są definiowane szczegóły wyświetlania dekoracji. W razie konieczności można się zapoznać z informacjami o klasie SourceViewerDecorationSupport i związanych z nią klasach (na przykład AnnotationPainter). Istotna jest wiedza, jakie dekoracje są dostępne, aby klasa SourceViewer oraz wspierająca ją klasa SourceViewerDecorationSupport zostały poprawnie skonfigurowane.
Teraz przedstawiona zostanie konfiguracja używana przez klasę TextEditor do obsługi dekoracji.
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()); }
Preferencje adnotacji służą do definiowania typów adnotacji dla wszystkich adnotacji wyświetlanych w preferencjach użytkownika. Dotyczy to adnotacji wnoszonych przez dowolny moduł dodatkowy i nie jest ograniczone do adnotacji dostarczanych przez środowisko robocze. Aby w edytorze nie były wyświetlane wszystkie typy adnotacji, należy przesłonić tę metodę i skonfigurować klasę SourceViewerDecorationSupport z tymi tylko typami adnotacji, które mają być wyświetlane.