Version 3.2
I det här dokumentet beskrivs strukturen på lathundens innehållsfil som en serie DTD-fragment (maskinläsbart XML-schema).
cheatsheet
<!ELEMENT cheatsheet (intro, item+)> <!ATTLIST cheatsheet title CDATA #REQUIRED >
<cheatsheet>-elementet definierar huvuddelen av lathundens innehållsfil. <cheatsheet>-attributen är följande:
intro
<!ELEMENT intro (description)> <!ATTLIST intro contextId CDATA #IMPLIED href CDATA #IMPLIED >
Du använder <intro>-elementet för att beskriva introduktionen till den lathund som ska visas. Underelementet <description> innehåller huvuddelen av introduktionen. <intro>-attributen är följande:
description
<!ELEMENT description EMPTY> <!ATTLIST description >
<description>-elementet innehåller beskrivningen av en lathund eller ett lathundsobjekt. Beskrivningen består av text som är blandad med enkla formateringsmärkord. Lathunden formaterar och ordnar texten så att den ser acceptabel ut i användargränssnittet. Inuti texten gör märkorden <b>...</b> att den inneslutna texten visas i fetstilt format. Du kan använda <br/>-elementet för att skapa en hård radbrytning. Det är de enda formateringsmärkorden som kan användas för tillfället (andra kan dock komma att läggas till i framtiden). Vissa tecken i texten har särskilda betydelser för XML-tolkning, särskilt "<", ">", "&", "'" och """ (citattecken). Skriv i stället "<", ">", "&", "'" och """. Tomrum (blanktecken och radbrytningar) behandlas som ordavgränsare. Närliggande blanktecken och radbrytningar behandlas som en enskild enhet och återges som ett enskilt blanktecken eller en enskild radbrytning. Tomrum omedelbart efter märkorden <description> och <br/> ignoreras, liksom tomrum omedelbart före märkordet </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 >
Varje <item>-element beskriver ett steg på den översta nivån i en lathund. Ett <item> kan innehålla <subitem>-element. <item>-attributen är följande:
org.eclipse.ui.cheatsheets.cheatSheetItemExtension tillåter att ytterligare anpassade kontroller för objektet visas i användargränssnittet. Bidrag till den här utökningspunkten deklarerar namnen på ytterligare strängvärdesattribut som kan visas på <item>-element.
Enkla objekt har en beskrivning och en valfri åtgärd eller kommando. I en vanlig presentation brukar rubrikerna på lathundssobjekt visas för användaren. Beskrivningen av ett objekt visas endast när steget körs. Ett <action>-, <command>- eller <perform-when>-element är associerat med en knapp som användaren kan trycka på för att utföra stegåtgärden eller -kommandot. Om det inte finns någon åtgärd eller kommando måste användaren utföra steget manuellt och sedan offentligt ange att steget är utfört.
Steg delas upp i delsteg enligt vad som anges av <subitem>-delelementen. Till skillnad från objekt, som användaren måste följa i rätt ordning, kan delelement för ett visst objekt utföras i vilken ordning som helst. Alla delobjekt i ett objekt måste testas (eller hoppas över) innan användaren kan gå vidare till nästa objekt. (Det innebär att åtgärder som måste utföras i en viss ordning inte kan visas som delobjekt.)
Ett <conditional-subitem>-delelement tillåter att ett steg anpassar presentationen av ett delsteg baserat på lathundssvariabler vars värden angavs i tidigare steg. Ett <repeated-subitem>-delelement tillåter att ett steg innehåller en uppsättning liknande delsteg. Även här kan den exakta uppsättningen steg baseras på lathundssvariabler vars värden angavs i tidigare steg.
subitem
<!ELEMENT subitem ( [action|command|perform-when] )> <!ATTLIST subitem label CDATA #REQUIRED skip ("true" | "false") "false" when CDATA #IMPLIED >
Varje <subitem>-element beskriver ett delsteg i en lathund. Ett <subitem>-element innehåller en enkel textetikett, men har varken en lång beskrivning eller ytterligare delobjekt. <subitem>-attribut är följande:
Delobjekt kan ha en valfri åtgärd eller kommando. Ett <action>-, <command>- eller <perform-when>-element är vanligen associerat med en knapp som användaren kan trycka på för att utföra delstegsåtgärden eller -kommandot. Om det inte finns någon åtgärd eller kommando måste användaren utföra delsteget manuellt och sedan offentligt ange att steget är utfört.
Till skillnad från objekt, som användaren måste följa i rätt ordning, kan delobjekt för ett visst objekt utföras i vilken ordning som helst. Alla delobjekt i ett objekt måste slutföras eller hoppas över innan användaren kan gå vidare till nästa objekt. (Det innebär att åtgärder som måste utföras i en viss ordning inte kan visas som delobjekt.)
conditional-subitem
<!ELEMENT conditional-subitem (subitem+)> <!ATTLIST conditional-subitem condition CDATA #REQUIRED >
Varje <conditional-subitem>-element beskriver ett enskilt delsteg vars form kan skilja sig åt, baserat på ett villkor som är känt vid den tidpunkt då objektet utökas. <conditional-subitem>-attributen är följande:
condition-attributet i <conditional-subitem>-elementet ger ett strängvärde (detta värde kommer alltid från en lathundssvariabel). Alla underordnade <subitem>-element måste ha ett when-attribut med ett tydligt strängvärde. När objektet utökas ersätts <conditional-subitem>-elementet av <subitem>-elementet med det matchande värdet. Om det inte finns något <subitem>-element med matchande värde, uppstår ett fel.
Exempel: Om lathundssvariabeln med namnet "v1" har värdet "b" när följande objekt utökas:
<item ...> <conditional-subitem condition="${v1}"> <subitem when="a" label="Steg för A." /> <subitem when="b" label="Steg för B." /> </conditional-subitem> </item>markeras det andra delobjektet och objektet utökas till något som motsvarar:
<item ...> <subitem label="Steg för B."/> </item>
repeated-subitem
<!ELEMENT repeated-subitem (subitem)> <!ATTLIST repeated-subitem values CDATA #REQUIRED >
Varje <repeated-subitem>-element beskriver ett delobjekt som utökas till 0, 1 eller fler liknande delsteg. <repeated-subitem>-attributen är följande:
values-attributet visar en lista med kommaavgränsade strängar. Det underordnade <subitem>-elementet anger mallen. När objektet utökas ersätts <repeated-subitem>-elementet av kopior av <subitem>-elementet samtidigt som förekomster av variabeln "this" ersätts av motsvarande strängvärde.
Exempel: Om lathundssvariabeln med namnet "v1" har värdet "1,b,tre" när följande objekt utökas:
<item ...> <repeated-subitem values="${v1}"> <subitem label="Steg ${this}."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/> </subitem> </repeated-subitem> </item>utökas objektet till något som motsvarar:
<item ...> <subitem label="Steg 1."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="1"/> </subitem> <subitem label="Steg b."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="b"/> </subitem> <subitem label="Steg tre."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="tre"/> </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 >
Varje <action>-element beskriver en åtgärd i en lathund. <action>-attributen är följande:
org.eclipse.jface.action.IAction
.
Om den här åtgärden även implementerar org.eclipse.ui.cheatsheets.ICheatSheetAction
anropas den via sin run(String[],ICheatSheetManager)-metod och
får lathundsshanteraren och åtgärdsparametrarna. pluginId-attributet
måste finnas om det här attributet finns. Vi rekommenderar att alla åtgärder som ska anropas från lathunden
rapporterar om åtgärden lyckades eller inte, om det finns en risk att körningen av åtgärden misslyckas (till
exempel för att användaren avbröt åtgärden från dialogrutan). (Mer
information finns i org.eclipse.jface.action.Action.notifyResult(boolesk).)org.eclipse.ui.cheatsheets.ICheatSheetAction
,
överförs strängvärdena för dessa attribut till åtgärden när
den anropas. Du kan överföra upp till 9 parametrar till en lathundssåtgärd (param1,
param2 m.m.). De angivna parametrarna måste börja med parameter 1
och fortsätta i nummerordning. Det går inte att ange param2 utan att param1
också finns närvarande. Om attributsträngen har formen "${var}",
räknas den som en referens till lathundssvariabeln var. Värdet
på villkoret är värdet på variabeln för lathunden i
början av körningen av <item>-elementet (eller den tomma
strängen om variabeln är obunden vid den tidpunkten).command
<!ELEMENT command EMPTY> <!ATTLIST command serialization CDATA #REQUIRED returns CDATA #IMPLIED confirm ("true" | "false") "false" when CDATA #IMPLIED >
Varje <command>-element beskriver ett kommando i en lathund. <command>-attribut är följande:
Nedan är ett exempel på ett objekt med ett kommando som öppnar en dialogruta och lagrar resultatet i lathundsvariabeln "result".
<item title="Visa urval"> <description>Välj en vy som öppnas i nästa steg.</description> <command returns = "result" serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Select View,buttonLabel0=Package Explorer,message=Välj en vy ,buttonLabel1=Sökvy)"/> <onCompletion> Valde ${result}. </onCompletion> </item>
onCompletion
<!ELEMENT onCompletion EMPTY> <!ATTLIST onCompletion >
Elementet <onCompletion> innehåller text som visas när objektet är slutfört. Det är särskilt praktiskt för att ange att hela uppgiften slutförts i det slutliga steget i lathunden. Beskrivningen består av text som är blandad med enkla formateringsmärkord som följer samma regler som gäller för elementet <description>. <onCompletion>-element kan även innehålla referenser till lathundsvariabler i formatet "${var}" som utökas med det faktiska värdet för lathundsvariablen var när steget slutförs.
perform-when
<!ELEMENT perform-when ((action|command)+)> <!ATTLIST perform-when condition CDATA #REQUIRED >
Varje <perform-when>-element beskriver en åtgärd i en lathund. <perform-when>-attributen är följande:
condition-attributet i <conditional-subitem>-elementet ger ett strängvärde (detta värde kommer alltid från en lathundssvariabel). Alla underordnade <subitem>-element måste ha ett when-attribut med ett tydligt strängvärde. När objektet utökas ersätts <conditional-subitem>-elementet av <subitem>-elementet med det matchande värdet. Om det inte finns något <subitem>-element med matchande värde, uppstår ett fel.
Exempel: Om lathundssvariabeln med namnet "v1" har värdet "b" när följande objekt utökas:
<item ...> <subitem label="Huvudsteg"> <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>markeras den andra åtgärden och objektet utökas till något som motsvarar:
<item ...> <subitem label="Huvudsteg"> <action class="com.xyz.action2" pluginId="com.xyz" /> </subitem> </item>
Följande är ett exempel på en mycket enkel innehållsfil för en lathund som visar hur commands-, perform-when- och conditional-delobjekt används.
<?xml version="1.0" encoding="UTF-8"?> <cheatsheet title="Exempel på lathund"> <intro> <description>En lathund som visar hur perform-when- och conditional-delobjekt används</description> </intro> <item title="Visa urval"> <description>Välj en vy som öppnas i följande steg.</description> <command returns = "result" serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Select View,buttonLabel0=Package Explorer,message=Välj en vy ,buttonLabel1=Sökvy)"/> <onCompletion> Valde ${result}. </onCompletion> </item> <item title="Stäng vyer"> <description>Stäng sökvyn och paketutforskaren om de är öppna</description> </item> <item title="Öppna vyn från ett perform-when-objekt" skip = "true"> <description>perform-when används till att öppna den vy som valdes tidigare</description> <perform-when condition = "${result}"> <command when = "Paketutforskaren" serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.jdt.ui.PackageExplorer)"/> <command when = "Sökvy" serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.search.ui.views.SearchView)"/> </perform-when> </item> <item title="Stäng vyer"> <description>Stäng sökvyn och paketutforskaren om de är öppna</description> </item> <item title="Öppna vyn från ett perform-when-delobjekt"> <description>perform-when används till att öppna den vy som valdes tidigare</description> <subitem label="Perform-when-delobjekt" skip = "true"> <perform-when condition = "${result}"> <command when = "Paketutforskaren" serialization="org.eclipse.jdt.ui.PackageExplorer"/> <command when = "Sökvy" serialization="org.eclipse.search.ui.views.SearchView"/> </perform-when> </subitem> </item> <item title="Stäng vyer"> <description>Stäng sökvyn och paketutforskaren om de är öppna</description> </item> <item title="Öppna vyn från ett conditional-delobjekt"> <description>perform-when används till att öppna den vy som valdes tidigare</description> <conditional-subitem condition="${result}"> <subitem when="Paketutforskaren" label="öppna paketutforskaren."> <command serialization = "org.eclipse.jdt.ui.PackageExplorer"/> </subitem> <subitem when="Sökvy" label="Öppna sökvyn"> <command serialization = "org.eclipse.search.ui.views.SearchView"/> </subitem> </conditional-subitem> </item> </cheatsheet>
Copyright (c) 2004, 2006 IBM Corporation and others.
All rights reserved. Detta program och medföljande material tillhandahålls under villkoren för Eclipse Public License v1.0 som medföljer denna distribution och finns tillgänglig på
http://www.eclipse.org/legal/epl-v10.html