Przykład - edytor Java
Wprowadzenie
Przykład edytora Java demonstruje standardowe elementy dostępne dla niestandardowych edytorów tekstu. Pokazuje również, jak zarejestrować edytor dla rozszerzenia pliku (w tym przypadku .jav) i zdefiniować niestandardowego dostawcę dokumentów do używania z tym edytorem. Poniższy przykład pełni jedynie funkcje demonstracyjne. Obsługę edytowania kodu Java udostępnia środowisko Eclipse Java Tooling.
Kod dla tego przykładu znajduje się w module dodatkowym org.eclipse.ui.examples.javaeditor
.
Aby przeglądać kod, zaleca się zaimportowanie tego modułu dodatkowego do obszaru roboczego.
Funkcje demonstrowane w przykładowym edytorze
-
Wyróżnianie składni
-
Asystent treści rozróżniający typ treści (dokumentacja Javadoc i kod Java)
-
Komunikacja między widokiem schematu a edytorem, tzn. wybór w widoku schematu powoduje wyróżnienie zakresu w edytorze
-
Dwa różne tryby prezentacji
-
Zaznaczanie zakresu wyróżnienia za pomocą widocznego wskaźnika zakresu
-
Ograniczanie edytora do pokazywania wyłącznie tekstu w wyróżnionym zakresie (np. pokazanie pojedynczej metody klasy Java)
-
Obsługa znaczników
-
Współużytkowanie dokumentów
Funkcje niedemonstrowane
-
Formatowanie treści
-
Dynamiczne rozliczanie strony schematu treści
Uruchamianie przykładowego edytora Java
-
Tworzenie projektu
-
Utwórz plik z rozszerzeniem ".jav" w nowo utworzonym projekcie.
Przykładowy edytor Java zostanie otworzony automatycznie.
-
Wstaw kod Java. Kod Java jest dynamicznie kolorowany. Przykładowy edytor przedstawia następujące elementy języka w różnych kolorach: wielowierszowe komentarze, jednowierszowe komentarze, słowa zastrzeżone języka Java, stałe łańcuchowe i znakowe, normalny kod Java oraz wielowierszowe komentarze następujące po wytycznych dokumentacji Javadoc. Wewnątrz komentarzy dokumentacji Javadoc słowa kluczowe dokumentacji Javadoc (zielone) i znaczniki HTML (szare) są oznaczone różnymi kolorami.
-
Otwórz nowy wieloliniowy komentarz Java, wstawiając znaki "/*" poza komentarzem Java.
Tekst między wstawionymi znakami "/*" i pierwszym wystąpieniem znaków "*/" lub końcem tekstu zmieni kolor na czerwony. Dodaj kolejny znak "*". Czerwony zakres zmieni kolor na czarny, ponieważ zwykły komentarz wielowierszowy będzie teraz traktowany jako zawierający dokumentację Javadoc. Wywołaj asystenta kodu za pomocą kombinacji klawiszy CTRL+SPACJA.
Zadaniem asystenta kodu jest wspomaganie użytkownika przy pisaniu kodu.
Po wywołaniu asystent treści powinien wyświetlić listę wszystkich możliwych poprawnych zakończeń w miejscu wywołania. Wewnątrz dokumentacji Javadoc przykładowy edytor zawsze proponuje wszystkie słowa kluczowe dokumentacji Javadoc.
-
Poza komentarzem Java wywołaj wskazówkę dotyczącą treści za pomocą kombinacji klawiszy CTRL+SHIFT+SPACJA. Wyświetlonych zostanie 5 propozycji. Wybierz jedną i naciśnij klawisz ENTER. Małe, przestawne, czerwone okno z wybraną propozycją zostanie wyświetlone nad bieżącym wierszem.
Wskazówki dotyczące treści mają za zadanie umożliwić użytkownikowi wyrażenie intencji (np. wprowadzenia wywołania metody), a następnie wyświetlenie informacji kontekstowych, które pomogą użytkownikowi wykonać to zadanie. W przykładowym edytorze za propozycje uważanych jest pięć poprawnych znaków w otoczeniu początkowego miejsca wywołania. Gdy wskazówka dotycząca treści jest widoczna, wywołaj asystenta treści za pomocą kombinacji klawiszy CTRL+SPACJA. Wywołany w tym momencie asystent treści powinien pomóc użytkownikowi przeprowadzić zamierzone działanie, ponieważ odpowiednia pozycja jest wciąż widoczna we wskazówce dotyczącej treści. W ramach zwykłego kodu Java przykładowy edytor zawsze proponuje wszystkie słowa kluczowe Java.
-
Zapisz kod Java. Zapisanie powoduje aktualizację schematu treści. Schemat treści zawiera dziesięć pozycji odpowiadających dziesięciu segmentom kodu Java o równej wielkości w edytorze. Ten styl schematu treści został wybrany, aby pokazać, że semantyka zakresów wyróżniania może być zdefiniowana arbitralnie. Więcej informacji o tym znajduje się w następnych krokach.
-
Wybierz jedną pozycję w schemacie treści. Odpowiadające jej wiersze są zaznaczane niebieskim paskiem na lewej pionowej linijce edytora.
-
Teraz przełącz się na tryb prezentacji segmentowej edytora Java. W tym celu upewnij się, że edytor jest aktywny, i naciśnij przycisk na pasku narzędzi pulpitu, którego tekst pomocy to "Włącz/wyłącz przeglądarkę kodu źródłowego z podziałem na segmenty".
Ta funkcja jest używana dla widoków pojedynczej metody i podobnych funkcji.
-
Wybierz inną pozycję w schemacie treści. Teraz edytor pokazuje jedynie wybrany segment. Aby wyświetlić ponownie pełen kod Java, usuń zaznaczenie pozycji w schemacie treści.
-
Wybierz pozycję w schemacie treści, wybierz część widocznego tekstu i dodaj czynności dla wyboru. Czynność zostanie wyświetlona na liście czynności.
Zmodyfikuj widoczny kod. Wybierz poprzednio utworzoną czynność z listy czynności i naciśnij przycisk Idź do pliku. Czynność zostanie wybrana w widocznym obszarze, poprawnie uwzględniając wprowadzone wcześniej modyfikacje.
-
Wybierz inną pozycję w schemacie treści. Wyświetl poprzednio dodaną czynność z poziomu listy czynności. Zakres wyróżnienia w edytorze zostanie automatycznie zwiększany w celu objęcia zakresu wyświetlonej czynności.
-
Otwórz nowy obszar roboczy. W nowym obszarze roboczym otwórz edytor Java dla tego samego pliku, co w pierwotnym obszarze roboczym. Zmodyfikuj treść w edytorze. Przełącz się do pierwotnego obszaru roboczego. W edytorze będą widoczne zmiany wprowadzone w drugim obszarze roboczym. Dwa edytory pokazujące ten sam plik są połączone.
Zasady tworzenia niestandardowych edytorów tekstu
Poniższe kroki są zwykle konieczne do utworzenia niestandardowego edytora tekstu.
-
Utwórz dostawcę dokumentu. Dostawca dokumentów (patrz IDocumentProvider) tworzy i zarządza dokumentami (patrz IDocument) zawierającymi tekstowe odwzorowanie elementów wprowadzanych do edytora. Istotne jest określenie, jak powinno być wykonane przekształcanie elementu w jego tekstową reprezentację, oraz czy dostawca dokumentów ma być współużytkowany przez wiele edytorów, czy też nie. Zobacz też klasę FileDocumentProvider w przykładowym edytorze Java.
-
Utwórz partycjonera dokumentu. Partycjoner dokumentu (patrz IDocumentPartitioner) dzieli dokument na rozłączne regiony. Partycjoner przypisuje każdemu regionowi typ treści z zestawu zdefiniowanych wcześniej typów treści partycjonera. Po każdej zmianie dokumentu partycjonowanie musi być aktualizowane. Zobacz też klasę JavaPartitioner w przykładowym edytorze Java. Klasa JavaPartitioner określa regiony reprezentujące komentarze javadoc, komentarze wielowierszowe i wszystkie pozostałe. Należy zagwarantować, że dostawca dokumentów jest ustawiony dla każdego dokumentu utworzonego przez dostawcę dokumentów.
-
Określ, które z modułów dodatkowych przeglądarki kodu źródłowego mają być udostępnione. Wśród obsługiwanych modułów dodatkowych są strategie automatycznego wcinania, strategie dwukrotnego kliknięcia, formater treści i komponent uzgadniający prezentację tekstu. Dalszy opis będzie ograniczony do komponentu uzgadniającego prezentację tekstu (patrz IPresentationReconciler).
W przykładowym edytorze Java komponent uzgadniający prezentację tekstu został użyty do zaimplementowania funkcji wyróżniania składni.
-
Utwórz dla wszystkich modułów dodatkowych przeglądarki kodu źródłowego odpowiednie rozszerzenia dla każdego obsługiwanego typu treści. Jak pokazano wyżej, partycjoner dokumentów określa obsługiwane typy treści. Domyślna implementacja IPresentationReconciler obsługuje rozszerzenia IPresentationDamagers i IPresentationRepairers.
Te rozszerzenia są uznawane za charakterystyczne dla konkretnego typu treści. Dlatego dla edytora niestandardowego użytkownik musi najpierw określić obsługiwane typy treści. Regiony typu będącego elementem wybranego podzbioru będą np. wyróżniane w składni. Dla każdego z tych typów muszą być zaimplementowane rozszerzenia. Zobacz też klasy JavaDamagerRepairer i JavaDocDamagerRepairer w przykładowym edytorze Java.
-
Zbuduj konfigurację przeglądarki kodu źródłowego, korzystając z wcześniej utworzonych modułów dodatkowych i rozszerzeń. Zobacz też klasę JavaSourceViewerConfiguration w przykładowym edytorze Java.
-
Dostosuj klasy TextEditor i AbstractTextEditor, uwzględniając w nich utworzonego partycjonera dokumentów i konfigurację przeglądarki kodu źródłowego. Dodaj lub zastąp akcje i dostosuj budowę menu kontekstowego edytora. W rzeczywistej wersji dostosowanie musi zostać przeprowadzone za pomocą podklasy. Zobacz też klasę JavaEditor w przykładowym edytorze Java.
-
Skonfiguruj odpowiedniego dostawcę paska działań, który dodaje akcje edytora do paska narzędzi pulpitu i menu. Zobacz też klasę JavaActionContributor w przykładowym edytorze Java.
-
Rozszerz plik konfiguracyjny XML modułu dodatkowego edytora, aby edytor rejestrował zdefiniowany wcześniej punkt rozszerzenia dla określonego zestawu rozszerzeń nazw plików.
Skonfiguruj również dostarczyciela paska akcji w pliku XML.
Zobacz też plik plugin.xml tego przykładu.
Organizacja kodu w przykładzie
Kod przykładowego edytora Java jest zorganizowany w cztery pakiety:
-
org.eclipse.ui.examples.javaeditor
zawiera wszystkie klasy charakterystyczne dla edytora.
-
org.eclipse.ui.examples.javaeditor.java
zawiera wszystkie moduły dodatkowe przeglądarki Java, takie jak JavaDamagerRepairer oraz partycjoner dokumentów.
-
org.eclipse.ui.examples.javaeditor.javadoc
zawiera wszystkie moduły dodatkowe przeglądarki Javadoc, takie ja JavaDocDamagerRepairer.
org.eclipse.ui.examples.javaeditor.util
zawiera gotowe do użycia klasy współużytkowane przez pozostałe trzy pakiety.