Muistilistat ohjaavat käyttäjiä monimutkaisissa tehtävissä, joiden tarkoituksena on saavuttaa jokin yleinen tavoite. Muistilistan avulla voidaan esimerkiksi auttaa käyttäjää tekemään kaikki toimet, joita tarvitaan yksinkertaisen Java-ohjelman luontiin, käännökseen ja ajoon. Muistilistat aloitetaan valitsemalla vaihtoehdot
Ohje > Muistilistat.... Muistilistat voi aloittaa myös aloitussivulta.
Muistilistat määritetään org.eclipse.ui.cheatsheets.cheatSheetContent-laajennuspisteen avulla. Muistilistan sisältö määritetään erillisessä tiedostossa, jotta sen voisi helpommin kääntää eri kielille.
Muistilistan lisäys on melko yksinkertaista. Esimerkkinä on muistilista, jonka JDT on toimittanut yksinkertaisen Java-sovelluksen koontia varten.
<extension point="org.eclipse.ui.cheatsheets.cheatSheetContent"> <cheatsheet name="%cheatsheet.helloworld.name" contentFile="$nl$/cheatsheets/HelloWorld.xml" id="org.eclipse.jdt.helloworld"> <description>%cheatsheet.helloworld.desc</description> </cheatsheet> ...Pitkälti samalla tavalla kuin muillekin työympäristön muokkauksille, muistilistalle voi määrittää nimen, kuvauksen ja tunnuksen. Nimen ja kuvauksen saa näkyviin valitsemalla vaihtoehdot
Muistilistojen varsinainen työ tehdään sisältötiedostossa. Sisältötiedosto on XML-tiedosto, jonka nimi ja sijainti on määritetty määritteessä contentFile. Tiedoston polku esitetään suhteessa lisäosan hakemistoon. (Huomaa, että muuttujan $nl$ käyttö hakemiston nimessä, joka tarkoittaa, että tiedosto sijaitsee kohdeympäristön kielen omassa hakemistossa.)
Tiedostomuoto sisältää yleiskuvaustiedot muistilistasta, minkä jälkeen on kunkin käyttäjän tekemän vaiheen kuvaus (josta käytetään nimitystä kohta). Yksinkertaisimmillaan kohta on vain yksityiskohtainen kuvaus vaiheesta, joka käyttäjän tulee tehdä. Kohta voi kuitenkin määrittää myös tapahtuman, joka voidaan ajaa tekemään vaihe käyttäjän puolesta. Seuraavassa esimerkissä on kuvattu Java-muistilistan sisältötiedoston (HelloWorld.xml) ensimmäinen osa.
<?xml version="1.0" encoding="UTF-8" ?> <cheatsheet title="Simple Java Application"> <intro href="/org.eclipse.ui.cheatsheets.doc/tasks/tcheatst.htm"> <description> Welcome to the Hello, World Java tutorial. It will help you build the famous "hello world" application and try it out. You will create a java project, and a java class that will print "hello world" in the console when run. Let's get started! </description> </intro> <item href="/org.eclipse.platform.doc.user/concepts/concepts-4.htm" title="Open the Java Perspective"> <action pluginId="org.eclipse.ui.cheatsheets" class="org.eclipse.ui.internal.cheatsheets.actions.OpenPerspective" param1="org.eclipse.jdt.ui.JavaPerspective"/> <description> Valitse työympäristön yläosan valikkopalkista Ikkuna->Avaa perspektiivi->Java. Tässä vaiheessa perspektiivi muuttuu Java-kehityksen Eclipse-työympäristön asettamista varten. Voit avata Java-perspektiivin automaattisesti napsauttamalla "Toteuta napsauttamalla tätä" -painiketta. </description> </item> ...
Otsikko ja esittelytiedot näkyvät muistilistan yläosassa. Tämän jälkeen on kohtien kuvaus. Tämän muistilistan ensimmäinen kohta kuvaa, miten Java-perspektiivi avataan. Lisäksi määrite action määrittää luokan, jonka avulla toiminto voidaan ajaa käyttäjän puolesta. Luokan on toteutettava IAction-rajapinta. Tämä on kätevää, sillä sen avulla voi käyttää uudelleen valikko- tai työkalurivilisäyksille kirjoitettuja toimintoluokkia.
Toiminnon luokka voi valinnaisesti toteuttaa ICheatSheetAction-rajapinnan, jos toiminto käyttää parametreja tai sen on oltava tietoinen muistilistasta ja sen tilasta. Tässä tapauksessa toiminnolle välitetään parametritaulukko ja viittaus ICheatSheetManager-rajapintaan, jotta se voi pyytää lisätietoja muistilistasta. Kaikki tarvittavat parametrit voidaan välittää toiminnon ajometodiin määritteillä paramN.
On erittäin suositeltavaa, että muistilistoista kutsutut toiminnot tuottavat raportin onnistumisesta tai epäonnistumisesta siltä varalta, että toiminnon ajo ei onnistu. (Esimerkiksi käyttäjä saattaa peruuttaa toiminnon sen valintaikkunasta.) Lisätietoja on ohjeaiheessa IAction.notifyResult(boolean).
Kohtien ei tarvitse määrittää toimintoja. Jos käyttäjän tulee tehdä jokin kohta manuaalisesti, mitään toimintoa ei tarvitse määrittää. Seuraavassa on Java-muistilistan kolmas vaihe, joka vain kertoo käyttäjälle, miten yksinkertainen sovellus koodataan. Kun mitään toimintoa ei ole määritetty, kohdan kuvauksen on neuvottava käyttäjää napsauttamaan oikeaa painiketta tehtävän valmistumisen jälkeen.
<item href="/org.eclipse.jdt.doc.user/tasks/tasks-54.htm" title="Lisää System.out.println-rivi päämetodiin"> <description> Kun olet nyt luonut HelloWorld-luokan, lisää "public static void main" -metodiin seuraava lause: System.out.println("Hello world!"); ja tallenna muutokset. Kun tämä on tehty, napsauta alla olevaa "napsauta tästä, kun valmis" -painiketta. </description> </item>Lisämääritteet ohjaavat, voiko kohdan ohittaa kokonaan ja mikä asiakirja tulee avata, jos käyttäjä pyytää ohjetta vaiheen aikana. Kuvaus kaikista muistilistan sisällä määritettävissä olevista määritteistä on org.eclipse.ui.cheatsheets.cheatSheetContent-laajennuspisteen dokumentaatiossa.
Kohdan esitystä voi järjestää edelleen määrittämällä alikohtia. Toisin kuin kohtia, alikohtia ei tarvitse käydä läpi tietyssä järjestyksessä. Alikohdat voivat määrittää myös toimintoja, jotka tekevät alitehtävän automaattisesti käyttäjän puolesta. Alikohtien toiminnot kuvataan samalla tavalla kuin kohtien toiminnot.
Muistilistan elementtejä, joiden sisältö tai toiminta vaihtelee tietyn ehdon täyttymisen mukaan, voidaan määrittää ehdollislausekkeiden avulla. Ehdot kuvataan alikohdan elementissä condition satunnaisilla merkkijonoarvoilla, joita verrataan kunkin valinnan when-määritteeseen. Ehdot viittaavat muistilistan muuttujiin tavallisesti muodossa ${var}, jossa var viittaa muistilistan muuttujan nimeen. Muutama yksinkertainen esimerkki kuvaa ehdollislausekkeiden toimintaa.
Ehdollisten alikohtien avulla voi valita yhden alikohdan mahdollisten alikohtien luettelosta. Vain ensimmäinen alikohta, jonka when-määrite vastaa ehdon määritettä, sisällytetään muistilistaan. Esimerkki:
<item ...> <conditional-subitem condition="${v1}"> <subitem when="a" label="Step for A." /> <subitem when="b" label="Step for B." /> </conditional-subitem> </item>Tämä kohta määrittää kaksi mahdollista alikohtaa, jotka ovat muuttujan v1 arvosta riippuvia. Jos muuttujan arvo on a, ensimmäinen alikohta sisällytetään. Jos muuttujan arvo on b, toinen alikohta sisällytetään. Jos muuttujan arvo ei ole kumpikaan näistä, tuloksena on virhe.
Ehdolliset toiminnot ovat samankaltaisia kuin ehdolliset alikohdat. Elementti perform-when määrittää ehdon yhden toiminnon tekemiselle mahdollisten toimintojen luettelosta. Ehto kuvataan samalla tavalla käyttäen satunnaista merkkijonoa, joka usein viittaa muuttujaan. Toiminto, jonka when-määrite vastaa ehtoa, tehdään. Esimerkki:
<item ...> <perform-when condition="${v1}"> <action when="a" class="com.example.actionA" pluginId-"com.example" /> <action when="b" class="com.example.actionB" pluginId-"com.example" /> </perform-when> </item>Tehtävä toiminto valitaan muuttujan v1 arvon mukaan. Jos muuttujan arvo ei ole kumpikaan arvoista a tai b, tuloksena on virhe.
Toistuvat alikohdat kuvaavat alikohdan, joka voi laajentua nollaan, yhteen tai useampaan vastaavaan alivaiheeseen. Alikohdat yksilöidään erityismuuttujan ${this} avulla. values-määritteessä määritetyt arvot korvaavat tämän muuttujan. Values-määrite on pilkuin eroteltu merkkijono arvoista. Arvojen luetteloon laajentuvaa muuttujaa voi käyttää values-määritteessä. Esimerkki:
<item ...> <repeated-subitem values="${v1}"> <subitem label="Step ${this}" /> </repeated-subitem> </item>Jos muuttujan arvo on 1,b,three, muistilistassa näkyy kolme alikohtaa, joista jokaisella on yksilöllinen otsikko ("Step 1," "Step b," "Step three"). Muuttujaa voi käyttää otsikossa tai toimintoparametrin arvossa. Sitä voi käsitellä myös ICheatSheetManager-rajapinnasta toiminnon suorituksen aikana.
Joskus voi olla, että haluat muuttaa käyttöliittymän muita osia, jos muistilista on aktiivinen. Voi olla, että esimerkiksi jokin muokkausohjelma näyttää erityishuomautukset, jos muistilista ohjaa käyttäjää muokkaustapahtumassa. Tällöin voi määrittää kuuntelutoiminnon muistilistan määritteeksi. Kuunteluohjelmamääritteen on oltava sellaisen Java-luokan tarkennettu nimi, joka on CheatSheetListener-luokan aliluokka. Kuunteluohjelmat vastaanottavat ilmoitukset yhdessä ICheatSheetEvent-rajapinnan kanssa, kun muistilistan elinkaaressa on jokin muutos, esimerkiksi se avataan, suljetaan tai saatetaan päätökseen.
Laajennuksen org.eclipse.ui.cheatsheets.cheatSheetItemExtension avulla voi toimittaa satunnaisia määritteitä aiemmin luotuun muistilistaan. Tämän laajennuspisteen tarkoituksena on antaa lisäosan lisätä painikkeita, jotka auttavat käyttäjää tietyssä vaiheessa. Nämä lisäpainikkeet näkyvät ohjekuvakkeen vieressä.
Tämän mekanismin käytössä voi määrittää minkä tahansa satunnaisen määritteen objektin määrityksen sisällä muistilistan XML-tiedostossa. Määritteen nimeä verrataan mihin tahansa määritteisiin, joka on lisätty org.eclipse.ui.cheatsheets.cheatSheetItemExtension-laajennuksissa. Lisätietoja on laajennuspisteen dokumentaatiossa.
Muistilistojen käyttö
Koostemuistilistojen luonti
Muistilistojen laatimisohjeet
org.eclipse.ui.cheatsheets.cheatSheetContent-laajennuspiste
Muistilistan sisältötiedoston määritys