Wersja 3.0
W tym dokumencie opisano strukturę pliku treści ściągawki w postaci zbioru fragmentów definicji DTD (schemat XML w formie zapisu maszynowego).
cheatsheet
<!ELEMENT cheatsheet (intro, item+)> <!ATTLIST cheatsheet title CDATA #REQUIRED >
Element <cheatsheet> definiuje treść pliku treści ściągawki. Poniżej przedstawiono atrybuty elementu <cheatsheet>:
intro
<!ELEMENT intro (description)> <!ATTLIST intro contextId CDATA #IMPLIED href CDATA #IMPLIED >
Element <intro> służy do opisania wyświetlanego wprowadzenia do ściągawki. Podelement <description> zawiera treść wprowadzenia. Poniżej przedstawiono atrybuty elementu <intro>:
description
<!ELEMENT description EMPTY> <!ATTLIST description >
Element <description> zawiera opis ściągawki lub jej elementu. Opis składa się z tekstu przeplatanego prostymi znacznikami formatowania. Tekst jest automatycznie formatowany i rozmieszczany przez ściągawkę w celu jego poprawnego wyświetlenia w interfejsie użytkownika. Użyte w obrębie tekstu pary znaczników <b>...</b> powodują renderowanie znajdującego się między nimi tekstu za pomocą pogrubionej czcionki, natomiast znacznik <br/> służy do wymuszenia końca wiersza. Są to jedyne obsługiwane obecnie znaczniki formatowania, chociaż w przyszłości mogą zostać dodane inne znaczniki. Niektóre znaki w tekście mają specjalne znaczenie dla analizatorów składni XML. W szczególności zamiast symboli "<", ">", "&", "'" i """ (cudzysłów) należy używać odpowiednio łańcuchów "<", ">", "&", "'" i """. Znaki spacji, tabulacji lub nowego wiersza są traktowane jako separatory słów. Przylegające spacje i znaki podziału wiersza są traktowane jako pojedyncza jednostka i renderowane jako pojedyncza spacja lub znak podziału wiersza. Znaki spacji znajdujące się po znacznikach <description> i <br/> są ignorowane, podobnie jak analogiczne znaki umieszczone bezpośrednio przed znacznikiem </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żdy element <item> opisuje jeden krok najwyższego poziomu w ściągawce. Element <item> może być prosty lub złożony. Poniżej przedstawiono atrybuty elementu <item>:
Rozszerzenie org.eclipse.ui.cheatsheets.cheatSheetItemExtension umożliwia wyświetlanie w interfejsie użytkownika dodatkowych, niestandardowych pól sterujących dla danego elementu. Uzupełnienia tego punktu rozszerzenia deklarują nazwy dodatkowych atrybutów o wartościach w postaci łańcuchów, które mogą być używane w elementach <item>.
Proste elementy mają opis i opcjonalną akcję. W przypadku typowej prezentacji tytuły elementów ściągawki są wyświetlane przez większość czasu. Opis elementu jest wyświetlany tylko podczas wykonywania kroku w procesie. Obecność elementu <action> (lub <perform-when>) jest zwykle powiązana z przyciskiem, który użytkownik może kliknąć w celu wykonania akcji danego kroku. W przypadku braku akcji użytkownik musi wykonać dany krok ręcznie, a następnie zasygnalizować jego pomyślne zakończenie.
Kroki złożone są podzielone na podkroki określane za pomocą podelementów <subitem>. W przeciwieństwie do elementów, które muszą zostać wykonane przez użytkownika w ściśle określonej kolejności, podelementy danego elementu mogą zostać wykonane w dowolnej kolejności. Należy wykonać (lub pominąć) wszystkie podelementy danego elementu, aby możliwe było przejście do kolejnego elementu. Oznacza to, że akcje, które należy wykonać w ustalonej kolejności, nie mogą być przedstawiane jako podelementy.
Podelement <conditional-subitem> umożliwia dostosowanie prezentacji podkroku w zależności od zmiennych ściągawki, których wartości zostały uzyskane we wcześniejszych krokach. Podelement <repeated-subitem> umożliwia zawarcie w danym kroku zestawu podobnych podkroków. Również w tym przypadku treść takiego zestawu podkroków może zależeć od zmiennych ściągawki uzyskanych we wcześniejszych krokach.
subitem
<!ELEMENT subitem ( [action|perform-when] )> <!ATTLIST subitem label CDATA #REQUIRED skip ("true" | "false") "false" when CDATA #IMPLIED >
Każdy element <subitem> opisuje podkrok w ściągawce. Z elementem <subitem> powiązana jest prosta etykieta tekstowa, ale nie ma on długiego opisu ani dalszych podelementów. Poniżej przedstawiono atrybuty elementu <subitem>:
Podelementy mają opcjonalną akcję. Obecność elementu <action> (lub <perform-when>) jest zwykle powiązana z przyciskiem, który użytkownik może kliknąć w celu wykonania akcji danego podkroku. W przypadku braku akcji użytkownik musi wykonać dany podkrok ręcznie, a następnie zasygnalizować jego pomyślne zakończenie.
W przeciwieństwie do elementów, które muszą zostać wykonane w ściśle określonej kolejności, podelementy danego elementu mogą zostać wykonane w dowolnej kolejności. Należy wykonać (lub pominąć) wszystkie podelementy danego elementu, aby możliwe było przejście do kolejnego elementu. Oznacza to, że akcje, które należy wykonać w ustalonej kolejności, nie powinny być przedstawiane jako podelementy.
conditional-subitem
<!ELEMENT conditional-subitem (subitem+)> <!ATTLIST conditional-subitem condition CDATA #REQUIRED >
Każdy element <conditional-subitem> opisuje pojedynczy podkrok, którego forma może się różnić zależnie od warunku, który będzie znany w momencie rozwinięcia elementu. Poniżej przedstawiono atrybuty elementu <conditional-subitem>:
Atrybut condition elementu <conditional-subitem> udostępnia wartość typu łańcuchowego (wartość ta pochodzi zawsze ze zmiennej ściągawki). Każdy element podrzędny <subitem> musi zawierać atrybut when wraz z odmienną wartością typu łańcuchowego. Po rozwinięciu elementu dany element <conditional-subitem> jest zastępowany elementem <subitem> o zgodnej wartości. Brak elementu <subitem> o zgodnej wartości jest traktowany jako błąd.
Na przykład jeśli podczas rozwijania następującego elementu zmienna ściągawki o nazwie "v1" ma wartość "b":
<item ...> <conditional-subitem condition="${v1}"> <subitem when="a" label="Krok dla wartości A." /> <subitem when="b" label="Krok dla wartości B." /> </conditional-subitem> </item>wybrany zostanie drugi podelement, a sam element zostanie rozwinięty do następującej postaci:
<item ...> <subitem label="Krok dla wartości B."/> </item>
repeated-subitem
<!ELEMENT repeated-subitem (subitem)> <!ATTLIST repeated-subitem values CDATA #REQUIRED >
Każdy element <repeated-subitem> opisuje podelement, który jest rozwijany do jednego lub większej liczby podobnych podkroków (albo też do żadnego). Poniżej przedstawiono atrybuty elementu <repeated-subitem>:
Atrybut values udostępnia listę rozdzielonych przecinkami łańcuchów, natomiast element podrzędny <subitem> udostępnia szablon. Po rozwinięciu elementu dany element <repeated-subitem> jest zastępowany kopiami elementu <subitem> z wystąpieniami zmiennej "this" zamienionymi na odpowiednie wartości typu łańcuchowego.
Na przykład jeśli podczas rozwijania następującego elementu zmienna ściągawki o nazwie "v1" ma wartość "1,b,trzeci":
<item ...> <repeated-subitem values="${v1}"> <subitem label="Krok ${this}."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/> </subitem> </repeated-subitem> </item>element zostanie rozwinięty do następującej postaci:
<item ...> <subitem label="Krok 1."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="1"/> </subitem> <subitem label="Krok b."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="b"/> </subitem> <subitem label="Krok trzeci."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="trzy"/> </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żdy element <action> opisuje akcję w ściągawce. Poniżej przedstawiono atrybuty elementu <action>:
org.eclipse.jface.action.IAction
.
Jeśli akcja implementuje również interfejs org.eclipse.ui.cheatsheets.ICheatSheetAction
,
zostanie wywołana poprzez jego metodę run(String[],ICheatSheetManager). Do akcji zostanie wówczas przekazany
menedżer ściągawki i parametry akcji. Gdy używany jest ten atrybut, obecny musi być również atrybut pluginId.
Zdecydowanie zaleca się, aby akcje wywoływane poprzez ściągawkę zgłaszały powodzenie lub niepowodzenie wykonania,
jeśli możliwe jest zakończenie się akcji niepowodzeniem (na przykład w sytuacji, gdy użytkownik anuluje akcję
poprzez jej okno dialogowe). Więcej
informacji można znaleźć w opisie metody
org.eclipse.jface.action.Action.notifyResult(boolean).org.eclipse.ui.cheatsheets.ICheatSheetAction
, wartości typu łańcuchowego tych atrybutów
są przekazywane do akcji przy jej wywoływaniu. Do akcji ściągawki można przekazać maksymalnie
9 parametrów (param1, param2 itd.). Podane parametry muszą zaczynać się od parametru 1,
a ich numeracja musi być ciągła. Oznacza to, że nie można określić parametru param2, jeśli nie istnieje
parametr param1. Jeśli łańcuch atrybutu ma postać "${zmienna}",
zostanie potraktowany jako odwołanie do zmiennej zmienna ściągawki. Warunek otrzyma
wartość tej zmiennej ściągawki z początku wykonywania zawartego w tym elemencie
elementu <item> (lub pusty łańcuch, jeśli w danym momencie zmienna nie będzie powiązana).perform-when
<!ELEMENT perform-when (action+)> <!ATTLIST perform-when condition CDATA #REQUIRED >
Każdy element <perform-when> opisuje akcję w ściągawce. Poniżej przedstawiono atrybuty elementu <perform-when>:
Atrybut condition elementu <conditional-subitem> udostępnia wartość typu łańcuchowego (wartość ta pochodzi zawsze ze zmiennej ściągawki). Każdy element podrzędny <subitem> musi zawierać atrybut when wraz z odmienną wartością typu łańcuchowego. Po rozwinięciu elementu dany element <conditional-subitem> jest zastępowany elementem <subitem> o zgodnej wartości. Brak elementu <subitem> o zgodnej wartości jest traktowany jako błąd.
Na przykład jeśli podczas rozwijania następującego elementu zmienna ściągawki o nazwie "v1" ma wartość "b":
<item ...> <subitem label="Krok główny"> <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>wybrana zostanie druga akcja, a sam element zostanie rozwinięty do następującej postaci:
<item ...> <subitem label="Krok główny"> <action class="com.xyz.action2" pluginId="com.xyz" /> </subitem> </item>
Poniżej przedstawiono przykład bardzo prostego pliku treści ściągawki:
<?xml version="1.0" encoding="UTF-8"?> <cheatsheet title="Przykład"> <intro> <description>Przykładowa ściągawka z dwoma krokami.</description> </intro> <item title="Krok 1"> <description>Jest to krok zawierający akcję.</description> <action class="com.xyz.myaction" pluginId="com.xyz"/> </item> <item title="Krok 2"> <description>Jest to krok wykonywany w całości ręcznie.</description> </item> </cheatsheet>
Copyright (c) 2004 IBM Corporation i inne podmioty.
Wszelkie prawa zastrzeżone. Program ten oraz towarzyszące mu materiały są udostępniane na warunkach licencji EPL (Eclipse Public License), wersja 1.0, dołączonej do nich i dostępnej pod adresem http://www.eclipse.org/legal/epl-v10.html.