Przykład - narzędzie Readme

Wprowadzenie

Edytor Readme pokazuje, w jaki sposób definiować własne punkty rozszerzenia na użytek innych modułów dodatkowych. Pokazuje również, w jaki sposób tworzyć rozszerzenia dla pozycji menu podręcznego zasobów, kreatorów nowych zasobów, edytorów plików z rozszerzeniem (.readme), niestandardowych widoków oraz stron właściwości.

Wykonanie przykładu

Aby rozpocząć korzystanie z tego przykładu, należy utworzyć plik z rozszerzeniem .readme przy użyciu kreatora tworzenia plików lub kreatora tworzenia przykładów. Dodatkowy widok udostępniony w tym przykładzie można wyświetlić, wybierając opcję Okna > Pokaż widok > Inne i rozwijając sekcję Readme. Akcję widoku można wyświetlić, klikając ikonę readme w widoku nawigatora.

Tworzenie nowego pliku readme

Należy utworzyć nowy plik z rozszerzeniem .readme. W tym celu z menu Plik należy wybrać opcję Nowy, a następnie z podmenu opcję Inne.  W kreatorze należy kliknąć pozycję Proste, a następnie wybrać pozycję Plik z listy po lewej stronie. Po kliknięciu przycisku Dalej trzeba podać nazwę pliku (ma mieć rozszerzenie .readme) oraz folder, w którym plik ma być przechowywany.

Kreatory tworzenia przykładów

Z menu Plik należy wybrać opcję Nowy, a z podmenu opcję Przykład. Następnie należy wybrać opcję Kreatory tworzenia przykładów i opcję Plik readme. Kliknij przycisk Dalej. Wybierz folder, w którym ma zostać utworzony plik. Należy wpisać nazwę pliku z rozszerzeniem .readme i kliknąć przycisk Zakończ.

Akcja rozszerzenia widoku Readme

W widoku nawigatora należy wybrać plik z rozszerzeniem .readme. Jeśli nie ma pliku z takim rozszerzeniem, należy go utworzyć. Na lokalnym pasku narzędzi widoku nawigatora widoczny będzie przycisk, którego podpowiedź zawiera treść Uruchom rozszerzenie widoku Readme.  Należy kliknąć ten przycisk. Wywołane zostanie okno dialogowe z komunikatem o wykonaniu akcji widoku.

Menu podręczne

W widoku nawigatora należy wybrać plik z rozszerzeniem .readme. Jeśli nie ma pliku z takim rozszerzeniem, należy go utworzyć. Plik należy wybrać w celu wywołania menu podręcznego. W menu podręcznym znajduje się pozycja o nazwie Pokaż akcję Readme. Należy wybrać tę pozycję menu, aby otworzyć okno dialogowe z komunikatem o wykonaniu akcji menu podręcznego.

Strona preferencji

Z menu Okno należy wybrać opcję Preferencje. Należy kliknąć stronę o nazwie Przykład Readme. Wyświetlony zostanie przykład strony preferencji.

Strona właściwości

W widoku nawigatora należy wybrać plik z rozszerzeniem .readme. Jeśli nie ma pliku z takim rozszerzeniem, należy go utworzyć. Plik należy wybrać w celu wywołania menu podręcznego, a następnie należy wybrać opcję Właściwości. Aby wyświetlić przykład strony właściwości, należy kliknąć stronę o nazwie Narzędzie Readme.

Edytor plików readme

Edytor plików readme jest domyślnym edytorem plików typu *.readme. Należy utworzyć plik z rozszerzeniem .readme i otworzyć go, klikając dwukrotnie, lub przez przywołanie menu podręcznego, wybranie opcji Otwórz za pomocą, a następnie wybranie z podmenu opcji Edytor plików readme.  Edytor ma ikonę z ołówkiem. Jest to edytor, którego narzędzie Readme używa domyślnie dla plików typu *.readme.

Akcje edytora Readme

Ta opcja prezentuje przykład akcji, które mają zastosowanie tylko do konkretnego edytora. Gdy edytor plików readme jest aktywny, widoczne są cztery dodatkowe przyciski paska narzędzi - Uruchom rozszerzenie edytora Readme, Akcja 1 edytora Readme, Akcja 2 edytora Readme, Akcja 3 edytora Readme.

Gdy edytor plików readme jest aktywny, wyświetlane jest również menu rozwijane o nazwie Readme. Zawiera ono opisane wcześniej akcje: Akcja 1 edytora Readme, Akcja 2 edytora Readme, Akcja 3 edytora Readme.

Widok sekcji readme

Aby wyświetlić widok sekcji readme, z menu Okna należy wybrać opcję Pokaż widok, a następnie z podmenu wybrać opcję Inny. Należy rozwinąć pozycję Readme i wybrać opcję Sekcje readme. Spowoduje to wyświetlenie listy sekcji z bieżącego pliku *.readme wybranego w widoku nawigatora.  Strukturę pliku *.readme można również wyświetlić w widoku Schemat.

Plik z rozszerzeniem .readme może zostać rozbity na sekcje, jeśli każda sekcja rozpoczyna się numerem.  Jeśli na przykład poniższy tekst zostałby wprowadzony w edytorze plików readme, to narzędzie Readme wykryłoby dwie sekcje.  Aby zobaczyć, w jaki sposób wykrywane są sekcje w narzędziu Readme, wystarczy wprowadzić dowolny tekst w edytorze plików readme i zapisać plik, naciskając skrót CTRL-S lub wybierając opcję Plik->Zapisz. Następnie należy otworzyć widok sekcji readme i wybrać ten plik .readme w widoku nawigatora.

Przykładowy tekst:

99.1 To jest pierwsza sekcja
To jest dowolny tekst pierwszej sekcji.

