Versio 3.2
Tässä ohjeessa kuvataan muistilistan sisältötiedoston rakenne DTD-osiksi (tietokoneen XML-skeemaksi) jaettuna.
cheatsheet
<!ELEMENT cheatsheet (intro, item+)> <!ATTLIST cheatsheet title CDATA #REQUIRED >
<Cheatsheet>-elementti määrittää muistilistan sisältötiedoston runko-osan. <Cheatsheet>-elementin määritteet ovat seuraavat:
intro
<!ELEMENT intro (description)> <!ATTLIST intro contextId CDATA #IMPLIED href CDATA #IMPLIED >
<Intro>-elementti määrittää näytettävän muistilistan esittelyn. <Description>-alielementti sisältää esityksen runko-osan. <Intro>-elementin määritteet ovat seuraavat:
description
<!ELEMENT description EMPTY> <!ATTLIST description >
<Description>-elementti sisältää muistilistan tai muistilistaobjektin kuvauksen. Tämä kuvaus muodostetaan tekstiosista ja perusmuotoilutunnisteista. Muistilista muotoilee ja asettelee tekstin automaattisesti käyttöliittymässä näyttämistä varten. <B>- ja </b>-tunnisteilla rajattu teksti näytetään lihavoituna, ja <br/>-tunniste lisää tekstiin rivinvaihdon. Nykyinen versio tukee vain näitä muotoilutunnisteita, mutta tunnistetukea voidaan laajentaa myöhemmissä versioissa. Tietyt merkit on kirjoitettava erikoismerkeillä XML-jäsennystoimintoja varten. Esimerkiksi merkit <, >, &, ' ja " on kirjoitettava seuraavasti: <, >, &, ' ja ". Tyhjämerkit (välilyönnit ja rivinvaihdot) käsitellään sanojen erotinmerkkeinä. Jos tekstissä on useita peräkkäisiä tyhjämerkkejä, ne käsitellään yhtenä tyhjämerkkinä. <Description>- ja <br/>-tunnisteiden jäljessä ja </description>-tunnisteen edellä olevat tyhjämerkit ohitetaan.
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 >
Kukin <item>-elementti määrittää yhden muistilistan ylätason vaiheen. Kyseiset <item>-elementit voivat sisältää <subitem>-elementtejä. <Item>-elementin määritteet ovat seuraavat:
Org.eclipse.ui.cheatsheets.cheatSheetItemExtension-laajennuspisteeseen voidaan määrittää mukautettuja ohjausobjekteja kohtien käyttöliittymässä näyttämistä varten. Tämän laajennuspisteen lisäyksiin määritetään niiden merkkijonomuotoisten lisämääritteiden nimet, joita <item>-elementeissä voidaan käyttää.
Peruskohdat sisältävät kuvauksen ja valinnaisen toiminnon tai komennon. Normaalissa esityksessä muistilistan kohtien otsikot näytetään yleensä käyttäjälle. Kohdan kuvaus näytetään vain, kun kyseistä vaihetta suoritetaan. Elementtien <action>, <command> tai <perform-when> olemassaolo liitetään näppäimeen, jota painamalla käyttäjä voi aloittaa kyseisen vaiheen toiminnon tai komennon. Jos toimintoja tai komentoja ei ole määritetty, käyttäjän on suoritettava vaihe manuaalisesti ja ilmaistava suorittaneensa vaihe.
Vaiheet voidaan jakaa alivaiheisiin <subitem>-alielementtimääritysten mukaisesti. Toisin kuin pääkohdat, jotka käyttäjän on suoritettava tietyssä järjestyksessä, yksittäisten kohtien alikohdat voidaan suorittaa missä tahansa järjestyksessä. Jokaista kohdan alikohtaa on kokeiltava (tai ohitettava ne) ennen seuraavaan kohtaan siirtymistä. (Näiden rajoitusten takia toimintoja, jotka on suoritettava tietyssä järjestyksessä, ei voi määrittää alikohdiksi.)
Vaiheen <conditional-subitem>-alielementin esitystapa määräytyy muistilistan aiemmissa vaiheissa määritettyjen muuttujien arvojen perusteella. <Repeated-subitem>-alielementin avulla vaiheeseen voidaan lisätä samankaltaisia alivaiheita. Myös näiden alivaiheiden koostumus voi määräytyä muistilistan aiemmissa vaiheissa määritettyjen muuttujien arvojen perusteella.
subitem
<!ELEMENT subitem ( [action|command|perform-when] )> <!ATTLIST subitem label CDATA #REQUIRED skip ("true" | "false") "false" when CDATA #IMPLIED >
Kukin <subitem>-elementti määrittää yhden muistilistan alatason vaiheen. <Subitem>-elementtiin määritetään tekstimuotoinen otsikko, mutta siihen ei liitetä pitkää kuvausta eikä siihen voi lisätä muita subitem-elementtejä. <Subitem>-elementin määritteet ovat seuraavat:
Alikohtiin voi liittää valinnaisia toimintoja tai komentoja. Elementtien <action>, <command> tai <perform-when> olemassaolo liitetään tavallisesti näppäimeen, jota painamalla käyttäjä voi aloittaa kyseisen vaiheen toiminnon tai komennon. Jos toimintoja tai komentoja ei ole määritetty, käyttäjän on suoritettava alivaihe manuaalisesti ja ilmaistava suorittaneensa se.
Toisin kuin pääkohdat, jotka on suoritettava tietyssä järjestyksessä, yksittäisten kohtien alikohdat voidaan suorittaa missä tahansa järjestyksessä. Jokainen kohdan alikohta on tehtävä loppuun (tai ohitettava) ennen seuraavaan kohtaan siirtymistä. (Näiden rajoitusten takia toimintoja, jotka on suoritettava tietyssä järjestyksessä, ei voi määrittää alikohdiksi.)
conditional-subitem
<!ELEMENT conditional-subitem (subitem+)> <!ATTLIST conditional-subitem condition CDATA #REQUIRED >
Kukin <conditional-subitem>-elementti määrittää yhden alivaiheen, jonka muoto vaihtelee kohdan laajennuksen toteutushetkellä selvitettävän ehdon mukaan. <Conditional-subitem>-elementin määritteet ovat seuraavat:
<Conditional-subitem>-elementin condition-määrite määrittää merkkijonoarvon (jonka arvo määräytyy poikkeuksetta jonkin muistilistan muuttujan perusteella). Kussakin elementin <subitem>-alielementissä on oltava when-määrite, jonka arvo on jokin määrätty merkkijono. Kun tämän kohdan laajennus toteutetaan, <conditional-subitem>-elementti korvataan sillä <subitem>-elementillä, jonka arvo vastaa ehtoa. Jos ehtoa vastaavaa <subitem>-elementtiä ei löydy, tilanne käsitellään virheenä.
Oletetaan esimerkiksi, että muistilistan muuttujan "v1" arvo on "b", kun seuraavan kohdan laajennus toteutetaan:
<item ...> <conditional-subitem condition="${v1}"> <subitem when="a" label="Vaihe A." /> <subitem when="b" label="Vaihe B." /> </conditional-subitem> </item>Tällöin suoritettavaksi valitaan toinen subitem-elementti ja kohdan laajennus toteutetaan seuraavassa muodossa:
<item ...> <subitem label="Vaihe B."/> </item>
repeated-subitem
<!ELEMENT repeated-subitem (subitem)> <!ATTLIST repeated-subitem values CDATA #REQUIRED >
Kukin <repeated-subitem>-elementti määrittää alikohdan, joka voi toteuttaa yhden tai useamman samankaltaisen alivaiheen tai ei yhtään alivaihetta. <Repeated-subitem>-elementin määritteet ovat seuraavat:
Values-määrite sisältää pilkuin eroteltujen merkkijonojen luettelon. <Subitem>-alielementti määrittää mallipohjan. Kun tämän kohdan laajennus toteutetaan, <repeated-subitem>-elementti korvataan <subitem>-elementin kopioilla, joiden "this"-muuttujat korvataan niitä vastavilla merkkijonoarvoilla.
Oletetaan esimerkiksi, että muistilistan muuttujan "v1" arvo on "1,b,kolme", kun seuraavan kohdan laajennus toteutetaan:
<item ...> <repeated-subitem values="${v1}"> <subitem label="Vaihe ${this}."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/> </subitem> </repeated-subitem> </item>Tällöin kohdan laajennus toteutettaisiin seuraavanlaisessa muodossa:
<item ...> <subitem label="Vaihe 1."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="1"/> </subitem> <subitem label="Vaihe b."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="b"/> </subitem> <subitem label="Vaihe kolme."> <action class="com.xyz.myaction" pluginId="com.xyz" param1="kolme"/> </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 >
Kukin <action>-elementti määrittää jonkin muistilistan toiminnon. <Action>-elementin määritteet ovat seuraavat:
org.eclipse.jface.action.IAction
-liittymän.
Jos tämä toiminto toteuttaa myös org.eclipse.ui.cheatsheets.ICheatSheetAction
-liittymän,
sen kutsu tehdään sen run(String[],ICheatSheetManager)-metodin avulla ja
sille välitetään muistilistan hallintaohjelma ja toimintoparametrit. Jos tämä määrite on käytössä, myös pluginId-määritteen
on oltava määritetty. On suositeltavaa, että muistilistalta
aloitettavat toiminnot raportoisivat onnistumisesta ja epäonnistumisesta,
jos toiminnon ajo voi epäonnistua (esimerkiksi siksi, että
käyttäjä peruuttaa toiminnon). (Lisätietoja on
org.eclipse.jface.action.Action.notifyResult(boolean)-laajennuksen ohjeessa.)org.eclipse.ui.cheatsheets.ICheatSheetAction
-liittymän. Muistilistan toimintoon voi välittää enintään yhdeksän parametria (param1,
param2 ja niin edelleen). Parametrien numeroinnin on oltava juokseva ja alettava
numerosta yksi. Param2-määritys ei siis ole mahdollinen, jos param1-määritystä
ei ole tehty. Jos tämän määritteen merkkijonon muoto on "${var}",
se käsitellään viittauksena muistilistan muuttujaan var. Tällöin tämän
ehtomääritteen arvo on kyseisen muistilistan muuttujan arvo
sillä hetkellä, kun tämän elementin sisältävän <item>-elementin suoritus aloitettiin, tai
tyhjä merkkijono, jos muuttujaa ei ollut sidottu arvoon kyseisenä hetkenä.command
<!ELEMENT command EMPTY> <!ATTLIST command serialization CDATA #REQUIRED returns CDATA #IMPLIED confirm ("true" | "false") "false" when CDATA #IMPLIED >
Kukin <command>-elementti määrittää jonkin muistilistan komennon. Elementin <command> määritteet ovat seuraavat:
Seuraavassa on esimerkki kohdasta, jossa on valintaikkunan avaava ja muistilistamuuttujaan "result" tuloksen tallentava komento.
<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 >
Elementti <onCompletion> sisältää tekstin, joka näytetään, kun kohta on tehty loppuun. Tästä on hyötyä etenkin muistilistan viimeisessä kohdassa, jossa voidaan kuitata koko tehtävän loppuun vienti. Tämä kuvaus muodostetaan tekstiosista ja perusmuotoilutunnisteista, jotka noudattavat samoja sääntöjä kuin <description>-elementin yhteydessä. Kyseiset <onCompletion>-elementit voivat myös sisältää viittauksia "${var}"-muotoisiin muistilistamuuttujiin, jotka laajennetaan muistilistamuuttujan var todellisella arvolla, kun kyseinen vaihe on tehty.
perform-when
<!ELEMENT perform-when ((action|command)+)> <!ATTLIST perform-when condition CDATA #REQUIRED >
Kukin <perform-when>-elementti määrittää jonkin muistilistan toiminnon. <Perform-when>-elementin määritteet ovat seuraavat:
<Conditional-subitem>-elementin condition-määrite määrittää merkkijonoarvon (jonka arvo määräytyy poikkeuksetta jonkin muistilistan muuttujan perusteella). Kussakin elementin <subitem>-alielementissä on oltava when-määrite, jonka arvo on jokin määrätty merkkijono. Kun tämän kohdan laajennus toteutetaan, <conditional-subitem>-elementti korvataan sillä <subitem>-elementillä, jonka arvo vastaa ehtoa. Jos ehtoa vastaavaa <subitem>-elementtiä ei löydy, tilanne käsitellään virheenä.
Oletetaan esimerkiksi, että muistilistan muuttujan "v1" arvo on "b", kun seuraavan kohdan laajennus toteutetaan:
<item ...> <subitem label="Päävaihe"> <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>Tällöin suoritettavaksi valitaan toinen action-elementti ja kohdan laajennus toteutetaan seuraavassa muodossa:
<item ...> <subitem label="Päävaihe"> <action class="com.xyz.action2" pluginId="com.xyz" /> </subitem> </item>
Seuraavassa on esimerkki yksinkertaisen muistilistan sisältötiedostosta. Esimerkki esittelee command-, perform-when- ja conditional-alikohtien käyttöä.
<?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