Příklad - Nástroj README

Úvod

Editor README ukazuje, jak si nadefinovat své vlastní body rozšíření pro použití u dalších modulů plug-in. Ukazuje také, jak si vytvořit rozšíření pro položky rozevíracích nabídek prostředků, průvodce novými prostředky, editory souborů s určitou příponou (.readme), vlastní pohled a stránky vlastností.

Spuštění příkladu

Chcete-li začít používat tento příklad, vytvořte soubor s příponou .readme s použitím průvodce vytvářením souborů nebo průvodce vytvářením příkladů. Další  pohled v tomto příkladu si můžete zobrazit výběrem položek Okno > Zobrazit pohled > Jiné a rozbalením oddílu README. Akci zobrazení si můžeme prohlédnout, pokud klepneme na ikonu README v pohledu Navigátor.

Vytvoření nového souboru README

Vytvořte nový soubor s příponou .readme.  Z nabídky Soubor vyberte Nový a z podnabídky potom Jiný...  V průvodci klepněte na Jednoduchý, poté vyberte položku Soubor v seznamu nalevo.  Klepněte na Další a doplňte název souboru (ujistěte se, že je přípona .readme) a složku, která má soubor obsahovat.

Průvodci vytvářením příkladů

Z nabídky Soubor vyberte položku Nový a z podnabídky poté Příklad...  Nyní zvolte položku Průvodci vytvářením příkladů. Vyberte Soubor Readme. Klepněte na Další. Vyberte složku, ve které chcete soubor vytvořit. Zadejte název souboru s příponou .readme. Klepněte na Dokončit.

Akce rozšíření pohledu README

V pohledu Navigátor vyberte soubor s příponou .readme. Pokud zde takový soubor není, vytvořte jej. V lokálním panelu nástrojů uvidíte tlačítko, které při přejetí myší zobrazí text Spustit rozšíření pohledu README.  Klepněte na toto tlačítko.  Objeví se dialogové okno s textem Akce pohledu byla provedena.

Rozevírací nabídky

V pohledu Navigátor vyberte soubor s příponou .readme.  pokud zde takový soubor není, vytvořte jej.  Vyberte tento soubor, aby se zobrazila rozevírací nabídka.  Všimněte si, že se zde nachází položka s textem Zobrazit akci README v rozevírací nabídce.  Když tuto položku vyberete, otevře se dialogové okno s textem Akce rozevírací nabídky byla provedena.

Stránka předvoleb

Z nabídky Okno vyberte Předvolby.  Klepněte na stránku s názvem Příklad README.  Tím otevřete příklad stránky předvoleb.

Stránka vlastností

V pohledu Navigátor vyberte soubor s příponou .readme.  pokud zde takový soubor není, vytvořte jej.  Vyberte tento soubor, aby se zobrazila rozevírací nabídka, poté vyberte položku Vlastnosti.  Klepnutím na stránku s názvem Nástroj README si zobrazíte příklad stránky vlastností.

Editor souborů README

Editor souborů README je výchozím editorem pro soubory typu *.readme.  Vytvořte soubor s příponou .readme a poklepáním jej otevřete, případně vyvolejte rozevírací nabídku,  vyberte položku Otevřít pomocí a poté položku Editor souborů README z podnabídky.  Všimněte si, že editor má ikonu s obrázkem tužky.  Jedná se o editor, který je nástrojem README používán jako výchozí editor pro soubory typu *.readme.

Akce editoru README

Tato položka zobrazí příklady akcí, které jsou použitelné pouze pro konkrétní editor.  Když má editor souborů README fokus, všimněte si čtyř dalších tlačítek - Spustit rozšíření pohledu README, Akce editoru README 1, Akce editoru README 2, Akce editoru README 3.

Když má editor souborů README fokus, zobrazí se rozevírací nabídka s názvem README.  Tato nabídka obsahuje již dříve popsané akce: Akce editoru README 1, Akce editoru README 2, Akce editoru README 3.

Pohled Oddíly README

Chcete-li zobrazit pohled Oddíly README, vyberte z nabídky Okno položku Pohled a poté z podnabídky Jiné...  Rozbalte položku README a pak vyberte Oddíly README.  Tím si zobrazíte seznam oddílů v aktuálním souboru *.readme, je-li tento soubor .readme zvolen v pohledu Navigátor.  V pohledu Osnova můžete také vidět strukturu souboru *.readme.

Soubor s příponou .readme můžeme rozdělit do jednotlivých oddílů, z nichž každý začíná číslem.  Pokud by byl například následující text zadán do editoru souborů README, nástroj README by objevil 2 oddíly.  Chcete-li vidět, jakým způsobem nástroj README detekuje, oddíly, zadejte do editoru souborů README libovolný text a uložte soubor buď pomocí klávesové zkratky CTRL-S, nebo výběrem položek  Soubor->Uložit.Otevřete pohled Oddíly README a vyberte soubor .readme v pohledu Navigátor.

Ukázkový text:

99.1 Toto je můj první oddíl
Toto je text v mém prvním oddílu.

99.1.1 Toto je pododdíl.
Toto je text v mém pododdílu.

Přetažení

Funkčnost přetažení se nejlépe projeví, když vyberete oddíl v pohledu Osnova a přetáhnete tento výběr nad horní okraj textového souboru. Obsah výběru bude připojen k danému souboru.

Příspěvek do nápovědy

Nástroj README také ukazuje možnosti použití a implementace kontextové nápovědy u všech rozšíření, která jsou k dispozici - u pohledu, různých akcí a stránky s průvodcem.  Chcete-li získat kontextovou nápovědu ke konkrétní akci, přejeďte myší nad danou položku, ale nevybírejte ji a poté stiskněte klávesu F1.  Kontextovou nápovědu (F1) můžete obdržet i k pohledu Oddíly README a ke stránce Průvodci vytvářením (v Novém průvodci).
 

Podrobnosti

Příklad nástroje README deklaruje jeden bod rozšíření a nabízí celou řadu rozšíření.   Tato rozšíření poměrně vyčerpávajícím způsobem vysvětlují, jak funguje modul Workbench, protože se používá mnoho velmi zajímavých bodů rozšíření deklarovaných v modulu Workbench.  Mezi rozšíření, která jsou součástí tohoto příkladu, patří pohledy a akce pohledů, stránky předvoleb, stránky vlastností, průvodci, editory a akce editorů, rozevírací nabídky, sady akcí, příspěvky do nápovědy, kontexty nápovědy a akce při puštění.

Tento příklad také dodává bod rozšíření deklarovaný v modulu plug-in. Pro každý modul plug-in, který používá rozšíření org.eclipse.ui.examples.readmetool.sectionParser definované tímto příkladem, je nezbytná třída IReadmeFileParser. Třída DefaultSectionParser je ukázkovou implementací třídy IReadmeFileParser.

Třída ReadmeEditor implementuje IEditorPart a je definována jako editor souborů s příponou .readme v souboru plugin.xml, která používá bod rozšíření org.eclipse.ui.editors. Třída ReadmeSectionsView implementuje IViewPart a je definována jako pohled, který používá bod rozšíření org.eclipse.ui.views. Tento bod rozšíření také definuje kategorii pro pohled, která se bude používat při výběru pohledu.

V tomto příkladu jsou definovány dva typy nastavení předvoleb - předvolby modulu Workbench a vlastnosti prostředků. Předvolby modulu Workbench jsou definovány ve třídě ReadmePreferencePage, která implementuje třídu IWorkbenchPreferencePage a přidává ji do dialogového okna Okno->Předvolby. Tato třída je definována v bodu rozšíření org.eclipse.ui.preferencePages v souboru plugin.xml. Dvě stránky vlastností prostředků - ReadmeFilePropertyPage a ReadmeFilePropertyPage2 - implementují třídu IWorkbenchPropertyPage. Obě se dle definice vyvolávají u typu IFile type pomocí značky objectClass v souboru plugin.xml v bodu rozšíření org.eclipse.ui.propertyPages.

Třída ReadmeCreationWizard implementuje třídu INewWizard a je definována v bodu rozšíření org.eclipse.ui.newWizards v souboru plugin.xml. Tento bod rozšíření také definuje kategorii, která se zobrazí v průvodci, když uživatel vybere položky Soubor->Nový->Příklad....

Do tohoto příkladu bylo přidáno několik zástupců vzdáleného objektu (stub) akcí. Sada akcí deklaruje nabídku s názvem Editor souborů README, která bude součástí pruhu nabídky modulu Workbench za použití bodu rozšíření org.eclipse.ui.actionSets. Definuje také akci pro pruh nabídky a modul Workbench, a to s použitím značek toolbarPath a menubarPath. Používá třídu WindowActionDelegate, která implementuje třídu IWorkbenchWindowActionDelegate pro danou akci. Akce pro rozevírací nabídku je definována jako objectContribution třídou PopupMenuActionDelegate v  bodu rozšíření org.eclipse.ui.popupMenus. PopupMenuActionDelegate implementuje IObjectActionDelegate a používá třídu IWorkbenchPart, která otevírá dialogové okno se zprávou. Akce pohledu ViewActionDelegate je definována v bodu rozšíření org.eclipse.ui.viewActions a implementuje třídu IViewActionDelegate. Pohled, ve kterém se objeví, je definován značkou targetID, která je v tomto příkladu org.eclipse.ui.views.ResourceNavigator. Akce editoru je definována třídou EditorActionDelegate, která implementuje IEditorActionDelegate a přidává se pomocí bodu rozšíření org.eclipse.ui.editorActions. Editor, ve kterém se používá, je definován značkou targetID, která je v tomto příkladu definována v bodu rozšíření org.eclipse.ui.examples.readmetool.ReadmeEditor.

Třída ReadmeDropActionDelegate implementuje IDropDelegate. Třídy IDropDelegates jsou informovány o všech akcích při puštění, ke kterým dochází v modulu Workbench. Bod rozšíření pro tuto akci je org.eclipse.ui.dropActions.