Versie 3.2
In dit document vindt u een beschrijving van de hulpbladbestandsstructuur als een reeks DTD-fragmenten (door computer te lezen XML-schema).
cheatsheet
<!ELEMENT cheatsheet (intro, item+)> <!ATTLIST cheatsheet title CDATA #REQUIRED >
Met het element <cheatsheet> (hulpblad) definieert u de inhoud van het bestand met de content van het hulpblad. Kenmerken van <cheatsheet> zijn:
intro
<!ELEMENT intro (description)> <!ATTLIST intro contextId CDATA #IMPLIED href CDATA #IMPLIED >
Het element <intro> wordt gebruikt om een beschrijving weer te geven als inleiding voor het hulpblad. Het subelement <description> (beschrijving) bevat de tekst van de inleiding. Kenmerken van <intro> zijn:
description
<!ELEMENT description EMPTY> <!ATTLIST description >
Het element <description> bevat de beschrijving van een hulpblad of een hulpbladitem. De beschrijving bestaat uit tekst die her en der is voorzien van eenvoudige opmaaktags. De tekst wordt door het hulpblad automatisch zo ingedeeld en opgemaakt, dat deze er netjes uitziet in de gebruikersinterface. In de tekst kunt u de tags <b>...</b> gebruiken om de tekst tussen de tags vetgedrukt weer te geven. Met het element <br/> forceert u een regeleinde. Dit zijn de enige opmaaktags die momenteel worden ondersteund (mogelijk worden in de toekomst ook andere tags ondersteund). Bepaalde tekens in de tekst hebben een speciale betekenis voor XML-parsers. In plaats van de tekens "<", ">", "&", "'" en """ (vraagteken) dient u respectievelijk "<", ">", "&", "'" en """ te gebruiken. Witruimten (spaties en regeleinden) worden behandeld als woordscheidingstekens. Aangrenzende spaties en regeleinden worden behandeld als een afzonderlijke eenheid en worden weergegeven als één spatie of regeleinde. Witruimten direct na de tags <description> en <br/> worden genegeerd, evenals witruimten direct vóór de 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 >
Elk <item>-element vormt een beschrijving van één stap van het hoogste niveau in een hulpblad. Het item <item> kan elementen van het type <subitem> bevatten. Kenmerken van <item> zijn:
In org.eclipse.ui.cheatsheets.cheatSheetItemExtension kunt u aanvullende aangepaste besturingselementen opgeven voor het item dat in de gebruikersinterface wordt weergegeven. Bijdragen aan dit extensiepunt bevatten declaraties van de namen van aanvullende, tekenreekskenmerken die worden weergegeven via <item>-elementen.
Eenvoudige items bevatten een beschrijving en een optionele actie of opdracht. Gewoonlijk zijn de titels van hulpbladitems het grootste deel van de tijd zichtbaar voor de gebruiker. De beschrijving van een item wordt alleen afgebeeld terwijl de stap wordt uitgevoerd. De aanwezigheid van het element <action>, <command> (of <perform-when>) wordt gewoonlijk gekoppeld aan een knop waarop kan worden geklikt om de bijbehorende actie of opdracht uit te voeren. Als er geen actie of opdracht aanwezig is, moet de gebruiker de desbetreffende stap handmatig uitvoeren en vervolgens aangeven dat de stap is voltooid.
Stappen kunnen worden onderverdeeld in substappen, die worden opgegeven in <subitem>-subelementen. In tegenstelling tot items, die door de gebruiker in de juiste volgorde moeten worden uitgevoerd, kunnen subitems van een gegeven item in een willekeurige volgorde worden uitgevoerd. Alle subitems in een item moeten worden uitgevoerd (of overgeslagen) voordat het volgende item wordt uitgevoerd. (Oftewel, acties die in een bepaalde volgorde moeten worden uitgevoerd, kunnen niet worden gedefinieerd als subitems.)
Met het subelement <conditional-subitem> kunt u de presentatie van een substap aanpassen op basis van hulpbladvariabelen waarvan de waarden in eerdere stappen zijn verkregen. Met het subelement <repeated-subitem> kunt u een reeks vergelijkbare substappen in een stap opnemen. Ook hierbij kan de exacte reeks substappen worden gebaseerd op hulpbladvariabelen waarvan de waarden in eerdere stappen zijn verkregen.
subitem
<!ELEMENT subitem ( [action|command|perform-when] )> <!ATTLIST subitem label CDATA #REQUIRED skip ("true" | "false") "false" when CDATA #IMPLIED >
Elk element <subitem> vormt een beschrijving van een substap in een hulpblad. Een <subitem> is voorzien van een eenvoudig tekstlabel, maar kan verder geen lange beschrijving of subitems bevatten. Kenmerken van <subitem> zijn:
Subitems kunnen een optionele actie of opdracht bevatten. De aanwezigheid van het element <action>, <command> of <perform-when> wordt gewoonlijk gekoppeld aan een knop waarop de gebruiker kan klikken om de bijbehorende actie of opdracht uit te voeren. Als er geen actie of opdracht bestaat, moet de gebruiker de desbetreffende substap handmatig uitvoeren en vervolgens aangeven dat de stap is voltooid.
In tegenstelling tot items, die door de gebruiker in de juiste volgorde moeten worden uitgevoerd, kunnen subitems van een gegeven item in willekeurige volgorde worden uitgevoerd. Alle subitems in een item moeten worden voltooid (of overgeslagen) voordat het volgende item wordt uitgevoerd. (Oftewel, acties die in een bepaalde volgorde moeten worden uitgevoerd, kunnen niet worden gedefinieerd als subitems.)
conditional-subitem
<!ELEMENT conditional-subitem (subitem+)> <!ATTLIST conditional-subitem condition CDATA #REQUIRED >
Een element <conditional-subitem> bevat een beschrijving van één substap waarvan de vorm kan verschillen, afhankelijk van een voorwaarde die bekend wordt wanneer het item wordt uitgebreid. Kenmerken van <conditional-subitem> zijn:
Het kenmerk condition van het element <conditional-subitem> biedt een tekenreekswaarde (deze waarde is altijd afkomstig van een hulpbladvariabele). Alle onderliggende <subitemelementen> moeten het kenmerk when met een unieke tekenreekswaarde bevatten. Wanneer het item wordt uitgebreid, wordt het <conditional-subitem>-element vervangen door het <subitem>-element met de overeenkomende waarde. Als er geen <subitem>-element met een overeenkomende waarde is, wordt dit door het programma gezien als een fout.
Als de hulpbladvariabele "v1" de waarde "b" heeft wanneer het volgende item wordt uitgebreid
<item ...> <conditional-subitem condition="${v1}"> <subitem when="a" label="Stap voor A." /> <subitem when="b" label="Stap voor B." /> </conditional-subitem> </item>dan wordt het tweede subitem geselecteerd en wordt het item ongeveer als volgt uitgebreid:
<item ...> <subitem label="Stap voor B."/> </item>
repeated-subitem
<!ELEMENT repeated-subitem (subitem)> <!ATTLIST repeated-subitem values CDATA #REQUIRED >
Elk <repeated-subitem>-element beschrijft een subitem dat kan worden uitgebreid met 0, 1 of meer soortgelijke substappen. Kenmerken van <repeated-subitem> zijn:
Het kenmerk values biedt een lijst met waarden die door komma's zijn gescheiden; de sjabloon is gebaseerd op het onderliggende element <subitem>. Wanneer het item wordt uitgebreid, wordt het element <repeated-subitem> vervangen door kopieën van het element <subitem> en worden voorvallen van de variabele "this" vervangen door de bijbehorende tekenreekswaarde.
Als de hulpbladvariabele "v1" de waarde "1,b,drie" wanneer het volgende item wordt uitgebreid
<item ...> <repeated-subitem values="${v1}"> <subitem label="Stap ${this}."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/> </subitem> </repeated-subitem> </item>dan wordt het item ongeveer als volgt uitgebreid:
<item ...> <subitem label="Stap 1."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="1"/> </subitem> <subitem label="Stap b."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="b"/> </subitem> <subitem label="Stap drie."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="drie"/> </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 >
Elk element <action> staat voor een actie in een hulpblad. Kenmerken van <action> zijn:
org.eclipse.jface.action.IAction
wordt geïmplementeerd.
Als met deze actie ook org.eclipse.ui.cheatsheets.ICheatSheetAction
wordt geïmplementeerd,
wordt deze aangeroepen via de bijbehorende methode run(String[],ICheatSheetManager) en doorgegeven
aan de hulpbladmanager en actieparameters. Als dit kenmerk aanwezig is, moet ook het kenmerk
pluginId aanwezig zijn. Het is raadzaam om bij acties die worden aangeroepen via hulpbladen
het resultaat van de actie (geslaagd of mislukt) te laten rapporteren als er een kans is dat de actie
mislukt, bijvoorbeeld omdat de gebruiker de actie vanuit het dialoogvenster annuleert. (Zie
org.eclipse.jface.action.Action.notifyResult(boolean) voor meer informatie.)org.eclipse.ui.cheatsheets.ICheatSheetAction
worden
de tekenreekswaarden van deze attibruten doorgegeven aan de actie wanneer deze wordt aangeroepen. U kunt maximaal
9 parameters doorgeven aan een hulpbladactie (param1, param2, enzovoort). De opgegeven parameters
moet beginnen bij parameter 1 en oplopend worden genummerd. Het is niet toegestaan param2 op te geven voordat param1
is gedefinieerd. Als de tekenreeks van het kenmerk "${var}" bevat,
wordt deze gezien als verwijzing naar een hulpbladvariabele var. De waarde
van de voorwaarde wordt dan de waarde van de variabele voor het hulpblad aan
het begin van uitvoering van het bovenliggende element <item> (of de lege
tekenreeks als de variabele op dat tijdstip ongebonden is).command
<!ELEMENT command EMPTY> <!ATTLIST command serialization CDATA #REQUIRED returns CDATA #IMPLIED confirm ("true" | "false") "false" when CDATA #IMPLIED >
Elk <command>-element staat voor een beschrijving van een opdracht in een hulpblad. De kenmerken van <command> zijn als volgt:
Hieronder vindt u een voorbeeld van een item met een opdracht die ervoor zorgt dat er een dialoogvenster wordt geopend en dat het resultaat wordt opgeslagen in de hulpbladvariabele "result".
<item title="View selecteren"> <description>Selecteer een view die in de volgende stap wordt geopend.</description> <command returns = "result" serialization="org.eclipse.ui.dialogs.openMessageDialog(title=View selecteren,buttonLabel0=Pakketverkenner,message=Selecteer een view,buttonLabel1=View Zoeken)"/> <onCompletion> View ${result} geselecteerd. </onCompletion> </item>
onCompletion
<!ELEMENT onCompletion EMPTY> <!ATTLIST onCompletion >
Het element <onCompletion> bevat tekst die wordt weergegeven wanneer een item is voltooid. Dit is vooral handig in de laatste stap van het hulpblad om aan te geven dat de hele taak is afgerond. De beschrijving bestaat uit tekst die her en der is voorzien van eenvoudige opmaakcodes volgens dezelfde regels als voor <description>-elementen. <onCompletion>-elementen kunnen ook verwijzingen bevatten naar hulpbladvariabelen in de notatie "${var}", die bij voltooiing van deze stap worden uitgebreid met de werkelijke waarde van de hulpbladvariabele var.
perform-when
<!ELEMENT perform-when ((action|command)+)> <!ATTLIST perform-when condition CDATA #REQUIRED >
Elk element <perform-when> staat voor een beschrijving van een actie in een hulpblad. Kenmerken van <perform-when> zijn:
Het kenmerk condition van het element <conditional-subitem> biedt een tekenreekswaarde (deze waarde is altijd afkomstig van een hulpbladvariabele). Alle onderliggende <subitemelementen> moeten het kenmerk when met een unieke tekenreekswaarde bevatten. Wanneer het item wordt uitgebreid, wordt het <conditional-subitem>-element vervangen door het <subitem>-element met de overeenkomende waarde. Als er geen <subitem>-element met een overeenkomende waarde is, wordt dit door het programma gezien als een fout.
Als de hulpbladvariabele "v1" de waarde "b" heeft wanneer het volgende item wordt uitgebreid
<item ...> <subitem label="Hoofdstap"> <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>dan wordt de tweede actie geselecteerd en wordt het item ongeveer als volgt uitgebreid:
<item ...> <subitem label="Hoofdstap"> <action class="com.xyz.action2" pluginId="com.xyz" /> </subitem> </item>
Hieronder ziet u een voorbeeld van de inhoud van een eenvoudig hulpbladbestand waarin het gebruik van de elementen command, perform-when en conditional-subitems wordt uitgelegd.
<?xml version="1.0" encoding="UTF-8"?> <cheatsheet title="Voorbeeldhulpblad"> <intro> <description>Een hulpblad waarin wordt uitgelegd hoe de elementen perform-when en conditional subitems worden gebruikt</description> </intro> <item title="View selecteren"> <description>Selecteer een view die in de volgende stappen wordt geopend.</description> <command returns = "result" serialization="org.eclipse.ui.dialogs.openMessageDialog(title=View selecteren,buttonLabel0=Pakketverkenner,message=Selecteer een view,buttonLabel1=View Zoeken)"/> <onCompletion> View ${result} geselecteerd. </onCompletion> </item> <item title="Views sluiten"> <description>View Zoeken en Pakketverkenner sluiten als deze zijn geopend</description> </item> <item title="View openen met item perform-when" skip = "true"> <description>Gebruikt perform-when om de eerder geselecteerde view te openen.</description> <perform-when condition = "${result}"> <command when = "Pakketverkenner" serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.jdt.ui.PackageExplorer)"/> <command when = "View Zoeken" serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.search.ui.views.SearchView)"/> </perform-when> </item> <item title="Views sluiten"> <description>View Zoeken en Pakketverkenner sluiten als deze zijn geopend</description> </item> <item title="View openen met item perform-when"> <description>Gebruikt perform-when om de eerder geselecteerde view te openen.</description> <subitem label="Subitem perform-when" skip = "true"> <perform-when condition = "${result}"> <command when = "Pakketverkenner" serialization="org.eclipse.jdt.ui.PackageExplorer"/> <command when = "View Zoeken" serialization="org.eclipse.search.ui.views.SearchView"/> </perform-when> </subitem> </item> <item title="Views sluiten"> <description>View Zoeken en Pakketverkenner sluiten als deze zijn geopend</description> </item> <item title="View openen met conditional-subitem"> <description>Gebruikt perform-when om de eerder geselecteerde view te openen.</description> <conditional-subitem condition="${result}"> <subitem when="Pakketverkenner" label="Pakketverkenner openen"> <command serialization = "org.eclipse.jdt.ui.PackageExplorer"/> </subitem> <subitem when="View Zoeken" label="View Zoeken openen"> <command serialization = "org.eclipse.search.ui.views.SearchView"/> </subitem> </conditional-subitem> </item> </cheatsheet>
Copyright (c) 2004, 2006 IBM Corporation en anderen.
Alle rechten voorbehouden. Dit programma en het begeleidende materiaal zijn beschikbaar gesteld onder de voorwaarden van de Eclipse Public License v1.0 die bij deze distributie is geleverd en beschikbaar is op http://www.eclipse.org/legal/epl-v10.html.