Ściągawki to specjalne widoki, które zapewniają pomoc użytkownikom podczas wykonywania złożonych czynności i umożliwiają osiągnięcie ogólnego celu. Można z nich korzystać na przykład podczas tworzenia, kompilowania i wykonywania prostego programu w języku Java. Ściągawki uruchamia się, wybierając opcję menu Pomoc>Ściągawki. Można je także uruchamiać ze strony wprowadzenia.
Ściągawki definiuje się przy użyciu punktu rozszerzenia org.eclipse.ui.cheatsheets.cheatSheetContent. Sama treść ściągawki jest definiowana w osobnym pliku, co ułatwia przetłumaczenie jej na inne języki.
Wnoszenie ściągawki jest bardzo proste. Warto przyjrzeć się ściągawce wnoszonej przez pakiet JDT dotyczącej budowania prostej aplikacji w języku 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> ...Podobnie jak dla innych elementów wnoszonych środowiska roboczego, dla ściągawek można określić nazwę, opis i identyfikator. Nazwa i opis są wyświetlane na liście otwieranej za pomocą opcji Pomoc>Ściągawki. Aby umieścić kilka ściągawek w jednej grupie, można także zdefiniować kategorię. Jeśli kategoria nie zostanie zdefiniowana, ściągawka będzie wyświetlana w kategorii Inne.
Faktyczna praca nad utworzeniem ściągawki odbywa się w pliku treści. Jest to plik XML, którego nazwę i położenie określa atrybut contentFile. Ścieżka do pliku treści jest określana względem katalogu modułu dodatkowego. Warto zwrócić uwagę na użycie zmiennej $nl$ w nazwie katalogu, co spowoduje umieszczenie pliku w katalogu odpowiadającym wersji językowej środowiska docelowego.
Sam format pliku zawiera informacje ogólne o ściągawce wraz z opisem każdego kroku (nazywanego elementem) wykonywanego przez użytkownika. W swej najprostszej postaci element jest tylko szczegółowym opisem kroku wykonywanego przez użytkownika. Jednak element może także określać akcję, która może zostać uruchomiona w celu wykonania kroku w imieniu użytkownika. Poniżej przedstawiono pierwszą część pliku treści (HelloWorld.xml) dla ściągawki Java.
<?xml version="1.0" encoding="UTF-8" ?> <cheatsheet title="Prosta aplikacja Java"> <intro href="/org.eclipse.ui.cheatsheets.doc/tasks/tcheatst.htm"> <description> Zapraszamy do udziału w kursie języka Java pod tytułem Hello, World. Jego celem jest pomoc w napisaniu słynnej aplikacji "hello world" i przetestowaniu jej działania. W ramach kursu zostanie utworzony projekt java i klasa java, która po uruchomieniu wyświetli w konsoli tekst "hello world". Zatem do dzieła! </description> </intro> <item href="/org.eclipse.platform.doc.user/concepts/concepts-4.htm" title="Otwieranie perspektywy Java"> <action pluginId="org.eclipse.ui.cheatsheets" class="org.eclipse.ui.internal.cheatsheets.actions.OpenPerspective" param1="org.eclipse.jdt.ui.JavaPerspective"/> <description> Na pasku menu u góry środowiska roboczego wybierz kolejno opcje Okna->Otwórz perspektywę->Java. Spowoduje to zmianę perspektywy i przestawienie środowiska roboczego Eclipse na programowanie w języku Java. Możesz kliknąć przycisk "Kliknij, aby wykonać", aby otworzyć perspektywę Java automatycznie. </description> </item> ...
Tytuł i informacje wprowadzające są wyświetlane u góry ściągawki. Niżej znajdują się opisy elementów. Pierwszy element tej ściągawki opisuje sposób otwarcia perspektywy Java. Co więcej, atrybut action określa klasę, której można użyć do uruchomienia akcji w imieniu użytkownika. Klasa ta musi implementować interfejs IAction. Jest to dość wygodne rozwiązanie, ponieważ umożliwia ponowne wykorzystanie klas akcji napisanych dla elementów wnoszonych menu lub pasków narzędzi.
Klasa akcji może opcjonalnie implementować interfejs ICheatSheetAction, o ile akcja używa parametrów lub powinna mieć informacje o ściągawce i jej stanie. W takim przypadku do akcji zostanie przekazana tablica parametrów i odwołanie do interfejsu ICheatSheetManager, dzięki czemu będzie ona mogła zażądać dodatkowych informacji o ściągawce. Wszelkie potrzebne parametry można przekazać do metody uruchamiania akcji przy użyciu atrybutów paramN.
Zdecydowanie zaleca się, aby akcje wywoływane poprzez ściągawkę zgłaszały powodzenie/niepowodzenie wykonania, o ile wykonanie akcji może się nie powieść (na przykład użytkownik może anulować akcję w jej oknie dialogowym). Więcej szczegółowych informacji na ten temat zawiera opis metody IAction.notifyResult(boolean).
Elementy nie muszą definiować akcji. Jeśli dany element musi być wykonany ręcznie przez użytkownika, nie ma potrzeby określania akcji. Poniżej przedstawiono trzeci krok ściągawki Java, który po prostu informuje użytkownika, jak napisać prostą aplikację. Gdy nie zostanie określona żadna akcja, opis w elemencie musi zawierać polecenie kliknięcia odpowiedniego przycisku przez użytkownika po wykonaniu czynności.
<item href="/org.eclipse.jdt.doc.user/tasks/tasks-54.htm" title="Dodawanie wiersza System.out.println w metodzie main"> <description> Gdy już masz swoją klasę HelloWorld, w metodzie "public static void main" dodaj następującą instrukcję: System.out.println("Hello world!"); i zapisz zmiany. Gdy skończysz, kliknij przycisk "Kliknij, kiedy gotowe" poniżej. </description> </item>Dodatkowe atrybuty decydują o tym, czy dany element można zupełnie pominąć oraz jaki dokument powinien zostać uruchomiony, gdy użytkownik zażąda pomocy podczas wykonywania tego kroku. Opis wszystkich atrybutów, które można zdefiniować wewnątrz ściągawki zawiera dokumentacja punktu rozszerzenia org.eclipse.ui.cheatsheets.cheatSheetContent.
Podelementy definiuje się w celu bardziej szczegółowej organizacji prezentacji elementu. W przeciwieństwie do elementów podelementy nie muszą być wywoływane w określonej kolejności. Podelementy mogą także definiować akcje, które automatycznie wykonają za użytkownika czynność podrzędną. Akcje podelementów opisuje się tak samo jak akcje elementów.
Wyrażenia warunkowe służą do definiowania elementów ściągawek, których treść lub zachowanie zależy od tego, czy konkretny warunek jest spełniony. Warunki są opisane w elemencie XML condition podelementu przy użyciu dowolnych wartości typu string, które są dopasowywane do atrybutu when dla każdej opcji. Warunki zwykle odwołują się do zmiennych ściągawki, używając formy ${zmienna}, gdzie zmienna odnosi się do nazwy zmiennej ściągawki. Kilka prostych przykładów pomoże zademonstrować sposób działania wyrażeń warunkowych.
Podelementy warunkowe służą do wyboru jednego podelementu z listy możliwych podelementów. Do ściągawki dołączany jest tylko pierwszy podelement, którego atrybut when jest zgodny z atrybutem warunku. Na przykład:
<item ...> <conditional-subitem condition="${v1}"> <subitem when="a" label="Krok dla A." /> <subitem when="b" label="Krok dla B." /> </conditional-subitem> </item>Ten element określa dwa możliwe podelementy, które zależą od wartości zmiennej v1. Gdy wartość zmiennej wynosi a, zostanie dołączony pierwszy podelement. Gdy wartość zmiennej wynosi b, zostanie dołączony drugi podelement. Inna wartość zmiennej zostanie uznana za błąd.
Akcje warunkowe są podobne do podelementów warunkowych. Element XML perform-when określa warunek wykonania jednej spośród możliwych akcji. Warunek jest opisywany w ten sam sposób i użyty do tego celu może zostać dowolny łańcuch, który zwykle odwołuje się do zmiennej. Akcja, której atrybut when jest zgodny z warunkiem, zostanie wykonana. Na przykład:
<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>Akcja do wykonania jest wybierana na podstawie wartości zmiennej v1. Wartość zmiennej inna niż a lub b jest uznawana za błąd.
Podelementy powtarzane to takie, które można rozwinąć na 0, 1 lub więcej podobnych kroków podrzędnych. Kroki podrzędne indywidualizuje się przy użyciu specjalnej zmiennej ${this}. Ta zmienna zostanie zastąpiona przez wartość określoną atrybutem values. Atrybut values to łańcuch wartości rozdzielonych przecinkami. W atrybucie values może być używana zmienna rozwijana do listy wartości. Na przykład:
<item ...> <repeated-subitem values="${v1}"> <subitem label="Krok ${this}" /> </repeated-subitem> </item>Gdy wartość zmiennej wynosi 1,b,trzeci, w ściągawce zostaną wyświetlone trzy podelementy z unikalnymi etykietami ("Krok 1," "Krok b," "Krok trzeci"). Zmiennej można użyć w etykiecie lub w wartości parametru akcji. Jest ona także dostępna z interfejsu ICheatSheetManager podczas wykonywania akcji.
W niektórych przypadkach pożądana może być zmiana innych części interfejsu użytkownika, gdy ściągawka jest aktywna. Na przykład w edytorze mogą być wyświetlane specjalne adnotacje, gdy użytkownik korzysta ze ściągawki podczas czynności edycji. W takiej sytuacji jako atrybut ściągawki można określić funkcję nasłuchiwania. Atrybut funkcji nasłuchiwania musi być pełną nazwą klasy Java, która jest podklasą klasy CheatSheetListener. Funkcje nasłuchiwania będą wraz z interfejsem ICheatSheetEvent otrzymywać powiadomienia, gdy wystąpi zmiana w cyklu życia ściągawki, na przykład gdy zostanie ona otwarta, zamknięta lub zakończona.
Punkt rozszerzenia org.eclipse.ui.cheatsheets.cheatSheetItemExtension służy do wnoszenia dowolnych atrybutów do istniejącej już ściągawki. Zadaniem tego punktu rozszerzenia jest umożliwienie wprowadzania dodatkowych przycisków, które pomogą użytkownikowi w danym kroku. Te przyciski są wyświetlane obok ikony pomocy.
Aby użyć tego mechanizmu, można zdefiniować dowolny atrybut wewnątrz definicji elementu w pliku XML ściągawki. Nazwa atrybutu zostanie dopasowana do atrybutów wnoszonych w rozszerzeniach punktu rozszerzenia org.eclipse.ui.cheatsheets.cheatSheetItemExtension. Szczegółowe informacje na ten temat można znaleźć w dokumentacji punktu rozszerzenia.