Versjon 3.2
Dette dokumentet beskriver strukturen i innholdsfilen for en jukselapp som en serie av DTD-fragmenter (maskinlesbart XML-skjema).
cheatsheet
<!ELEMENT cheatsheet (intro, item+)> <!ATTLIST cheatsheet title CDATA #REQUIRED >
Elementet <cheatsheet> definerer hoveddelen av jukselappens innholdsfil. Dette er <cheatsheet>-attributtene:
intro
<!ELEMENT intro (description)> <!ATTLIST intro contextId CDATA #IMPLIED href CDATA #IMPLIED >
Elementet <intro> brukes til å beskrive jukselappintroduksjonen som skal vises. Underelementet <description> inneholder hoveddelen av introduksjonen. Dette er <intro>-attributtene:
description
<!ELEMENT description EMPTY> <!ATTLIST description >
Elementet <description> inneholder beskrivelsen av en jukselapp eller av et jukselappelement. Beskrivelsen består av tekst med enkle formateringskoder. Jukselappen formaterer og bestemmer layouten for teksten automatisk slik at den vises på en fornuftig måte i brukergrensesnittet. I teksten gjør par av kodene <b>...</b> at teksten blir gjengitt med fet skrift, og elementet <br/> kan brukes til å fremtvinge et linjeskift. Dette er de eneste formateringskodene som støttes nå (det kan bli tilføyd andre senere). Bestemte tegn i teksten har spesialbetydning for XML-analysatorer. Hvis du vil skrive "<", ">", "&", "'" og """ (spørsmålstegn), skriver du i stedet henholdsvis "<", ">", "&", "'" og """. Blanktegn (mellomrom og linjeskift) behandles som et ordskilletegn. Tilstøtende mellomrom og linjeskift behandles som en enkeltenhet og gjengis som ett enkelt mellomrom eller linjeskift. Blanktegn umiddelbart etter kodene <description> og <br/> blir ignorert, på samme måte som blanktegn umiddelbart før koden </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 >
Hvert <item>-element beskriver et toppnivåtrinn i en jukselapp. Et <item> kan inneholde <subitem>-elementer. Dette er <item>-attributtene:
Ved hjelp av org.eclipse.ui.cheatsheets.cheatSheetItemExtension kan ekstra tilpassede kontroller for elementet vises i brukergrensesnittet. Bidrag til dette utvidelsespunktet deklarerer navnene på tilleggsattributter med strengverdier som kan bli vist i <item>-elementer.
Enkle elementer har en beskrivelse og en valgfri handling eller kommando. I den vanlige presentasjonen blir titlene på jukselappelementer vist til brukeren det meste av tiden. Et elements beskrivelse blir bare vist mens trinnet er i ferd med å bli utført. Forekomsten av et <action>-, <command>- eller <perform-when>-element er knyttet til en knappe som brukeren kan trykke på for å utføre trinnets handling eller kommando. Hvis det ikke finnes noen handling eller kommando, må brukeren utføre trinnet manuelt og deretter oppgi at trinnet er fullført på en vellykket måte.
Trinn brytes ned i undertrinn slik det oppgis av <subitem>-underelementer. I motsetning til elementer, som brukeren må følge i streng rekkefølge, kan underelementene i et gitt element utføres i en hvilken som helst rekkefølge. Alle underelementer i et element må forsøkes (eller hoppes over) før neste trinn behandles. (Det betyr at handlinger som må utføres i en obligatorisk rekkefølge, ikke kan representeres som underelementer.)
Ved hjelp av et <conditional-subitem>-underelement er det mulig å skreddersy presentasjonen av et undertrinn i et trinn, basert på jukselappvariabler med verdier som kommer fra tidligere trinn. Et <repeated-subitem>-underelement tillater at et trinn inkluderer et sett av liknende undertrinn. Og igjen kan det nøyaktige settet av undertrinn være basert på jukselappvariabler med verdier fra tidligere trinn.
subitem
<!ELEMENT subitem ( [action|command|perform-when] )> <!ATTLIST subitem label CDATA #REQUIRED skip ("true" | "false") "false" when CDATA #IMPLIED >
Hvert <subitem>-element beskriver et undertrinn i en jukselapp. Et <subitem> har en enkel tekstetikett, men det har verken en lang beskrivelse eller andre underelementer. Dette er <subitem>-attributtene:
Underelementer kan ha en valgfri handling eller kommando. Forekomsten av et <action>-, <command>- eller <perform-when>-element er vanligvis knyttet til en knapp som brukeren kan trykke på for å utføre undertrinnets handling eller kommando. Hvis det ikke finnes noen handling eller kommando, må brukeren utføre undertrinnet manuelt og deretter oppgi at trinnet er fullført på en vellykket måte.
I motsetning til elementer, som må følges i streng rekkefølge, kan underelementene i et gitt element utføres i en hvilken som helst rekkefølge. Alle underelementer i et element må fullføres eller hoppes over før neste trinn behandles. (Det betyr at handlinger som må utføres i en obligatorisk rekkefølge, ikke bør representeres som underelementer.)
conditional-subitem
<!ELEMENT conditional-subitem (subitem+)> <!ATTLIST conditional-subitem condition CDATA #REQUIRED >
Hvert <conditional-subitem>-element beskriver et enkelt undertrinn med en form som kan variere basert på en betingelse på tidspunktet da elementet utvides. Dette er <conditional-subitem>-attributtene:
Attributtet condition i <conditional-subitem>-elementet oppgir en strengverdi (denne verdien kommer alltid fra en jukselappvariabel). Hver enkelt av de underordnede <subitem> må ha et when-attributt med en distinkt strengverdi. Når elementet er utvidet, blir <conditional-subitem>-elementet erstattet av <subitem>-elementet med den samsvarende verdien. Det blir betraktet som en feil hvis det ikke finnes noe <subitem>-element med en samsvarende verdi.
Hvis jukselappvariabelen "v1" for eksempel har verdien "b" når det følgende elementet utvides:
<item ...> <conditional-subitem condition="${v1}"> <subitem when="a" label="Step for A." /> <subitem when="b" label="Step for B." /> </conditional-subitem> </item>så velges det andre underelementet og elementet utvides til noe som likner på dette:
<item ...> <subitem label="Step for B."/> </item>
repeated-subitem
<!ELEMENT repeated-subitem (subitem)> <!ATTLIST repeated-subitem values CDATA #REQUIRED >
Hvert <repeated-subitem>-element beskriver et underelement som blir utvidet til 0, 1, eller mer liknende undertrinn. Dette er <repeated-subitem>-attributtene:
Attributtet values har en liste over strenger med komma som skilletegn. Den underordnede <subitem> oppgir malen. Når elementet er utvidet, blir <repeated-subitem>-elementet erstattet av kopier av <subitem>-elementet med forekomster av variabelen "this", erstattet av den tilsvarende strengverdien.
Hvis jukselappvariabelen "v1" for eksempel har verdien "1,b,three", blir det følgende elementet utvidet:
<item ...> <repeated-subitem values="${v1}"> <subitem label="Step ${this}."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/> </subitem> </repeated-subitem> </item>Deretter utvides elementet til noe som likner på dette:
<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 >
Hvert <action>-element beskriver en handling i en jukselapp. Dette er <action>-attributtene:
org.eclipse.jface.action.IAction
.
Hvis denne handlingen
også implementerer org.eclipse.ui.cheatsheets.ICheatSheetAction
, blir den startet via
metoden run(String[],ICheatSheetManager), og jukselappstyreren og
handlingsparameterne kan sendes til den. Attributtet pluginId
må være oppgitt når dette attributtet er oppgitt. Det anbefales på det sterkeste at handlinger
som er tenkt å skulle startes fra jukselapper, rapporterer resultatet som
suksess/mislykket hvis kjøringen av handlingen kan mislykkes (kanskje på grunn av at brukeren avbryter
handlingen fra dialogboksen). (Se
org.eclipse.jface.action.Action.notifyResult(boolean) hvis du vil vite mer.)org.eclipse.ui.cheatsheets.ICheatSheetAction
,
sendes strengverdiene for disse attributtene til handlingen når den startets. Du kan sende opptil
9 parametere til en jukselapphandling (param1, param2 og så videre). De oppgitte
parameterne må begynne med parameter 1 og være fortløpende. Det vil si at det er ulovlig
å oppgi param2 uten at param1 også er oppgitt. Hvis attributtstrengen har
formen "${var}", blir den betraktet som en referanse til
jukselappvariabelen var, og verdien av betingelsen vil være verdien av variabelen for
jukselappen ved starten av utføringen av elementet <item> i den (eller den tomme strengen
hvis variabelen er ubundet på dette tidspunktet).command
<!ELEMENT command EMPTY> <!ATTLIST command serialization CDATA #REQUIRED returns CDATA #IMPLIED confirm ("true" | "false") "false" when CDATA #IMPLIED >
Hvert <command>-element beskriver en kommando i en jukselapp. Dette er <command>-attributtene:
Nedenfor finner du et eksempel på et element med en kommando som åpner en dialogboks og lagrer resultatene i jukselappvariabelen "result".
<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 >
Elementet <onCompletion> inneholder tekste som blir vist når et element er fullført. Dette er spesielt nyttig i det siste trinnet av jukselappen for å godkjenne fullføringen av hele oppgaven. Beskrivelsen består av tekst med enkle formateringskoder som følger de samme reglene som for et <description>-element. <onCompletion>-elementene kan også inneholde referanser til jukselappvariabler i formen "${var}", som blir utvidet ved hjelp av den faktiske verdien av jukselappvariabelen var på det tidspunktet dette trinnet fullføres.
perform-when
<!ELEMENT perform-when ((action|command)+)> <!ATTLIST perform-when condition CDATA #REQUIRED >
Hvert <perform-when>-element beskriver en handling i en jukselapp. Dette er <perform-when>-attributtene:
Attributtet condition i <conditional-subitem>-elementet oppgir en strengverdi (denne verdien kommer alltid fra en jukselappvariabel). Hver enkelt av de underordnede <subitem> må ha et when-attributt med en distinkt strengverdi. Når elementet er utvidet, blir <conditional-subitem>-elementet erstattet av <subitem>-elementet med den samsvarende verdien. Det blir betraktet som en feil hvis det ikke finnes noe <subitem>-element med en samsvarende verdi.
Hvis jukselappvariabelen "v1" for eksempel har verdien "b" når det følgende elementet utvides:
<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>Deretter velges den andre handlingen og elementet utvides til noe som likner på dette:
<item ...> <subitem label="Main step"> <action class="com.xyz.action2" pluginId="com.xyz" /> </subitem> </item>
Nedenfor finner du et eksempel på en enkel innholdsfil for en jukselapp som demonstrerer bruken av command, perform-when og betingede underelementer.
<?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 and others.
All rights reserved. This program and the accompanying materials are made
available under the terms of the Eclipse Public License v1.0 which accompanies
this distribution, and is available at
http://www.eclipse.org/legal/epl-v10.html