Verze 3.0
Tento dokument popisuje strukturu souboru s obsahem Cheat sheet jako sérii DTD fragmentů (strojově čitelné schéma XML).
cheatsheet
<!ELEMENT cheatsheet (intro, item+)> <!ATTLIST cheatsheet title CDATA #REQUIRED >
Prvek <cheatsheet> definuje tělo souboru s obsahem cheat sheet. Atributy <cheatsheet> jsou následující:
intro
<!ELEMENT intro (description)> <!ATTLIST intro contextId CDATA #IMPLIED href CDATA #IMPLIED >
Prvek <intro> se používá k popisu úvodu Cheat sheet, který má být zobrazen. Podřízený prvek <description> obsahuje tělo úvodu. Atributy <intro> jsou následující:
description
<!ELEMENT description EMPTY> <!ATTLIST description >
Prvek <description> obsahuje popis Cheat sheet nebo popis prvku Cheat sheet. Popis sestává z textu prokládaného jednoduchými formátovacími značkami. Cheat sheet automaticky formátuje a uspořádává text, aby se zobrazil v uživatelském rozhraní v přijatelné podobě. V rámci textu bude text ohraničený vyváženými značkami <b>...</b> zobrazen tučným písmem a prvek <br/> způsobí zalomení řádku. To jsou v současné době jediné podporované značky (v budoucnosti mohou být nicméně přidány další). Určité znaky v textu mají zvláštní význam pro analyzátory XML; zejména chcete-li napsat "<", ">", "&", "'" a """ (uvozovka), napište namísto toho "<", ">", "&", "'" a """ v uvedeném pořadí. Neviditelný znak (mezery a zalomení řádku) je považován za oddělovač slov; sousedící mezery a zalomení řádků jsou považovány za jednu jednotku a zobrazovány jako jedna mezera nebo zalomení řádku. Neviditelný znak bezprostředně po značkách <description> a <br/> je ignorován stejně jako neviditelný znak bezprostředně před značkou </description>.
item
<!ELEMENT item (description ([action|perform-when] | (subitem|repeated-subitem|conditional-subitem)*))> <!ATTLIST item title CDATA #REQUIRED skip ("true" | "false") "false" contextId CDATA #IMPLIED href CDATA #IMPLIED >
Každý prvek <item> popisuje jeden krok na nejvyšší úrovni v Cheat sheet. Atribut <item> je buď jednoduchý, nebo složený. Atributy <item> jsou následující:
org.eclipse.ui.cheatsheets.cheatSheetItemExtension umožňuje, aby byly v uživatelském rozhraní zobrazeny další uživatelské obslužné prvky pro položku. Příspěvky do tohoto bodu rozšíření deklarují názvy dalších, na řetězci založených atributů, které se mohou objevit v prvcích <item>.
Jednoduché položky mají popis a volitelnou akci. V typické prezentaci jsou uživateli zobrazovány titulky položek Cheat sheet po většinu času. Popis položky je zobrazen pouze během provádění daného kroku. Přítomnost prvku <action> (nebo <perform-when>) je obvykle spojena s tlačítkem, jehož stisknutím může uživatel provést akci daného kroku. Pokud není žádná akce nabízena, musí uživatel provést krok ručně a poté zřetelně ukázat, že byl daný krok dokončen.
Složené kroky se dělí na dílčí kroky, jak jsou specifikovány dílčími prvky <subitem>. Na rozdíl od položek, u kterých musí uživatel dodržovat přesné pořadí, mohou být dílčí položky dané položky prováděny v libovolném pořadí. U všech dílčích položek v rámci položky musí být proveden pokus o jejich provedení (nebo musí být přeskočeny), než je možné přejít na další položku. (Což znamená, že akce, které musí být provedeny v požadovaném pořadí, nemohou být představovány dílčími položkami.)
Dílčí prvek <conditional-subitem> umožňuje, aby krok přizpůsobil prezentaci dílčího kroku v závislosti na proměnných Cheat sheet, jejichž hodnoty jsou získány v předchozích krocích. Dílčí prvek <repeated-subitem> umožňuje, aby krok zahrnoval sadu podobných dílčích kroků. Přesná sada dílčích kroků může být opět založena na proměnných Cheat sheet, jejichž hodnoty jsou získány v předchozích krocích.
subitem
<!ELEMENT subitem ( [action|perform-when] )> <!ATTLIST subitem label CDATA #REQUIRED skip ("true" | "false") "false" when CDATA #IMPLIED >
Každý prvek <subitem> popisuje dílčí krok v Cheat sheet. <Subitem> nese jednoduché textové označení, ale nemá ani dlouhý popis ani další dílčí položky. Atributy <subitem> jsou následující:
Dílčí položky mají volitelnou akci. Přítomnost prvku <action> (nebo <perform-when>) je obvykle spojena s tlačítkem, jehož stisknutím může uživatel provést akci daného dílčího kroku. Pokud není žádná akce nabízena, musí uživatel provést dílčí krok ručně a poté zřetelně ukázat, že byl daný krok dokončen.
Na rozdíl od položek, u kterých musí uživatel dodržovat přesné pořadí, mohou být dílčí položky dané položky prováděny v libovolném pořadí. U všech dílčích položek v rámci položky musí být proveden pokus o jejich provedení (nebo musí být přeskočeny), než je možné přejít na další položku. (Což znamená, že akce, které musí být provedeny v požadovaném pořadí, nemohou být představovány dílčími položkami.)
conditional-subitem
<!ELEMENT conditional-subitem (subitem+)> <!ATTLIST conditional-subitem condition CDATA #REQUIRED >
Každý prvek <conditional-subitem> popisuje jeden dílčí krok, jehož forma se může lišit v závislosti na podmínce známé v době, kdy je položka rozbalena. Atributy <conditional-subitem> jsou následující:
Atribut condition v prvku <conditional-subitem> poskytuje hodnotu typu řetězec (tato hodnota vždy pochází z proměnné Cheat sheet). Každý z podřízených prvků <subitem> musí obsahovat when s jednoznačnou hodnotou typu řetězec. Když je položka rozbalena, je prvek <conditional-subitem> nahrazen prvkem <subitem> s odpovídající hodnotou. Je považováno za chybu, pokud se nevyskytuje žádný prvek <subitem> s odpovídající hodnotou.
Například pokud má proměnná Cheat sheet nazvaná "v1" hodnotu "b" při rozbalení následující položky:
<item ...> <conditional-subitem condition="${v1}"> <subitem when="a" label="Step for A." /> <subitem when="b" label="Step for B." /> </conditional-subitem> </item>V tom případě je vybrána druhá dílčí položka (subitem) a položka (item) je rozbalena do něčeho, co odpovídá
<item ...> <subitem label="Step for B."/> </item>
repeated-subitem
<!ELEMENT repeated-subitem (subitem)> <!ATTLIST repeated-subitem values CDATA #REQUIRED >
Každý prvek <repeated-subitem> popisuje dílčí položku, která se rozbalí do 0, 1 nebo více podobných dílčích kroků. Atributy <repeated-subitem> jsou následující:
Atribut values poskytuje seznam čárkou oddělených řetězců; podřízený prvek <subitem> poskytuje šablonu. Když je položka rozbalena, je prvek <repeated-subitem> nahrazen kopiemi prvku <subitem>, přičemž výskyty proměnné "this" jsou nahrazeny odpovídající hodnotou typu řetězec.
Například pokud má proměnná Cheat sheet nazvaná "v1" hodnotu "1,b,three" při rozbalení následující položky:
<item ...> <repeated-subitem values="${v1}"> <subitem label="Step ${this}."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/> </subitem> </repeated-subitem> </item>V tom případě je položka rozbalena do něčeho, co odpovídá:
<item ...> <subitem label="Step 1."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="1"/> </subitem> <subitem label="Step b."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="b"/> </subitem> <subitem label="Step three."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="three"/> </subitem> </item>
action
<!ELEMENT action EMPTY> <!ATTLIST action class CDATA #REQUIRED pluginId CDATA #REQUIRED param1 CDATA #IMPLIED ... param9 CDATA #IMPLIED confirm ("true" | "false") "false" when CDATA #IMPLIED >
Každý prvek <action> popisuje akci v Cheat sheet. Atributy <action> jsou následující:
org.eclipse.jface.action.IAction
.
Pokud tato akce rovněž implementuje org.eclipse.ui.cheatsheets.ICheatSheetAction
, bude vyvolána prostřednictvím její metody run(String[],ICheatSheetManager) a předána správci Cheat sheet a parametrům akce. Atribut pluginId musí být přítomen, kdykoli se vyskytuje tento atribut. U akcí, které budou vyvolávány z Cheat sheet se doporučuje, aby hlásily úspěšný/neúspěšný výsledek, pokud může spuštění akce selhat (například pokud uživatel akci zruší z dialogového okna). (Podrobnosti viz org.eclipse.jface.action.Action.notifyResult(boolean).)org.eclipse.ui.cheatsheets.ICheatSheetAction
jsou hodnoty typu řetězec těchto atributů předány na akci při jejím vyvolání. Akci Cheat sheet můžete předat až 9 parametrů (param1,
param2 atd.). Poskytnuté parametry musí začínat parametrem 1 a musí být souvislé; to znamená, že není možné zadat param2, aniž by existoval param1. Pokud je řetězec atributu ve formě "${var}", je považován za odkaz na proměnnou Cheat sheet var a hodnota podmínky bude hodnota proměnné pro Cheat sheet na začátku provádění obsahujícího prvku <item> (nebo prázdný řetězec, pokud není proměnná v dané chvíli svázaná).perform-when
<!ELEMENT perform-when (action+)> <!ATTLIST perform-when condition CDATA #REQUIRED >
Každý prvek <perform-when> popisuje akci v Cheat sheet. Atributy <perform-when> jsou následující:
Atribut condition v prvku <conditional-subitem> poskytuje hodnotu typu řetězec (tato hodnota vždy pochází z proměnné Cheat sheet). Každý z podřízených prvků <subitem> musí obsahovat when s jednoznačnou hodnotou typu řetězec. Když je položka rozbalena, je prvek <conditional-subitem> nahrazen prvkem <subitem> s odpovídající hodnotou. Je považováno za chybu, pokud se nevyskytuje žádný prvek <subitem> s odpovídající hodnotou.
Například pokud má proměnná Cheat sheet nazvaná "v1" hodnotu "b" při rozbalení následující položky:
<item ...> <subitem label="Main step"> <perform-when condition="${v1}"> <action when="a" class="com.xyz.action1" pluginId="com.xyz" /> <action when="b" class="com.xyz.action2" pluginId="com.xyz" /> </conditional-subitem> </subitem> </item>V tom případě je vybrána druhá akce a položka je rozbalena do něčeho, co odpovídá
<item ...> <subitem label="Main step"> <action class="com.xyz.action2" pluginId="com.xyz" /> </subitem> </item>
Následuje příklad velmi jednoduchého souboru s obsahem Cheat sheet:
<?xml version="1.0" encoding="UTF-8"?> <cheatsheet title="Příklad"> <intro> <description>Příklad obsahu Cheat sheet se dvěma kroky.</description> </intro> <item title="Krok 1"> <description>Toto je krok s akcí.</description> <action class="com.xyz.myaction" pluginId="com.xyz"/> </item> <item title="Step 2"> <description>Toto je plně ruční krok.</description> </item> </cheatsheet>
Copyright (c) 2004 IBM Corporation a další.
Všechna práva vyhrazena.
Tento program a doprovodné materiály jsou zpřístupněny za podmínek licence Eclipse Public License
v1.0, která je součástí této distribuce a je k dispozici na adrese
http://www.eclipse.org/legal/epl-v10.html