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ę we wtyczce org.eclipse.ui.examples.javaeditor. Aby przeglądać kod, zaleca się zaimportowanie tej wtyczki do obszaru roboczego.

Funkcje demonstrowane w przykładowym edytorze

Opcje 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 otwarty 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 wielowierszowy 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 podpowiedzi 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 podświetlenia w edytorze zostanie automatycznie zwiększony 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 czynności są zwykle konieczne do utworzenia niestandardowego edytora tekstu.
  1. Utwórz dostawcę dokumentów. Dostawca dokumentów (patrz IDocumentProvider) tworzy dokumenty (patrz IDocument) zawierające tekstowe odwzorowanie elementów wprowadzanych do edytora, a także zarządza tymi dokumentami. 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. Patrz też klasa FileDocumentProvider w przykładowym edytorze Java.
  2. Utwórz partycjoner 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. Patrz też klasa 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 wtyczek przeglądarki kodu źródłowego mają być udostępnione. Wśród obsługiwanych wtyczek 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 podświetlania składni.
  4. Utwórz dla wszystkich wtyczek 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. Patrz też klasa JavaDamagerRepairer i JavaDocDamagerRepairer w przykładowym edytorze Java.
  5. Zbuduj konfigurację przeglądarki kodu źródłowego, korzystając z wcześniej utworzonych wtyczek i rozszerzeń. Patrz też klasa JavaSourceViewerConfiguration w przykładowym edytorze Java.
  6. Dostosuj klasy TextEditor i AbstractTextEditor, uwzględniając w nich utworzony partycjoner 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. Patrz też klasa 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. Patrz też klasa JavaActionContributor w przykładowym edytorze Java.
  8. Rozszerz plik konfiguracyjny XML wtyczki edytora, aby edytor rejestrował zdefiniowany wcześniej punkt rozszerzenia dla określonego zestawu rozszerzeń nazw plików. Skonfiguruj również kontrybutor paska działań w pliku XML. Patrz też plik plugin.xml tego przykładu.

Organizacja kodu w przykładzie

Kod przykładowego edytora Java jest zorganizowany w cztery pakiety: