Version 3.2
Dieses Dokument beschreibt die Struktur der Inhaltsdatei für den Spickzettel als Reihe von DTD-Fragmenten (maschinenlesbares XML-Schema).
cheatsheet
<!ELEMENT cheatsheet (intro, item+)> <!ATTLIST cheatsheet title CDATA #REQUIRED >
Das Element <cheatsheet> definiert den Hauptteil der Inhaltsdatei für den Spickzettel. Für das Attribut <cheatsheet> gibt es folgende Attribute:
intro
<!ELEMENT intro (description)> <!ATTLIST intro contextId CDATA #IMPLIED href CDATA #IMPLIED >
Mit dem Element <intro> wird die Einführung in den Spickzettel beschrieben, die angezeigt werden soll. Das Unterelement <description> enthält den Hauptteil der Einführung. Für das Element <intro> werden die folgenden Attribute verwendet:
description
<!ELEMENT description EMPTY> <!ATTLIST description >
Das Element <description> enthält die Beschreibung eines Spickzettels oder eines Spickzettelements. Die Beschreibung besteht aus Text mit einfachen Formatierungstags. Der Spickzettel formatiert den Text automatisch und ordnet ihn so an, dass er in der Benutzerschnittstelle korrekt angezeigt wird. Im Text bewirken die Tagpaare <b>...</b>, dass der eingeschlossene Text in einer Fettdruckschriftart wiedergegeben wird. Mit dem Element <br/> kann ein Zeilenumbruch erzwungen werden. Gegenwärtig werden lediglich diese Formatierungstags unterstützt (künftig werden möglicherweise jedoch weitere Tags hinzugefügt). Bestimmte Zeichen im Text haben eine besondere Bedeutung für XML-Parser. Insbesondere sollten Sie statt "<", ">", "&", "'" und """ (Fragezeichen) die Schreibweise "<", ">", "&", "'" bzw. """ verwenden. Leerräume (Leerzeichen und Zeilenumbrüche) werden als Worttrennzeichen behandelt. Benachbarte Leerzeichen und Zeilenumbrüche werden als gemeinsame Einheit betrachtet und als einfaches Leerzeichen bzw. einfacher Zeilenumbruch wiedergegeben. Ein Leerzeichen, das unmittelbar nach den Tags <description> und <br/> angegeben ist, wird ignoriert, gleiches gilt für ein Leerzeichen direkt vor dem Tag </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 >
Jedes Element <item> beschreibt einen Schritt der höchsten Ebene im Spickzettel. Ein Element <item> kann Elemente <subitem> enthalten. Für das Element <item> gibt es folgende Attribute:
Die Erweiterung "org.eclipse.ui.cheatsheets.cheatSheetItemExtension" ermöglicht das Anzeigen zusätzlicher Steuerelemente für das Element in der Benutzerschnittstelle. Ergänzungen für diesen Erweiterungspunkt deklarieren die Namen von zusätzlichen Attributen mit Zeichenfolgewerten, die für Elemente <item> angezeigt werden können.
Einfache Elemente haben eine Beschreibung und eine optionale Aktion bzw. einen optionalen Befehl. In der normalen Darstellung werden die Titel der Spickzettelelemente meistens für den Benutzer angezeigt. Die Beschreibung eines Elements wird nur dann angezeigt, wenn der Prozess gerade ausgeführt wird. Das Vorhandensein eines Elements <action>, <command> oder <perform-when> ist normalerweise mit einer Schaltfläche verbunden, durch deren Auswahl der Benutzer die Aktion oder den Befehl des entsprechenden Schrittes ausführen kann. Wenn keine Aktion bzw. kein Befehl vorhanden ist, handelt es sich um einen Schritt, den der Benutzer manuell ausführen und anschließend angeben muss, dass der Schritt erfolgreich ausgeführt wurde.
Schritte können in Unterschritte aufgeteilt werden, die durch die Unterelemente <subitem> angegeben werden. Anders als Elemente, die der Benutzer in einer genauen Reihenfolge befolgen muss, können die Unterelemente eines Elements in einer beliebigen Reihenfolge ausgeführt werden. Alle Unterelemente innerhalb eines Elements müssen aufgerufen (oder übersprungen) werden, bevor mit dem nächsten Element fortgefahren wird. (Dies bedeutet, dass Aktionen, die in einer bestimmten Reihenfolge ausgeführt werden müssen, nicht als Unterelemente dargestellt werden können.)
Durch ein Unterelement <conditional-subitem> kann ein Schritt die Darstellung eines Unterschrittes basierend auf Spickzettelvariablen anpassen, deren Werte in vorherigen Schritten erhalten wurden. Durch ein Unterelement <repeated-subitem> kann ein Schritt eine Reihe von ähnlichen Unterschritten aufnehmen. Die genaue Gruppe der Unterschritte kann auch hier auf Spickzettelvariablen basieren, deren Werte in früheren Schritten erhalten wurden.
subitem
<!ELEMENT subitem ( [action|command|perform-when] )> <!ATTLIST subitem label CDATA #REQUIRED skip ("true" | "false") "false" when CDATA #IMPLIED >
Jedes Element <subitem> beschreibt einen Unterschritt auf einem Spickzettel. Ein Element <subitem> enthält eine einfache Textmarke, jedoch keine längere Beschreibung oder weitere Unterelemente. Für das Element <subitem> gibt es die folgenden Attribute:
Unterelemente können eine optionale Aktion oder einen optionalen Befehl enthalten. Das Vorhandensein eines Elements <action>, <command> oder <perform-when> ist normalerweise mit einer Schaltfläche verbunden, durch deren Auswahl der Benutzer die Aktion oder den Befehl des entsprechenden Unterschrittes ausführen kann. Wenn keine Aktion bzw. kein Befehl vorhanden ist, handelt es sich um einen Unterschritt, den der Benutzer manuell ausführen und anschließend angeben muss, dass der Schritt erfolgreich ausgeführt wurde.
Anders als Elemente, die in einer genauen Reihenfolge befolgt werden müssen, können die Unterelemente eines jeweiligen Elements in einer beliebigen Reihenfolge ausgeführt werden. Alle Unterelemente innerhalb eines Elements müssen abgeschlossen oder übersprungen werden, bevor mit dem nächsten Element fortgefahren wird. (Dies bedeutet, dass Aktionen, die in einer bestimmten Reihenfolge ausgeführt werden müssen, nicht als Unterelemente dargestellt werden sollten.)
conditional-subitem
<!ELEMENT conditional-subitem (subitem+)> <!ATTLIST conditional-subitem condition CDATA #REQUIRED >
Jedes Element <conditional-subitem> beschreibt einen einzelnen Unterschritt, dessen Format abhängig von einer Bedingung variieren kann, die zum Zeitpunkt der Erweiterung des Elements bekannt ist. Für das Element <conditional-subitem> gibt es die folgenden Attribute:
Das Attribut condition für das Element <conditional-subitem> stellt einen Zeichenfolgewert zur Verfügung (dieser Wert stammt unveränderbar aus einer Spickzettelvariablen). Jedes untergeordnete Element <subitem> muss ein Attribut when mit einem distinkten Zeichenfolgewert haben. Wenn das Element erweitert wird, wird das Element <conditional-subitem> durch das Element <subitem> mit dem übereinstimmenden Wert ersetzt. Falls kein Element <subitem> mit einem übereinstimmenden Wert vorhanden ist, gilt dies als Fehler.
Beispiel: Die Spickzettelvariable namens "v1" hat den Wert "b", und das folgende Element wird erweitert:
<item ...> <conditional-subitem condition="${v1}"> <subitem when="a" label="Step for A." /> <subitem when="b" label="Step for B." /> </conditional-subitem> </item>In diesem Fall wird das zweite Unterelement ausgewählt, und das Element wird etwa wie folgt erweitert:
<item ...> <subitem label="Step for B."/> </item>
repeated-subitem
<!ELEMENT repeated-subitem (subitem)> <!ATTLIST repeated-subitem values CDATA #REQUIRED >
Jedes Element <repeated-subitem> beschreibt ein Unterelement, das in 0, 1 oder mehr ähnliche Unterschritte erweitert wird. Es gibt folgende Attribute für das Element <repeated-subitem>:
Das Attribut values stellt eine Liste von durch Kommata getrennten Zeichenfolgen zur Verfügung. Das untergeordnete Element <subitem> stellt die Schablone bereit. Wenn das Element erweitert wird, wird das Element <repeated-subitem> durch Kopien des Elements <subitem> ersetzt, wobei die Vorkommen der Variablen "this" durch den entsprechenden Zeichenfolgewert ersetzt werden.
Beispiel: die Spickzettelvariable namens "v1" hat den Wert "1,b,three", und das folgende Element wird erweitert:
<item ...> <repeated-subitem values="${v1}"> <subitem label="Step ${this}."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/> </subitem> </repeated-subitem> </item>In diesem Fall wird das Element etwa wie folgt erweitert:
<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 >
Jedes Element <action> beschreibt eine Aktion auf einem Spickzettel. Für das Element <action> gibt es die folgenden Attribute:
org.eclipse.jface.action.IAction
implementiert.
Wenn diese Aktion außerdem org.eclipse.ui.cheatsheets.ICheatSheetAction
implementiert, wird
sie über ihre Methode "run(String[],ICheatSheetManager)" aufgerufen, und die Parameter für den Spickzettelmanager und die Aktion werden an sie übergeben. Wenn dieses Attribut verwendet wird, muss immer auch das Attribut "pluginId" vorhanden sein. Es wird dringend empfohlen, dass Aktionen, die aus Spickzetteln heraus aufgerufen werden sollen, eine Ausgabe über die erfolgreiche bzw. fehlgeschlagene Ausführung melden sollen, falls die Ausführung der Aktion fehlschlagen könnte (beispielsweise aufgrund des Abbruchs der Aktion durch den Benutzer im Dialog). (Details finden Sie im Abschnitt zu
"org.eclipse.jface.action.Action.notifyResult(boolean)".)org.eclipse.ui.cheatsheets.ICheatSheetAction
implementieren, werden die Zeichenfolgewerte dieser Attribute an die Aktion übergeben, sobald sie aufgerufen wird. Sie können bis zu 9 Parameter an eine Spickzettelaktion übergeben (param1,
param2 usw.). Die bereitgestellten Parameter müssen mit dem Parameter 1 beginnen und fortlaufend nummeriert sein. Die Angabe von param2 ohne param1 ist demnach unzulässig. Wenn die Attributzeichenfolge das Format "${var}" hat, wird sie als Verweis
auf eine Spickzettelvariable var betrachtet. Der Wert der Bedingung ist dann der Wert der Variablen für den Spickzettel, der am Beginn der Ausführung des übergeordneten Elements <item> ermittelt wurde (bzw. eine leere Zeichenfolge, wenn die Variable zu diesem Zeitpunkt ungebunden war).command
<!ELEMENT command EMPTY> <!ATTLIST command serialization CDATA #REQUIRED returns CDATA #IMPLIED confirm ("true" | "false") "false" when CDATA #IMPLIED >
Jedes Element <command> beschreibt einen Befehl in einem Spickzettel. Für das Attribut <command> gibt es folgende Attribute:
Das folgende Beispiel zeigt ein Element mit einem Befehl, der ein Dialogfenster öffnet und das Ergebnis in der Spickzettelvariablen "result" speichert.
<item title="View Selection"> <description>Select a view which will be opened in the next step.</description> <command returns = "result" serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Select View,buttonLabel0=Package Explorer,message=Select a view ,buttonLabel1=Search View)"/> <onCompletion> Selected the ${result}. </onCompletion> </item>
onCompletion
<!ELEMENT onCompletion EMPTY> <!ATTLIST onCompletion >
Das Element <onCompletion> enthält Text, der angezeigt wird, nachdem ein Element abgeschlossen wurde. Dies ist besonders beim letzten Schritt des Spickzettels sinnvoll, um den Abschluss der gesamten Tasks mitzuteilen. Die Beschreibung besteht aus Text mit einfachen Formatierungstags, die dieselben Regeln wie für ein Element <description> befolgen müssen. Elemente <onCompletion> können außerdem Verweise auf Spickzettelvariablen mit dem Format "${var}" enthalten. Diese Verweise werden unter Verwendung des tatsächlichen Werts der Spickzettelvariablen var erweitert, sobald der entsprechende Schritt abgeschlossen wurde.
perform-when
<!ELEMENT perform-when ((action|command)+)> <!ATTLIST perform-when condition CDATA #REQUIRED >
Jedes Element <perform-when> beschreibt eine Aktion auf einem Spickzettel. Für das Element <perform-when> gibt es die folgenden Attribute:
Das Attribut condition für das Element <conditional-subitem> stellt einen Zeichenfolgewert zur Verfügung (dieser Wert stammt unveränderbar aus einer Spickzettelvariablen). Jedes untergeordnete Element <subitem> muss ein Attribut when mit einem distinkten Zeichenfolgewert haben. Wenn das Element erweitert wird, wird das Element <conditional-subitem> durch das Element <subitem> mit dem übereinstimmenden Wert ersetzt. Falls kein Element <subitem> mit einem übereinstimmenden Wert vorhanden ist, gilt dies als Fehler.
Beispiel: Die Spickzettelvariable namens "v1" hat den Wert "b", und das folgende Element wird erweitert:
<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" /> <command when="c" serialization="org.eclipse.search.ui.views.SearchView"/> </conditional-subitem> </subitem> </item>In diesem Fall wird die zweite Aktion ausgewählt, und das Element wird etwa wie folgt erweitert:
<item ...> <subitem label="Main step"> <action class="com.xyz.action2" pluginId="com.xyz" /> </subitem> </item>
Das folgende Beispiel ist eine sehr einfache Inhaltsdatei für einen Spickzettel und veranschaulicht die Verwendung von Unterelementen "command", "perform-when" und "conditional":
<?xml version="1.0" encoding="UTF-8"?> <cheatsheet title="Sample Cheat Sheet"> <intro> <description>A cheat sheet which demonstrates the use of perform-when and conditional subitems</description> </intro> <item title="View Selection"> <description>Select a view which will be opened in the following steps.</description> <command returns = "result" serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Select View,buttonLabel0=Package Explorer,message=Select a view ,buttonLabel1=Search View)"/> <onCompletion> Selected the ${result}. </onCompletion> </item> <item title="Close Views"> <description>Close the search view and package explorer if open</description> </item> <item title="Open the view from a perform when item" skip = "true"> <description>Uses perform when to open the view seleted previously.</description> <perform-when condition = "${result}"> <command when = "Package Explorer" serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.jdt.ui.PackageExplorer)"/> <command when = "Search View" serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.search.ui.views.SearchView)"/> </perform-when> </item> <item title="Close Views"> <description>Close the search view and package explorer if open</description> </item> <item title="Open the view from a perform when subitem"> <description>Uses perform when to open the view seleted previously.</description> <subitem label="Perform when subitem" skip = "true"> <perform-when condition = "${result}"> <command when = "Package Explorer" serialization="org.eclipse.jdt.ui.PackageExplorer"/> <command when = "Search View" serialization="org.eclipse.search.ui.views.SearchView"/> </perform-when> </subitem> </item> <item title="Close Views"> <description>Close the search view and package explorer if open</description> </item> <item title="Open the view from a conditional subitem"> <description>Uses perform when to open the view seleted previously.</description> <conditional-subitem condition="${result}"> <subitem when="Package Explorer" label="Open package explorer."> <command serialization = "org.eclipse.jdt.ui.PackageExplorer"/> </subitem> <subitem when="Search View" label="Open Search View"> <command serialization = "org.eclipse.search.ui.views.SearchView"/> </subitem> </conditional-subitem> </item> </cheatsheet>
Copyright (c) 2004, 2006 IBM Corporation und Andere.
Alle Rechte vorbehalten. Dieses Programm und sein Begleitmaterial werden gemäß den Bedingungen der "Eclipse Public License v1.0" zur Verfügung gestellt, die dieser Lieferung beiliegt und unter
http://www.eclipse.org/legal/epl-v10.html abgerufen werden kann.