Snydeark guider brugeren gennem en serie komplekse opgaver for at opnå et overordnet mål.
Et snydeark kan f.eks. bruges til at føre brugeren gennem alle de trin, der kræves for at
oprette, kompilere og udføre et enkelt Java-program. Snydeark startes fra menupunktet
Hjælp > Snydeark....
Snydeark kan også startet fra en introduktionsside.
Snydeark defineres med udvidelsespunktet org.eclipse.ui.cheatsheets.cheatSheetContent. Indholdet af selve snydearket defineres i en separat fil, så det lettere kan oversættes til andre sprog.
Det er forholdsvist enkelt at bidrage med et snydeark. Det følgende er et snydeark, som kommer fra JDT'en, og som bruges til at bygge et enkelt Java-program.
<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> ...Du kan angive et navn, en beskrivelse og en id for snydearket på samme måde som for andre arbejdsbænksbidrag. Navnet op beskrivelsen vises, når brugeren åbner listen
Den virkelige arbejde med snydeark udføres i indholdsfilen. Indholdsfilen er en XML-fil, hvis navn og placering er angivet i attributten contentFile. Stien til filen er relativ i forhold til plugin'ens bibliotek. Bemærk brugen af variablen $nl$ i biblioteksnavnet, som betyder, at filen bliver placeret i et bibliotek, der er specifikt for det sprog, som målmiljøet bruger.
Selve filformatet omfatter oversigtsoplysninger om snydearket efterfulgt af en beskrivelse af hvert trin, kaldet et element, som brugeren skal udføre. Når et element er allermest enkelt, er det blot en detaljeret beskrivelse af det trin, som brugeren skal udføre. Et element kan imidlertid også angive en funktion, der skal udføre trinet på brugerens vegne. I det følgende vises den første del af indholdsfilen (HelloWorld.xml) for Java-snydearket.
<?xml version="1.0" encoding="UTF-8" ?> <cheatsheet title="Enkelt Java-program"> <intro href="/org.eclipse.ui.cheatsheets.doc/tasks/tcheatst.htm"> <description> Velkommen til Java-øveprogrammet Hello, World. Her får du at vide, hvordan du bygger det berømte "hello world"-program og afprøver det. Du opretter et Java-projekt og en Java-klasse, som udskriver "hello world" på konsollen, når det udføres. Lad os komme i gang! </description> </intro> <item href="/org.eclipse.platform.doc.user/concepts/concepts-4.htm" title="Åbn Java-perspektiv"> <action pluginId="org.eclipse.ui.cheatsheets" class="org.eclipse.ui.internal.cheatsheets.actions.OpenPerspective" param1="org.eclipse.jdt.ui.JavaPerspective"/> <description> Vælg Vindue->Åbn perspektiv->Java på menulinjen øverst på arbejdsbænken. Dette trin ændrer perspektivet, så Eclipse-arbejdsbænken indstilles til Java-udvikling. Klik på "Klik for at udføre", hvis perspektivet "Java" skal åbnes automatisk. </description> </item> ...
Titlen og indledningen vises øverst på snydearket. Derefter beskrives elementerne. Det første element for snydearket beskriver, hvordan Java-perspektivet åbnes. Som alternativ angiver attributten action en klasse, der kan bruges til at udføre funktionen på brugerens vegne. Klassen skal implementere IAction. Det er nyttigt, fordi det giver dig mulighed for at genbruge de funktionsklasser, der er skrevet for menu- eller værktøjslinjebidrag.
Klassen for funktionen kan eventuelt implementere ICheatSheetAction, hvis funktionen bruger parametre eller skal være opmærksom på snydearket og dets tilstand. I dette tilfælde sendes et array af parametre og en reference til ICheatSheetManager til funktionen, så den kan anmode om flere oplysninger om snydearket. De eventuelle nødvendige parametre kan sendes til funktionens udførelsesmetode vha. attributterne paramN.
Det anbefales stærkt, at funktioner, der startes fra snydeark, rapporterer om resultatet af en funktion. Resultatet kan være, at funktionen er udført eller ikke er udført. Brugeren annullerer f.eks. funktionen via dens dialogboks. Der er flere oplysninger i IAction.notifyResult(boolean).
Elementer behøver ikke at definere funktioner. Hvis brugeren skal udføre elementet manuelt, behøver du ikke at angive en funktion. Nedenfor vises det tredje trin i Java-snydearket, som blot fortæller brugeren, hvordan et enkelt program kodes. Hvis der ikke er angivet en funktion, skal elementbeskrivelsen instruere brugeren i at trykke på den relevante knap, når opgaven er udført.
<item href="/org.eclipse.jdt.doc.user/tasks/tasks-54.htm" title="Tilføj linjen System.out.println i den overordnede metode"> <description> Nu, da du har oprettet en HelloWorld-klasse, skal du i metoden "public static void main" tilføje følgende sætning: System.out.println("Hello world!"); og gemme ændringerne. Klik på "Klik for at afslutte" nedenfor, når du er færdig. </description> </item>Yderligere attributter styrer, om elementet kan springes over, og hvilket dokument der skal åbnes, hvis brugeren anmoder om hjælp i løbet af trinnet. Der er en beskrivelse af alle de attributter, der kan defineres i et snydeark i dokumentationen til udvidelsespunktet org.eclipse.ui.cheatsheets.cheatSheetContent.
Du kan definere underelementer for at organisere præsentationen af et element yderligere. I modsætning til elementer behøver elementer ikke at blive besøgt i en bestemt rækkefølge. Underelementer kan også definere funktioner, som automatisk udfører underopgaven for brugeren. Underelementfunktioner beskrives på samme måde som elementfunktioner.
Betingede udtryk kan bruges til at definere snydearkselementer, hvis indhold eller funktionsmåde afhænger af, at en bestemt betingelse er sand. Betingelser beskrives i elementet condition for et underelement med vilkårlige strengværdier, der sammenlignes med attributten when for hvert valg. Betingelser refererer typisk til snydearksvariabler med formatet ${var}, hvor var refererer til navnet på en snydearksvariabel. Følgende er eksempler på, hvordan betingede udtryk fungerer.
Betingede underelementer kan bruges til at vælge et underelement fra en liste med mulige underelementer. Kun det første underelement, hvis when-attribut matcher betingelsesattributten, inkluderes i snydearket. Eksempel:
<item ...> <conditional-subitem condition="${v1}"> <subitem when="a" label="Trin for A." /> <subitem when="b" label="Trin for B." /> </conditional-subitem> </item>Dette element angiver to mulige underelementer, som afhænger værdien af variablen v1. Hvis variabelværdien er a, inkluderes det første underelement. Hvis variabelværdien er b, inkluderes det andet underelement. Hvis variablen ikke er nogen af værdierne, antages det at være en fejl.
Betingede funktioner ligner betingede underelementer. Elementet perform-when angiver en betingelse for at udføre en funktion fra listen med mulige funktioner. Betingelsen beskrives på samme måde med en vilkårlig streng, som ofte refererer til en variabel. Den funktion, hvis when-attribut matcher betingelsen, bliver udført. Eksempel:
<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>Den funktion, der skal udføres, vælges på basis af værdien af variablen v1. Hvis variabelværdien hverken er a eller b, antages det at være en fejl.
Gentagne underelementer beskriver et underelement, der kan udvides til 0, 1 eller flere lignende undertrin. Undertrinene gøres individuelle med specialvariablen ${this}. Denne variabel erstattes med de værdier, der angives i attributten values. Attributten values er en streng af værdier, der er adskilt med kommaer. En variabel, der udvides til en liste med værdier, kan bruges i attributten values. Eksempel:
<item ...> <repeated-subitem values="${v1}"> <subitem label="Trin ${this}" /> </repeated-subitem> </item>Hvis værdien af variablen er 1,b,tre, vises der tre underelementer i snydearket, som har hver sin entydige etiket ("Trin 1," "Trin b," "Trin tre"). Variablen kan bruges i etiketten eller i funktionsparameterværdien. Der kan også oprettes adgang til den fra ICheatSheetManager, mens en funktion udføres.
Du kan i nogle tilfælde have brug for at ændre andre dele af din brugergrænseflade, hvis et snydeark er aktivt. Du kan f.eks. have en editor, der viser specielle annotationer, hvis et snydeark fører en bruger gennem en redigeringsopgave. I dette tilfælde kan du angive en lytter som en attribut for snydearket. Lytterattributten skal være det fuldstændige navn på en Java-klasse, der er underklasse af CheatSheetListener. Lyttere modtager beskeder sammen med en ICheatSheetEvent, når der sker en ændring i et snydearks livscyklus, som f.eks. når det åbnes, lukkes eller afsluttes.
Udvidelsen org.eclipse.ui.cheatsheets.cheatSheetItemExtension kan bruges til at bidrage med vilkårlige attributter til et snydeark, som allerede findes. Formålet med udvidelsespunktet er at give en plugin mulighed for at tilføje flere knapper, som kan hjælpe brugeren med et givet trin. De ekstra knapper vises ved siden af hjælpeikonen.
Du bruger denne mekanisme ved at definere en vilkårlig attribut i en elementdefinition i XML-filen til snydearket. Attributnavnet sammenlignes med eventuelle attributter, som kommer fra udvidelser til org.eclipse.ui.cheatsheets.cheatSheetItemExtension. Der er flere oplysninger i dokumentation til udvidelsespunktet.
Arbejd med snydeark
Opret sammensatte snydeark
Retningslinjer for udarbejdelse
Udvidelsespunktet
org.eclipse.ui.cheatsheets.cheatSheetContent
Specifikation af indholdsfil for snydeark