Version 3.0
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. <cheatsheet> Es gibt folgende Attribute für das Element:
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 Spickzetteintrags. 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 "<", ">", "&", "'" und """ 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|perform-when] | (subitem|repeated-subitem|conditional-subitem)*))> <!ATTLIST item title CDATA #REQUIRED skip ("true" | "false") "false" contextId CDATA #IMPLIED href CDATA #IMPLIED >
Jedes Element <item> beschreibt einen Schritt der höchsten Ebene im Spickzettel. Das Element <item> ist entweder einfach oder kombiniert. <item> Es gibt folgende Attribute für das Element:
Die Erweiterung "org.eclipse.ui.cheatsheets.cheatSheetItemExtension" ermöglicht das Anzeigen zusätzlicher Steuerelemente für den Eintrag in der Benutzerschnittstelle. Ergänzungen für diesen Erweiterungspunkt deklarieren die Namen von zusätzlichen Attributen mit Zeichenfolgewerten, die für Elemente <item> elements angezeigt werden können.
Einfache Einträge haben eine Beschreibung und eine optionale Aktion. In der normalen Darstellung werden die Titel der Spickzetteleinträge meistens für den Benutzer angezeigt. Die Beschreibung eines Eintrags wird nur dann angezeigt, wenn der Prozess gerade ausgeführt wird. Einem vorhandenen Element <action> (oder <perform-when>) ist in der Regel eine Schaltfläche zugeordnet, durch deren Auswahl der Benutzer die Aktion des Schrittes ausführen kann. Wenn keine Aktion 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.
Kombinierte Schritte sind in Unterschritte aufgeteilt, was durch die Unterelemente <subitem> angegeben wird. Anders als Einträge, die der Benutzer in einer genauen Reihenfolge befolgen muss, können die Untereinträge eines Eintrags in einer beliebigen Reihenfolge ausgeführt werden. Alle Untereinträge innerhalb eines Eintrags müssen aufgerufen (oder übersprungen) werden, bevor mit dem nächsten Eintrag fortgefahren wird. (Dies bedeutet, dass Aktionen, die in einer bestimmten Reihenfolge ausgeführt werden müssen, nicht als Untereinträge 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|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 Untereinträge. Für das Element <subitem> gibt es die folgenden Attribute:
Untereinträge haben eine optionale Aktion. Einem vorhandenen Element <action> (oder <perform-when>) ist in der Regel eine Schaltfläche zugeordnet, durch deren Auswahl der Benutzer die Aktion des Unterschrittes ausführen kann. Wenn keine Aktion 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 Einträge, die in einer genauen Reihenfolge befolgt werden müssen, können die Untereinträge eines jeweiligen Eintrags in einer beliebigen Reihenfolge ausgeführt werden. Alle Untereinträge innerhalb eines Eintrags müssen aufgerufen (oder übersprungen) werden, bevor mit dem nächsten Eintrag fortgefahren wird. Dies bedeutet, dass Aktionen, die in einer bestimmten Reihenfolge ausgeführt werden müssen, nicht als Untereinträge 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 Eintrags 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 der Eintrag 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 der folgende Eintrag 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 der zweite Untereintrag ausgewählt, und der Eintrag 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 einen Untereintrag, der 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 der Eintrag 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 der folgende Eintrag 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 der Eintrag 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).perform-when
<!ELEMENT perform-when (action+)> <!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 der Eintrag 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 der folgende Eintrag 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" /> </conditional-subitem> </subitem> </item>In diesem Fall wird die zweite Aktion ausgewählt, und der Eintrag 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:
<?xml version="1.0" encoding="UTF-8"?> <cheatsheet title="Beispiel"> <intro> <description>Beispielspickzettel mit zwei Schritten.</description> </intro> <item title="Schritt 1"> <description>Dieser Schritt enthält eine Aktion.</description> <action class="com.xyz.myaction" pluginId="com.xyz"/> </item> <item title="Schritt 2"> <description>Dieser Schritt ist vollständig manuell.</description> </item> </cheatsheet>
Copyright (c) 2004 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.