Version 3.2
Dette dokument beskriver snydearkets indholdsfilstruktur som en række DTD-fragmenter (maskinlæsbart XML-skema).
cheatsheet
<!ELEMENT cheatsheet (intro, item+)> <!ATTLIST cheatsheet title CDATA #REQUIRED >
Elementet <cheatsheet> definerer indholdet af indholdsfilen til snydearket. <cheatsheet>-attributterne er som følger:
intro
<!ELEMENT intro (description)> <!ATTLIST intro contextId CDATA #IMPLIED href CDATA #IMPLIED >
Elementet <intro> bruges til at beskrive den introduktion til snydearket, som bliver vist. Underelementet <description> indeholder indholdet af introduktionen. <intro>-attributterne er som følger:
description
<!ELEMENT description EMPTY> <!ATTLIST description >
Elementet <description> indeholder en beskrivelse af snydearket eller af snydearkselementet. Beskrivelsen består af tekst, hvori der er enkle formateringskoder. Snydearket formaterer automatisk teksten og sørger for layoutet, så den ser rimelig ud, når den vises på UI. Inde i teksten får koderne <b>...</b> den tekst, de omgiver, til at vises med fed skrift. Du kan bruge elementet <br/>, hvis du vil indsætte et fast linjeskift. Det er de eneste formateringskoder, der understøttes for øjeblikket (der kan dog komme flere til senere). Visse tegn i teksten har særlig betydning for XML-parsere. Hvis du skal skrive "<", ">", "&", "'" og """ (citationstegn), skal du i stedet skrive henholdsvis "<", ">", "&", "'" og """. Tomme pladser (mellemrum og linjeskift) behandles som ordskilletegn. Mellemrum og linjeskift ved siden af hinanden behandles som en enkelt enhed og gengives som et enkelt mellemrum eller et enkelt linjeskift. En tom plads umiddelbart efter koden <description> og <br/> ignoreres, ligesom tomme pladser umiddelbart foran 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 af de øverste trin i et snydeark. Et <element> kan indeholde <underordnede elementer>. <item>-attributterne er som følger:
org.eclipse.ui.cheatsheets.cheatSheetItemExtension tillader, at der vises flere tilpassede kontroller for elementet i UI. Bidrag til dette udvidelsespunkt erklærer navnene på flere streng-værdi-attributter, som eventuelt vises på <item>-elementerne.
Enkle elementer har en beskrivelse og en valgfri funktion eller kommando. I den typiske præsentation får brugeren det meste af tiden vist titlerne på snydearkets elementer. Et elements beskrivelse vises kun, mens trinnet er ved at blive udført. Tilstedeværelsen af et element af typen <action>, <command> eller <perform-when> forbindes med en knap, som brugerne kan trykke på for at udføre undertrinnets funktion. Hvis der ikke er en funktion eller kommando, er trinnet et, som brugeren skal udføre manuelt, og derefter angive, at trinnene er udført.
Trin opdeles i undertrin, som angivet af <subitem>-underelementerne. I modsætning til elementer, som brugeren skal følge i en helt bestemt rækkefølge, kan underelementer til et givent element udføres i en vilkårlig rækkefølge. Alle underelementer i en element skal være forsøgt anvendt (eller være sprunget over), før man kan gå videre til næste element. Det betyder, at funktioner, der skal udføres i en bestemt rækkefølge, ikke kan præsenteres som underelementer.
Underelementet <conditional-subitem> gør det muligt for et trin at skræddersy præsentationen af en undertrin, som er baseret på de variabler i snydearket, hvis værdier er anskaffet i tidligere trin. Underelementet <repeated-subitem> gør det muligt for et trin at inkludere et sæt af lignende undertrin. Igen gælder det, at det præcise undertrinsæt kan være baseret på snydearkvariabler, hvis værdi er anskaffet i tidligere trin.
subitem
<!ELEMENT subitem ( [action|command|perform-when] )> <!ATTLIST subitem label CDATA #REQUIRED skip ("true" | "false") "false" when CDATA #IMPLIED >
Hvert <subitem>-element beskriver et undertrin i et snydeark. Et <subitem> har en enkel tekstetiket, men har hverken en længere beskrivelse eller flere underelementer. <subitem>-attributterne er som følger:
Underelementer kan have en valgfri funktionel kommando. Tilstedeværelsen af et element af typen <action>, <command> eller <perform-when> forbindes typisk med en knap, som brugerne kan trykke på for at udføre undertrinnets funktion. Hvis der ikke er en funktion eller kommando, er trinnet et, som brugeren skal udføre manuelt, og derefter angive, at trinnene er udført.
I modsætning til elementer, som skal følges i en helt bestemt rækkefølge, kan underelementer til et givent element udføres i en vilkårlig rækkefølge. Alle underelementer i en element skal være udført eller være sprunget over, før man kan gå videre til næste element. Det betyder, at funktioner, der skal udføres i en bestemt rækkefølge, ikke kan præsenteres som underelementer.
conditional-subitem
<!ELEMENT conditional-subitem (subitem+)> <!ATTLIST conditional-subitem condition CDATA #REQUIRED >
Hvert <conditional-subitem>-element beskriver en enkelt undertrin, hvis form kan variere afhængigt af en betingelse, som var kendt på det tidspunkt, elementet blev udvidet. <conditional-subitem>-attributterne er som følger:
condition-attributten på elementet <conditional-subitem> giver en strengværdi (denne værdi kommer uundgåeligt fra en snydearkvariabel). Hvert af de underordnede <subitem>-elementer skal indeholde attributten when sammen med en speciel strengværdi. Når elementet udvides, erstattes <conditional-subitem>-elementet med elementet <subitem>, der har en tilsvarende værdi. Det betragtes som en fejl, hvis der ikke er et <subitem>-element med en tilsvarende værdi.
Hvis snydearksvariablen "v1" f.eks. har værdien "b", når følgende element udvides
<item ...> <conditional-subitem condition="${v1}"> <subitem when="a" label="Step for A." /> <subitem when="b" label="Step for B." /> </conditional-subitem> </item>så vælges det andet underelement, og elementet udvides til noget, der svarer til
<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 udvides til 0, 1 eller flere lignende undertrin. <repeated-subitem>-attributetterne er som følger:
values-attributten giver en liste med kommaseparerede strenge. Det underordnede <subitem> giver skabelonen. Når elementet udvides, erstattes <repeated-subitem>-elementet med kopier af <subitem>-elementet, hvor forekomster af variablen "this" er udskiftet med den tilsvarende strengværdi.
Hvis snydearksvariablen "v1" f.eks. har værdien "1,b,three", når følgende element udvides
<item ...> <repeated-subitem values="${v1}"> <subitem label="Step ${this}."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/> </subitem> </repeated-subitem> </item>udvides element til noget, der svarer til:
<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 funktion i et snydeark. <action>-attributterne er som følger:
org.eclipse.jface.action.IAction
.
Hvis denne funktion også implementerer org.eclipse.ui.cheatsheets.ICheatSheetAction
, startes den via sin
run(String[],ICheatSheetManager)-metode og får overført snydearksprogrammet og funktionsparametrene. pluginId-attributten
skal være til stede, når denne attribut er til stede. Det anbefales på det kraftigste, at funktioner, der skal startes fra snydeark, skal rapportere, om funktionen blev gennemført eller ej, hvis der er risiko for,
at funktionen ikke gennemføres (måske fordi brugeren annullerer funktionen fra dialogboksen). (Der er flere oplysninger i
org.eclipse.jface.action.Action.notifyResult(boolean)).org.eclipse.ui.cheatsheets.ICheatSheetAction
,
overføres strengværdierne af disse attributter til funktionen, når den startes. Du kan overføre op til 9 parametre til et snydeark (param1,
param2 osv.). Parametrene skal begynde med parameter 1
og være fortløbende, det vil sige, du må ikke angive param2, medmindre du også har param1. Hvis attributstrengen har formatet "${var}",
betragtes den som en reference til snydearkvariablen var, og betingelsens værdi er værdien af variablen for snydearket på det tidspunkt,
hvor udførelsen af elementet <item> startede (eller udførelsen af den tomme streng, hvis variablen ikke er bundet på dette tidspunkt). 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 et snydeark. <command>-attributter er som følger:
Nedenfor er et eksempel på et element med en kommando, der åbner en dialogboks og gemmer resultatet i snydearkets variabel "result".
<item title="Vis valg"> <description>Vælg en oversigt, der skal åbnes i næste trin.</description> <command returns = "result" serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Select View,buttonLabel0=Package Explorer,message=Vælg en oversigt ,buttonLabel1=Søg efter oversigt)"/> <onCompletion> ${result} er valgt. </onCompletion> </item>
onCompletion
<!ELEMENT onCompletion EMPTY> <!ATTLIST onCompletion >
Elementet <onCompletion> indeholder tekst, der vises, når et element er afsluttet. Det er især nyttigt i det afsluttende trin for snydearket for at godkende afslutningen af hele opgaven. Beskrivelsen består af tekst, hvori der er enkle formateringskoder, der følger de samme regler som for elementet <description>. <onCompletion>-elementer kan også indeholde referencer til snydearksvariabler i formatet "${var}", der udvides ved at bruge den aktuelle værdi for snydearksvariablen var på det tidspunkt, dette trin er afsluttet.
perform-when
<!ELEMENT perform-when ((action|command)+)> <!ATTLIST perform-when condition CDATA #REQUIRED >
Hvert <perform-when>-element beskriver en funktion i et snydeark. <perform-when>-attributterne er som følger:
condition-attributten på elementet <conditional-subitem> giver en strengværdi (denne værdi kommer uundgåeligt fra en snydearkvariabel). Hvert af de underordnede <subitem>-elementer skal indeholde attributten when sammen med en speciel strengværdi. Når elementet udvides, erstattes <conditional-subitem>-elementet med elementet <subitem>, der har en tilsvarende værdi. Det betragtes som en fejl, hvis der ikke er et <subitem>-element med en tilsvarende værdi.
Hvis snydearksvariablen "v1" f.eks. har værdien "b", når følgende element udvides
<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>så vælges den anden funktion, og elementet udvides til noget, det svarer til
<item ...> <subitem label="Main step"> <action class="com.xyz.action2" pluginId="com.xyz" /> </subitem> </item>
Følgende eksempel viser en enkel indholdsfil for et snydeark, der viser brugen af kommandoer, perform-when og betingede underordnede elementer.
<?xml version="1.0" encoding="UTF-8"?> <cheatsheet title="Eksempelsnydeark"> <intro> <description>Et snydeark, der viser brugen af perform-when og betingede underordnede elementer</description> </intro> <item title="Vis valg"> <description>Vælg en oversigt, der skal åbnes i næste trin.</description> <command returns = "result" serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Select View,buttonLabel0=Package Explorer,message=Vælg en oversigt ,buttonLabel1=Søg efter oversigt)"/> <onCompletion> ${result} er valgt. </onCompletion> </item> <item title="Luk oversigter"> <description>Luk søgeoversigten og Package Explorer, hvis den er åben</description> </item> <item title="Åbn oversigten fra et perform-when-element" skip = "true"> <description>Anvender perform-when til at åbne den oversigt, der tidligere er valgt.</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 = "Søg efter oversigt" serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.search.ui.views.SearchView)"/> </perform-when> </item> <item title="Luk oversigter"> <description>Luk søgeoversigten og Package Explorer, hvis den er åben</description> </item> <item title="Åbn oversigten fra et underordnet perform-when-element"> <description>Anvender perform-when til at åbne den oversigt, der tidligere er valgt.</description> <subitem label="Underordnet perform-when-element" skip = "true"> <perform-when condition = "${result}"> <command when = "Package Explorer" serialization="org.eclipse.jdt.ui.PackageExplorer"/> <command when = "Søg efter oversigt" serialization="org.eclipse.search.ui.views.SearchView"/> </perform-when> </subitem> </item> <item title="Luk oversigter"> <description>Luk søgeoversigten og Package Explorer, hvis den er åben</description> </item> <item title="Åbn oversigten fra et betinget underordnet element"> <description>Anvender perform-when til at åbne den oversigt, der tidligere er valgt.</description> <conditional-subitem condition="${result}"> <subitem when="Package Explorer" label="Åbn Package Explorer."> <command serialization = "org.eclipse.jdt.ui.PackageExplorer"/> </subitem> <subitem when="Søg efter oversigt" label="Åbn Søg efter oversigt"> <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