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

Funkcje niedemonstrowane

Uruchamianie przykładowego edytora Java

  1. Tworzenie projektu
  2. Utwórz plik z rozszerzeniem ".jav" w nowo utworzonym projekcie. Przykładowy edytor Java zostanie otworzony automatycznie.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. Wybierz jedną pozycję w schemacie treści. Odpowiadające jej wiersze są zaznaczane niebieskim paskiem na lewej pionowej linijce edytora.
  8. 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.
  9. 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.
  10. 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.
  11. 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.
  12. 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.
  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. 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: