Pohledy Cheat sheet

Pohledy Cheat sheet jsou speciální pohledy, které provádějí uživatele sérií komplexních úloh za účelem dosažení konečného výsledku. Pohled Cheat sheet lze použít například k provedení uživatele všemi kroky potřebnými k vytvoření, kompilaci a spuštění jednoduchého programu v jazyce Java. Pohledy Cheat sheet se spouštějí prostřednictvím položky nabídky Nápověda>Pohledy Cheat sheet.... Pohledy Cheat sheet lze spouštět rovněž ze stránky Intro.

Pohledy Cheat sheet se definují s použitím bodu rozšíření org.eclipse.ui.cheatsheets.cheatSheetContent. Vlastní obsah pohledu Cheat sheet se definuje v samostatném souboru, takže jej lze snadněji přeložit do jiných jazyků.

Přispívání pohledem Cheat sheet

Přispívání pohledem Cheat sheet je dokonale přímočaré. Podívejme se na pohled Cheat sheet přispívaný prostřednictvím JDT pro sestavení jednoduché aplikace Java.

<extension point="org.eclipse.ui.cheatsheets.cheatSheetContent">
	<cheatsheet
		name="%cheatsheet.helloworld.name"
		contentFile="$nl$/cheatsheets/HelloWorld.xml"
		id="org.eclipse.jdt.helloworld">
		<description>%cheatsheet.helloworld.desc</description>
	</cheatsheet>
	...
Stejně jako je tomu v případě ostatních příspěvků pracovní plochy, i pro pohled Cheat sheet lze zadat název, popis a ID. Název a popis se zobrazují, když uživatel přistupuje do seznamu prostřednictvím nabídky Nápověda>Pohledy Cheat sheet.... Kategorii pro pohled Cheat sheet může být rovněž definován, když chcete umístit několik pohledů Cheat sheet do logické skupiny. Není-li zadána žádná kategorie, pohled Cheat sheet se zobrazí v kategorii Další.

Dialogové okno Cheat sheet

Položky pohledu Cheat sheet

Skutečná manipulace s pohledy Cheat sheet se provádí v souborech s obsahem. Soubor s obsahem je soubor formátu XML, jehož název a umístění určuje atribut contentFile. Cesta souboru je relativní vzhledem k adresáři modulu plug-in. (Povšimněte si použití proměnné $nl$ v názvu adresáře, což znamená, že soubor bude umístěn v adresáři specifickém pro národní jazyk cílového prostředí.)

Samotný soubor obsahuje přehledovou informaci o pohledu Cheat sheet následovanou popisem jednotlivých kroků (tzv. položek), které provede uživatel. V nejjednodušším případě je položka pouhým podrobným popisem úkonu, který má uživatel provést. Položka však může rovněž určit akci, jež může být spuštěna na účelem provedení kroku jménem uživatele. Podívejme se na první část souboru s obsahem (HelloWorld.xml) pro Pohled Cheat sheet jazyku Java.

<?xml version="1.0" encoding="UTF-8" ?> 
<cheatsheet title="Jednoduchá aplikace Java">
	<intro
		href="/org.eclipse.ui.cheatsheets.doc/tasks/tcheatst.htm">
		<description>
Vítejte ve výukovém programu Ahoj světe pro prostředí Java.
Tento program vám pomůže vytvořit a vyzkoušet známou aplikaci "Ahoj světe". Vytvoříte projekt v prostředí Java a třídu Java, která při spuštění zobrazí v konzole nápis "Ahoj světe".
Začínáme!
		
		</description>
</intro>
	<item
		href="/org.eclipse.platform.doc.user/concepts/concepts-4.htm"
		title="Otevřít perspektivu Java">
		<action
			pluginId="org.eclipse.ui.cheatsheets"
			class="org.eclipse.ui.internal.cheatsheets.actions.OpenPerspective"
			param1="org.eclipse.jdt.ui.JavaPerspective"/>
		<description>
Vyberte Okno->Otevřít perspektivu->Java v pruhu nabídky v horní části pracovní plochy.
Tímto krokem změníte perspektivu pro nastavení pracovní plochy Eclipse pro vývoj v prostředí Java.
Můžete klepnout na tlačítko "Klepnutím provést", aby se perspektiva prostředí Java otevírala automaticky.
		
		</description>
</item>
...

Jednoduchý pohled Cheat sheet jazyku Java

V horní části pohledu Cheat sheet se zobrazuje titulek a informace části Intro. Dále následují popisy položek. První položka tohoto pohledu Cheat sheet popisuje způsob otevírání perspektivy Java. Atribut action určuje třídu, kterou lze použít pro spuštění akce jménem uživatele. Třída musí implementovat IAction. Přednost tohoto způsobu spočívá ve skutečnosti, že můžete opětovně využívat třídy akcí napsané pro příspěvky do nabídky nebo panelu nástrojů.

Třída akce může volitelně implementovat ICheatSheetAction, pokud akce používá parametry nebo pokud potřebuje informace o pohledu Cheat sheet a jeho stavu. V takovém případě bude akci předáno pole parametrů a odkaz na ICheatSheetManager, jehož prostřednictvím bude moci požadovat další informace o pohledu Cheat sheet. Veškeré nezbytné parametry lze běhové metodě akce předávat prostřednictvím atributů paramN.

Důrazně doporučujeme, aby akce vyvolané z pohledů Cheat sheet hlásily výslený úspěch/selhání, pokud spuštění akce může selhat. (Uživatel například může zrušit akci z jejího dialogového okna.) Další informace viz IAction.notifyResult(boolean).

Položky nemusejí definovat akce. Vyžaduje-li vaše položka ruční provedení uživatelem, nemusíte definovat vůbec žádnou akci. Níže uvádíme třetí krok pohledu Cheat sheet jazyku Java, který uživatele pouze seznamuje se způsobem vytvoření kódu jednoduché aplikace. Není-li zadána žádná akce, musí popis položky vyzvat uživatele, aby po dokončení úlohy stiskl příslušné tlačítko.

<item
	href="/org.eclipse.jdt.doc.user/tasks/tasks-54.htm"
	title="Přidání řádku System.out.println do hlavní metody">
	<description>
Za předpokladu, že máte svou třídu HelloWorld,
přidejte do metody "public static void main" následující příkaz:  System.out.println("Ahoj světe!"); a uložte provedenou změnu. Po dokončení stiskněte tlačítko "klepnout po dokončení".
	</description>
</item>
Další atributy určují, zda má být položka zcela přeskočena a který dokument má být spuštěn, pokud si uživatel během tohoto kroku vyžádá nápovědu. Popis veškerých atributů, které lze definovat v rámci pohledu Cheat sheet, viz dokumentaci bodu rozšíření org.eclipse.ui.cheatsheets.cheatSheetContent.
Dílčí položky

Za účelem dalšího uspořádání zobrazení položky lze definovat dílčí položky. Narozdíl od položek dílčí položky nevyžadují určité pořadí návštěvy. Dílčí položky mohou definovat rovněž akce, které pro uživatele automaticky provádějí dílčí úlohu. Akce dílčích položek se definují stejně jako akce položek.

Podmíněné výrazy a proměnné pohledu Cheat sheet

Podmíněné výrazy lze používat k definici prvků pohledu Cheat sheet, jejichž obsah či chování závisí na splnění určité podmínky. Podmínky jsou popsány v prvku condition dílčí položky s použitím libovolných řetězcových hodnot, které jsou pro každou volbu porovnávány s atributem when. Podmínky v běžném případě odkazují na proměnné pohledu Cheat sheet pomocí ${var}, kde var je název proměnné pohledu Cheat sheet. Uveďme několik jednoduchých příkladů použití podmíněných výrazů.

K výběru jedné dílčí položky ze seznamu všech dostupných dílčích položek lze použít podmíněné dílčí položky. Do pohledu Cheat sheet se vloží pouze první dílčí položka, jejíž atribut when bude shodný s atributem condition. Například:

<item ...>
	<conditional-subitem condition="${v1}">
		<subitem when="a" label="Krok pro A." />
		<subitem when="b" label="Krok pro B." />
	</conditional-subitem>
</item>
Tato položka definuje dvě možné dílčí položky, které závisejí na hodnotě proměnné v1. Je-li hodnota proměnné a, dojde k vložení první dílčí položky. Je-li hodnota proměnné b, dojde k vložení druhé dílčí položky. Pokud proměnná neobsahuje žádnou hodnotu, je rozpoznána chyba.

Podmíněné akce se podobají podmíněným dílčím položkám. Prvek perform-when určuje podmínku provedení jedné akce ze seznamu možných akcí. Podmínka se popisuje tímtéž způsobem s použitím libovolného řetězce, který často odkazuje na proměnnou. Provedena bude akce, jejíž atribut when se shoduje s podmínkou. Například:

<item ...>
	<perform-when condition="${v1}">
		<action when="a" class="com.example.actionA" pluginId-"com.example" />
		<action when="b" class="com.example.actionB" pluginId-"com.example" />
	</perform-when>
</item>
Akce k provedení bude zvolena na základě hodnoty proměnné v1. Neobsahuje-li proměnná hodnotu a ani b, bude rozpoznána chyba.
Opakované dílčí položky

Opakované dílčí položky definují dílčí položku, kterou lze rozšířit na 0, 1 nebo více podobných dílčích kroků. Dílčí kroky se přizpůsobují s použitím speciální proměnné ${this}. Tato proměnná bude nahrazena hodnotami určenými atributem values. Atribut values obsahuje řetězec hodnot, které jsou odděleny čárkami. V atributu values lze použít proměnnou, která obsahuje seznam hodnot. Například:

<item ...>
	<repeated-subitem values="${v1}">
		<subitem label="Krok ${this}" />
	</repeated-subitem>
</item>
Obsahuje-li proměnná hodnotu 1,b,tři, zobrazí se v pohledu Cheat sheet tři dílčí položky s jedinečným popisem ("Krok 1," "Krok b," "Krok tři"). Proměnnou lze použít ve štítku nebo jako hodnotu parametru akce. Během provádění akce k ní lze přistupovat rovněž z ICheatSheetManager.

Příjemci pohledu Cheat sheet

V určitých případech můžete při aktivaci pohledu Cheat sheet vyžadovat změnu jiných částí svého uživatelského rozhraní. Můžete mít například editor, který zobrazuje speciální anotace, pokud uživatele editační úlohou provádí pohled Cheat sheet. V takovém případě lze jako atribut pohledu Cheat sheet zadat příjemce. Atribut listener musí uvádět úplný název třídy Java, jež je podtřídou CheatSheetListener. Příjemci obdrží upozornění spolu s ICheatSheetEvent, pokud došlo k úpravě během aktivace pohledu Cheat sheet, jako při jeho otevření, uzavření či dokončení.

Vkládání atributů do existujícího pohledu Cheat sheet

Rozšířením org.eclipse.ui.cheatsheets.cheatSheetItemExtension lze přispívat libovolnými atributy do dříve existujícího pohledu Cheat sheet. Účelem tohoto bodu rozšíření je umožnit modulu plug-in přidávat další tlačítka, které uživateli pomohou při provádění daného kroku. Tato přídavná tlačítka se zobrazují vedle ikony nápovědy.

Chcete-li použít tento mechanizmus, můžete definovat jakýkoli libovolný atribut uvnitř definice položky v souboru XML pohledu Cheat sheet. Název atributu bude porovnán s veškerými atributy obsaženými v rozšířeních org.eclipse.ui.cheatsheets.cheatSheetItemExtension. Další informace viz dokumentaci bodu rozšíření.