99.1.1 To jest podsekcja
To jest dowolny tekst podsekcji.

Przeciąganie i upuszczanie

Sposób działania metody przeciągania i upuszczania można zaobserwować, wybierając sekcję w widoku Schemat i przeciągając wybór do górnej części pliku tekstowego. Treść danej sekcji zostanie dopisana do pliku.

Współtworzenie pomocy

Przykład narzędzia Readme prezentuje również sposób użycia i implementowania pomocy kontekstowej dla wszystkich udostępnianych rozszerzeń - widoku, różnych akcji oraz strony kreatora. Aby uzyskać pomoc kontekstową dotyczącą akcji, należy zatrzymać wskaźnik myszy nad pozycją menu (nie wybierając jej), a następnie nacisnąć klawisz F1. Pomoc kontekstową (F1) można również uzyskać w widoku sekcji readme oraz na stronie kreatorów tworzenia przykładów (kreator Nowy).
 

Szczegóły

Przykład narzędzia Readme deklaruje jeden punkt rozszerzenia oraz udostępnia wiele rozszerzeń.  Udostępniane rozszerzenia pomagają w szerokim zakresie zrozumieć działanie środowiska roboczego, ponieważ korzystają z wielu interesujących punktów rozszerzeń zadeklarowanych przez środowisko robocze.  W tym przykładzie udostępniono następujące rozszerzenia: widoki oraz akcje widoków, strony preferencji, kreatorzy, edytory oraz akcje edytorów, menu podręczne, zestawy akcji, elementy wnoszone pomocy, konteksty pomocy oraz akcje upuszczania.

Ten przykład udostępnia również punkt rozszerzenia zadeklarowany w module dodatkowym. Każdy moduł dodatkowy korzystający z rozszerzenia org.eclipse.ui.examples.readmetool.sectionParser zdefiniowanego w tym przykładzie wymaga klasy IReadmeFileParser. Klasa DefaultSectionParser jest przykładową implementacją klasy IReadmeFileParser.

Klasa ReadmeEditor implementuje interfejs IEditorPart i jest zdefiniowana jako edytor plików z rozszerzeniem .readme w pliku plugin.xml przy użyciu punktu rozszerzenia org.eclipse.ui.editors. Klasa ReadmeSectionsView implementuje interfejs IViewPart i jest zdefiniowana jako widok przy użyciu punktu rozszerzenia org.eclipse.ui.views. Ten punkt rozszerzenia definiuje również kategorię dla widoku używaną przy wybieraniu widoku.

W tym przykładzie zdefiniowane zostały dwa typy ustawień preferencji - preferencje środowiska roboczego oraz właściwości zasobów. Preferencja środowiska roboczego jest zdefiniowana w klasie ReadmePreferencePage, która implementuje interfejs IWorkbenchPreferencePage, dzięki czemu jest dodawana do okna dialogowego Okna->Preferencje. Klasa ta jest zdefiniowana w punkcie rozszerzenia org.eclipse.ui.preferencePages w pliku plugin.xml. Strony ReadmeFilePropertyPage i ReadmeFilePropertyPage2 to dwie strony właściwości zasobów, z których każda implementuje interfejs IWorkbenchPropertyPage. Obie są zdefiniowane w taki sposób, aby mogły być wywoływane w typie IFile przez znacznik objectClass w pliku plugin.xml w punkcie rozszerzenia org.eclipse.ui.propertyPages.

Klasa ReadmeCreationWizard implementuje interfejs INewWizard i jest zdefiniowana w punkcie rozszerzenia org.eclipse.ui.newWizards w pliku plugin.xml. Ten punkt rozszerzenia definiuje również kategorię, wyświetlaną przez kreatora po wybraniu przez użytkownika opcji Plik->Nowy->Przykład.

Do tego przykładu zostało dodanych kilka szkieletów akcji. Zestaw akcji deklaruje przy użyciu punktu rozszerzenia org.eclipse.ui.actionSets menu oznaczone etykietą Edytor plików readme, które ma być uwzględnione na pasku menu okna środowiska roboczego. Ten zestaw definiuje również przy użyciu znaczników toolbarPath i menubarPath akcję dla paska narzędzi oraz paska menu środowiska roboczego. Do zaimplementowania tej akcji używana jest klasa WindowActionDelegate implementująca interfejs IWorkbenchWindowActionDelegate. Akcja dla menu podręcznego jest zdefiniowana jako obiekt typu objectContribution przez klasę PopupMenuActionDelegate w punkcie rozszerzenia org.eclipse.ui.popupMenus. Klasa PopupMenuActionDelegate implementuje interfejs IObjectActionDelegate i używa dostarczonego interfejsu IWorkbenchPart do otwierania okien dialogowych z komunikatami. Akcja widoku ViewActionDelegate jest zdefiniowana w punkcie rozszerzenia org.eclipse.ui.viewActions i implementuje interfejs IViewActionDelegate. Widok, w którym jest ona wyświetlana, jest zdefiniowany przez znacznik targetID, który w tym przykładzie przyjmuje wartość org.eclipse.ui.views.ResourceNavigator. Akcja edytora jest zdefiniowana przez klasę EditorActionDelegate, która implementuje interfejs IEditorActionDelegate i jest dodana przy użyciu punktu rozszerzenia org.eclipse.ui.editorActions. Edytor, do którego jest zastosowana, zdefiniowany jest przez znacznik targetID, który w tym przykładzie jest zdefiniowany w klasie org.eclipse.ui.examples.readmetool.ReadmeEditor.

Klasa ReadmeDropActionDelegate implementuje interfejs IDropDelegate. Obiekty IDropDelegate są informowane o każdej akcji upuszczania mającej miejsce w środowisku roboczym. Punktem rozszerzenia dla tej akcji jest org.eclipse.ui.dropActions.