Spickzettel sind spezielle Sichten, die den Benutzer durch eine Reihe von komplexen Tasks leiten, um ein übergeordnetes Ziel zu erreichen. Ein Spickzettel könnte beispielsweise verwendet werden, um einen Benutzer durch alle Schritte zu führen, die für die Erstellung, Kompilierung und Ausführung eines einfachen Java-Programms nötig sind. Spickzettel werden vom Menüpunkt Hilfe>Spickzettel... gestartet. Sie können auch von einer Einführungsseite aus gestartet werden.
Spickzettel werden über den Erweiterungspunkt org.eclipse.ui.cheatsheets.cheatSheetContent definiert. Der Inhalt des Spickzettels selbst wird in einer getrennten Datei definiert, so dass er leichter in andere Sprachen übersetzt werden kann.
Die Ergänzung von Spickzetteln ist relativ einfach. Der Spickzettel im folgenden Beispiel wird durch die JDT ergänzt, um eine einfache Java-Anwendung zu erstellen.
<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> ...Ganz ähnlich wie bei anderen Workbench-Ergänzungen können für den Spickzettel Namen, Beschreibung und eine ID angegeben werden. Name und Beschreibung werden angezeigt, wenn der Benutzer auf die Liste Hilfe>Spickzettel... zugreift. Für den Spickzettel kann auch eine Kategorie definiert werden, wenn Sie mehrere Spickzettel zu einer logischen Gruppierung zusammenführen wollen. Wird keine Kategorie angegeben, so erscheint der Spickzettel in der Kategorie Andere.
Die eigentlichen Arbeitsschritte eines Spickzettels werden in der Inhaltsdatei vorgenommen. Die Inhaltsdatei ist eine XML-Datei, deren Name und Position im Attribut contentFile angegeben sind. Der Pfad der Datei wird relativ zum Verzeichnis des Plug-ins angegeben. (Beachten Sie die Verwendung der Variable$nl$ im Verzeichnisnamen, was bedeutet, dass die Datei in einem Verzeichnis untergebracht wird, das der Landessprache der Zielumgebung vorbehalten ist.)
Das Dateiformat selbst enthält Übersichtsinformationen über den Spickzettel, sowie eine Beschreibung aller Schritte (die als Elemente oder items bezeichnet werden) die der Benutzer ausführen soll. In seiner einfachsten Form ist ein Element nichts anderes als eine detaillierte Beschreibung des Schritts, den der Benutzer ausführen soll. Ein Element kann allerdings auch eine Aktion bestimmen, die den Schritt für den Benutzer ausführt. Der folgende Ausschnitt ist der erste Teil der Inhaltsdatei (HelloWorld.xml) des Java-Spickzettels.
<?xml version="1.0" encoding="UTF-8" ?> <cheatsheet title="Simple Java Application"> <intro href="/org.eclipse.ui.cheatsheets.doc/tasks/tcheatst.htm"> <description> Welcome to the Hello, World Java tutorial. It will help you build the famous "hello world" application and try it out. You will create a java project, and a java class that will print "hello world" in the console when run. Let's get started! </description> </intro> <item href="/org.eclipse.platform.doc.user/concepts/concepts-4.htm" title="Java-Perspektive öffnen"> <action pluginId="org.eclipse.ui.cheatsheets" class="org.eclipse.ui.internal.cheatsheets.actions.OpenPerspective" param1="org.eclipse.jdt.ui.JavaPerspective"/> <description> Wählen Sie in der Menüleiste oben in der Workbench die Optionen 'Fenster->Perspektive öffnen->Java' aus. This step changes the perspective to set up the Eclipse workbench for Java development. You can click the "Click to Perform" button to have the "Java" perspective opened automatically. </description> </item> ...
Titel und Einführungsinformationen werden am oberen Ende des Spickzettels angezeigt. Danach werden die Elemente beschrieben. Das erste Element dieses Spickzettels beschreibt, wie die Java-Perspektive geöffnet wird. Genaugenommen bestimmt das Attribut action eine Klasse, die verwendet werden kann, um die Aktion für den Benutzer durchzuführen. Die Klasse muss IAction implementieren. Dies ist recht praktisch, da Sie hierdurch Aktionsklassen, die für Menü- oder Symbolleistenergänzungen geschrieben wurden, wiederverwenden können.
Die Klasse der Aktion kann optional ICheatSheetAction implementieren, wenn die Aktion Parameter verwendet oder über den Spickzettel und seinen Status unterrichtet sein muss. In diesem Fall wird der Aktion eine Gruppe von Parametern und Verweis auf ICheatSheetManager übergeben, so dass sie zusätzliche Informationen über den Spickzettel abrufen kann. Erforderliche Parameter können an die Methode 'run' der Aktion über die Attribute des Typs paramN übergeben werden.
Es wird dringend empfohlen, dass Aktionen, die von Spickzetteln aufgerufen werden, eine Ausgabe über die erfolgreiche bzw. fehlgeschlagene Ausführung melden sollten, falls die Ausführung der Aktion fehlschlagen könnte. (Der Benutzer könnte die Aktion beispielsweise über den entsprechenden Dialog abbrechen.) Weitere Details finden Sie unter IAction.notifyResult(boolean).
Elemente müssen keine Aktionen definieren. Wenn Ihr Element vom Benutzer manuell ausgeführt werden muss, brauchen Sie überhaupt keine Aktion anzugeben. Der folgende Code ist der dritte Schritt des Java-Spickzettels, der dem Benutzer lediglich Anweisungen darüber gibt, wie er die einfache Anwendung codieren kann. Wenn keine Aktion angegeben wird, muss die Elementbeschreibung den Benutzer anweisen, die entsprechende Taste zu drücken, nachdem die Task beendet wurde.
<item href="/org.eclipse.jdt.doc.user/tasks/tasks-54.htm" title="Add a System.out.println line in your main method"> <description> Now that you have your HelloWorld class, In the "public static void main" method, add the following statement: System.out.println("Hello world!"); and save your changes. Press the "click when done" button below when finished. </description> </item>Zusätzliche Attribute steuern, ob das Element komplett übersprungen werden kann, und welches Dokument gestartet werden soll, wenn der Benutzer in diesem Schritt Hilfe anfordert. Eine Beschreibung aller Attribute, die in einem Spickzettel definiert werden können, finden Sie in der Dokumentation für den Erweiterungspunkt org.eclipse.ui.cheatsheets.cheatSheetContent.
Unterelemente können definiert werden, um die Darstellung eines Elements weiter zu organisieren. Im Gegensatz zu Elementen müssen Unterelemente nicht in einer bestimmten Reihenfolge abgerufen werden. Unterelemente können auch Aktionen definieren, die für den Benutzer eine Subtask automatisch ausführen. Unterelementaktionen werden genauso beschrieben wie Elementaktionen.
Spickzettelelemente, deren Inhalt oder Verhalten von der Erfüllung einer bestimmten Bedingung abhängen, können über Bedingungsausdrücke definiert werden. Bedingungen werden im Element condition eines Unterelements beschrieben. Hierfür werden für jede Auswahl beliebige Zeichenfolgewerte mit dem Attribut when abgeglichen. Bedingungen verwenden für den Verweis auf Spickzettelvariablen normalerweise das Format ${var}, wobei var sich auf den Namen einer Spickzettelvariable bezieht. Ein paar einfache Beispiele sollen veranschaulichen, wie Bedingungsausdrücke funktionieren.
Bedingte Unterelemente können verwendet werden, um ein Unterelement aus einer Liste möglicher Unterelemente auszuwählen. Nur das erste Unterelement, dessen Attribut when mit dem Bedingungsattribut übereinstimmt, wird im Spickzettel aufgenommen. Beispiel:
<item ...> <conditional-subitem condition="${v1}"> <subitem when="a" label="Step for A." /> <subitem when="b" label="Step for B." /> </conditional-subitem> </item>Dieses Element bestimmt zwei mögliche Unterelemente, die vom Wert der Variable v1 abhängen. Ist der Variablenwert a, wird das erste Unterelement eingefügt. Ist der Variablenwert b, wird das zweite Unterelement eingefügt. Hat die Variable keinen der beiden Werte, wird ein Fehler angenommen.
Bedingte Aktionen sind ähnlich wie bedingte Unterelemente. Das Element perform-when gibt eine Bedingung für die Ausführung einer Aktion aus einer Liste möglicher Aktionen an. Die Bedingung wird auf die gleiche Art und Weise definiert. Hierfür wird eine beliebige Zeichenfolge verwendet, die oft auf eine Variable verweist. Die Aktion, deren Attribut when mit der Bedingung übereinstimmt, ist diejenige, die ausgeführt wird. Beispiel:
<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>Die auszuführende Aktion wird auf Basis der Variable v1 ermittelt. Ist der Variablenwert weder a noch b, so wird ein Fehler angenommen.
Wiederholte Unterelemente beschreiben ein Unterelement, das in 0, 1 oder mehrere ähnliche Unterschritte erweitert werden kann. Die Unterschritte werden über die spezielle Variable ${this} individualisiert. Diese Variable wird durch die im Attribut values bestimmten Werte ersetzt. Das Attribut 'values' ist eine Folge von Werten, die durch Kommata getrennt werden. Für das Attribut 'values' kann auch eine Variable verwendet werden, die zu einer Liste von Werten erweitert wird. Beispiel:
<item ...> <repeated-subitem values="${v1}"> <subitem label="Step ${this}" /> </repeated-subitem> </item>Ist der Wert der Variable 1,b,drei, so erscheinen drei Unterelemente im Spickzettel, die jeweils eine eindeutige Bezeichnung haben ("Schritt 1," "Schritt b," "Schritt drei"). Die Variable kann in der Bezeichnung oder im Aktionsparameterwert verwendet werden. Der ICheatSheetManager kann während der Ausführung der Aktion auch auf sie zugreifen.
In manchen Fällen möchten Sie vielleicht andere Teile der Benutzerschnittstelle immer dann ändern, wenn ein Spickzettel aktiviert ist. In ihrem Editor könnten beispielsweise bestimmte Anmerkungen angezeigt werden, wenn der Benutzer von einem Spickzettel durch eine Editiertask geleitet wird. In diesem Fall kann eine Listener-Funktion als Attribut des Spickzettels angegeben werden. Das Listener-Attribut muss der vollständig qualifizierte Name der Java-Klasse sein, die eine Unterklasse zu CheatSheetListener bildet. Listener-Funktionen erhalten Benachrichtigungen zusammen mit einem Ereignis ICheatSheetEvent wenn sich der Lebenszyklus eines Spickzettels ändert, z.B. indem er geöffnet, geschlossen oder beendet wird.
Die Erweiterung org.eclipse.ui.cheatsheets.cheatSheetItemExtension kann verwendet werden, um beliebige Attribute zu einem bereits bestehenden Spickzettel zu ergänzen. Zweck dieses Erweiterungspunkts ist es, Plug-ins das Hinzufügen zusätzlicher Schaltflächen zu ermöglichen, die den Benutzer bei einem bestimmten Schritt unterstützen. Diese zusätzlichen Schaltflächen werden neben dem Hilfesymbol angezeigt.
Um diesen Mechanismus zu verwenden, können Sie beliebige Attribute innerhalb einer Elementdefinition in der XML-Datei des Spickzettels definieren. Die jeweiligen Attributsnamen werden gegen Attribute abgeglichen, die in Erweiterungen von org.eclipse.ui.cheatsheets.cheatSheetItemExtension ergänzt sind. Weitere Details finden Sie in der Dokumentation über Erweiterungspunkte.