Wersja 3.2
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 poprawnego wyświetlenia go 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, aczkolwiek inne znaczniki mogą zostać dodane w przyszłości. 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 ograniczniki 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|command|perform-when] | (subitem|repeated-subitem|conditional-subitem)*) [onCompletion])> <!ATTLIST item title CDATA #REQUIRED dialog ("true" | "false") "false" 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 zawierać elementy <subitem>. Poniżej przedstawiono atrybuty elementu <item>:
Rozszerzenie org.eclipse.ui.cheatsheets.cheatSheetItemExtension umożliwia wyświetlanie w interfejsie użytkownika dodatkowych elementów 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 oraz opcjonalną akcję lub komendę. 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>, <command> lub <perform-when> jest zwykle związana z przyciskiem, który użytkownik może kliknąć w celu wykonania akcji lub komendy w ramach danego etapu. W przypadku braku akcji lub komendy użytkownik musi wykonać dany etap ręcznie, a następnie jawnie zasygnalizować jego pomyślne zakończenie.
Etapy mogą dzielić się na etapy podrzędne 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ć reprezentowane w postaci podelementów.
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|command|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>:
W ramach podelementów mogą występować opcjonalne akcje lub komendy. Obecność elementu <action>, <command> lub <perform-when> jest związana z przyciskiem, który użytkownik może kliknąć w celu wykonania akcji lub komendy w ramach danego etapu. W przypadku braku akcji lub komendy użytkownik musi wykonać dany etap podrzędny ręcznie, a następnie jawnie 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. Przed przejściem do następnego elementu należy wykonać lub pominąć wszystkie podelementy w ramach bieżącego elementu. Oznacza to, że akcje, które należy wykonać w ustalonej kolejności, nie powinny być reprezentowane w postaci podelementów.
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ść łańcucha (wartość ta pochodzi zawsze ze zmiennej ściągawki). Każdy element podrzędny <subitem> musi zawierać atrybut when wraz z odmienną wartością łańcucha. 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 łańcucha.
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.moja_akcja" 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.moja_akcja" pluginId="com.xyz" param1="1"/> </subitem> <subitem label="Krok b."> <action class="com.xyz.moja_akcja" pluginId="com.xyz" param1="b"/> </subitem> <subitem label="Krok trzeci."> <action class="com.xyz.moja_akcja" pluginId="com.xyz" param1="trzeci"/> </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 łańcucha 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).command
<!ELEMENT command EMPTY> <!ATTLIST command serialization CDATA #REQUIRED returns CDATA #IMPLIED confirm ("true" | "false") "false" when CDATA #IMPLIED >
Każdy element <command> opisuje komendę w ściągawce. Poniżej przedstawiono atrybuty elementu <command>:
Poniżej przedstawiono przykładowy element z komendą otwierającą okno dialogowe i zapisującą rezultaty w zmiennej ściągawki "wynik".
<item title="Wybór widoku"> <description>Wybierz widok, który ma zostać otwarty w następnym etapie.</description> <command returns = "wynik" serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Wybór widoku,buttonLabel0=Eksplorator pakietów,message=Wybierz widok,buttonLabel1=Widok wyszukiwania)"/> <onCompletion> Wybrano opcję ${wynik}. </onCompletion> </item>
onCompletion
<!ELEMENT onCompletion EMPTY> <!ATTLIST onCompletion >
Element <onCompletion> zawiera tekst, który ma być wyświetlany po wykonaniu danego elementu ściągawki. Jest on szczególnie przydatny na końcowych etapach ściągawek, umożliwia bowiem potwierdzanie wykonania całej czynności. Opis ma postać tekstu z prostymi znacznikami formatowania, w przypadku których obowiązują te same reguły, co w przypadku elementu <description>. Elementy <onCompletion> mogą także zawierać odwołania do zmiennych ściągawki w postaci "${zmienna}". Po zakończeniu danego etapu element zmienna zostaje zastąpiony odpowiadającą mu wartością.
perform-when
<!ELEMENT perform-when ((action|command)+)> <!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ść łańcucha (wartość ta pochodzi zawsze ze zmiennej ściągawki). Każdy element podrzędny <subitem> musi zawierać atrybut when wraz z odmienną wartością łańcucha. 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.akcja1" pluginId="com.xyz" /> <action when="b" class="com.xyz.akcja2" pluginId="com.xyz" /> <command when="c" serialization="org.eclipse.search.ui.views.SearchView"/> </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.akcja2" pluginId="com.xyz" /> </subitem> </item>
Poniżej przedstawiono przykładowy plik treści ściągawki prostej, w którym zademonstrowano zastosowanie elementów <command>, <perform-when> i <conditional-subitem>.
<?xml version="1.0" encoding="UTF-8"?> <cheatsheet title="Przykładowa ściągawka"> <intro> <description>Ściągawka ta ma na celu zademonstrowanie zastosowania elementów typu perform-when oraz elementów conditional-subitem.</description> </intro> <item title="Wybór widoku"> <description>Wybierz widok, który ma zostać otwarty w następnym etapie.</description> <command returns = "wynik" serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Wybór widoku,buttonLabel0=Eksplorator pakietów,message=Wybierz widok,buttonLabel1=Widok wyszukiwania)"/> <onCompletion> Wybrano opcję ${wynik}. </onCompletion> </item> <item title="Zamykanie widoków"> <description>Zamykanie widoku wyszukiwania i Eksploratora pakietów, jeśli są otwarte</description> </item> <item title="Otwieranie widoku za pomocą elementu perform-when" skip = "true"> <description>Zastosowanie elementu perform-when do otwarcia wcześniej wybranego widoku</description> <perform-when condition = "${wynik}"> <command when = "Eksplorator pakietów" serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.jdt.ui.PackageExplorer)"/> <command when = "Widok wyszukiwania" serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.search.ui.views.SearchView)"/> </perform-when> </item> <item title="Zamykanie widoków"> <description>Zamykanie widoku wyszukiwania i Eksploratora pakietów, jeśli są otwarte</description> </item> <item title="Otwieranie widoku za pomocą podelementu perform-when"> <description>Zastosowanie elementu perform-when do otwarcia wcześniej wybranego widoku</description> <subitem label="Podelement perform-when" skip = "true"> <perform-when condition = "${wynik}"> <command when = "Eksplorator pakietów" serialization="org.eclipse.jdt.ui.PackageExplorer"/> <command when = "Widok wyszukiwania" serialization="org.eclipse.search.ui.views.SearchView"/> </perform-when> </subitem> </item> <item title="Zamykanie widoków"> <description>Zamykanie widoku wyszukiwania i Eksploratora pakietów, jeśli są otwarte</description> </item> <item title="Otwieranie widoku za pomocą elementu conditional-subitem"> <description>Zastosowanie elementu perform-when do otwarcia wcześniej wybranego widoku</description> <conditional-subitem condition="${wynik}"> <subitem when="Eksplorator pakietów" label="Otwórz Eksplorator pakietów"> <command serialization = "org.eclipse.jdt.ui.PackageExplorer"/> </subitem> <subitem when="Widok wyszukiwania" label="Otwórz widok wyszukiwania"> <command serialization = "org.eclipse.search.ui.views.SearchView"/> </subitem> </conditional-subitem> </item> </cheatsheet>
Copyright (c) 2004, 2006 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.