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