Asiakirjat ja niiden osiot

Käyttöympäristön tekstikehys määrittää tekstien asiakirjamallit. Kehyksen katseluohjelman avulla tekstit voi esittää tätä mallia käyttäen. Seuraavassa perehdytään ensin Java-esimerkkimuokkausohjelmaan ja siihen, miten siinä käytetään asiakirjamallia. Muokkausohjelman laajennuksen rekisteröintiin ei enää syvennytä, koska siihen on perehdytty kohdassa org.eclipse.ui.editors. Seuraavassa kuvataan sitä, miten muokkausohjelman luokka toteutetaan.

Asiakirjan toimittajat ja asiakirjat

Muokkausohjelma avautuu työympäristössä yleensä silloin, kun käyttäjä valitsee jonkin verkkoalue-elementin (kuten tiedoston tai jonkin arkistotiedostoon tallennetun elementin) ja avaa sen. Kun muokkausohjelmaa luodaan, se liitetään muokkausohjelman syötteeseen (IEditorInput), joka määrittää muokattavat objektit.

Java-esimerkkimuokkausohjelma avautuu, kun käyttäjä avaa tiedoston, jolla on tunniste "*.jav". Tällöin muokkausohjelman syöte on IFileEditorInput.  Ympäristön tekstikehys ei tee oletuksia muokkausohjelman syötteestä. Kehys käyttää syötteen käsittelyyn IDocument-esitysmallia, jotta se voi esittää ja muokata tekstiä tehokkaasti.

Tämä tarkoittaa sitä, että esitysmallin on oltava jäljitettävissä odotetun verkkoalueen mallista (muokkausohjelman syötteestä). Vastaavuuden selvittäminen määritetään IDocumentProvider-rajapinnan avulla. Kun asiakirjan toimittajalle annetaan muokkausohjelman syöte, se palauttaa sopivan IDocument-rajapinnan.

Java-esimerkkimuokkausohjelma perii TextFileDocumentProvider-luokan, jonka on määrittänyt org.eclipse.ui.editors-luokan lisäosa. org.eclipse.ui.editors.documentProviders-laajennusta käytetään määrittämään muokkausohjelman syötteen lajien (tai tiedoston tunnisteiden) ja asiakirjan toimittajien välisiä vastaavuuksia. Muokkausohjelman lisäosa määrittää asiakirjan toimittajan seuraavasti:

   <extension
         point="org.eclipse.ui.editors.documentProviders">
<provider
            class="org.eclipse.ui.editors.text.TextFileDocumentProvider"
            inputTypes="org.eclipse.ui.IStorageEditorInput"
            id="org.eclipse.ui.editors.text.StorageDocumentProvider">
      </provider>
	</extension>

Tämän laajennuspisteen avulla lisäosat voivat rekisteröidä asiakirjan toimittajia ja liittää ne joko tiedoston tunnisteeseen tai muokkausohjelman syötteen lajiin. Koska Java-esimerkkimuokkausohjelma ei määritä omaa asiakirjan toimittajan laajennustaan, se perii yleisen asiakirjan toimittajan, joka on määritetty kaikille syötelajeille, jotka ovat IStorageEditorInput-rajapinnassa. Kun käyttäjä avaa tiedoston muokkausta varten, käyttöympäristö ohjaa oikean asiakirjan toimittajan ilmentymän luomista. Jos tiedoston tunnisteelle on rekisteröity jokin tietty asiakirjan toimittaja, kyseistä toimittajaa käytetään. Jos taas tiedoston tunnisteelle ei ole määritetty asiakirjan toimittajaa, muokkausohjelman syötteen lajia käytetään sopivan toimittajan löytämisessä.

Koska Java-esimerkkimuokkausohjelma käyttää käyttöympäristön yleistä asiakirjan toimittajaa, se voi hyödyntää kaikkia asiakirjan toimittajan ominaisuuksia, kuten tiedostojen puskurointia ja muita optimointeja.

Asiakirjan asetukset

Java-muokkausohjelma käyttää käyttöympäristön tekstimuotoisen asiakirjan toimittajaa. Seuraavassa esitellään, kuinka sen avulla voi käsitellä Java-tiedostoja käsitellä.

Laajennuksen org.eclipse.core.filebuffers.documentSetup avulla voidaan määrittää tiedoston tunnisteiden ja IDocumentSetupParticipant-rajapinnan väliset vastaavuudet. Asetusten osapuoli määrittää asiakirjalle mahdolliset erityisominaisuudet, kun asiakirja on toimitettu muokkausohjelmaan.

<extension
	id="ExampleJavaDocumentSetupParticipant"
	name="%documentSetupParticipantName"
	point="org.eclipse.core.filebuffers.documentSetup">
	<participant
		extensions="jav"
		class="org.eclipse.ui.examples.javaeditor.JavaDocumentSetupParticipant">
	</participant>
</extension>

Tämä laajennusmääritys mahdollistaa sen, että esimerkkiohjelma voi määrittää asiakirjalle Java-kohtaiset tehtävät. Mitä JavaDocumentSetupParticipant sitten tekee? Seuraavassa tarkastellaan asetusmetodin yksinkertaistettua versiota.

 	public void setup(IDocument document) {
		...
		IDocumentPartitioner partitioner= new FastPartitioner(JavaEditorExamplePlugin.getDefault().getJavaPartitionScanner(), JavaPartitionScanner.JAVA_PARTITION_TYPES);
		partitioner.connect(document);
		...
	}

Asetuskoodi määrittää osiointiobjektin.

Osiot

Osiointitoiminto IDocumentPartitioner) jakaa dokumentin ei-päällekkäisiin osioihin. Osiot (jotka ITypedRegion-rajapinta on esitellyt) ovat hyödyksi silloin, kun asiakirjan eri osia pitää käsitellä eri tavalla (esimerkiksi muotoilussa tai syntaksin korostuksessa).

Muokkausohjelmaesimerkissä asiakirja jaetaan osioihin, jotka edustavat esimerkiksi javadoc-kommentteja ja monirivisiä kommentteja. Jokaiselle osiolle määritetään sisältölaji ja sen sijainti asiakirjassa. Sijaintitietoja päivitetään sitä mukaa kuin käyttäjä muokkaa tekstiä.

Sääntöpohjainen asiakirjan osiointi

Kukin muokkausohjelma määrittää sopivan toteutuksen asiakirjan osiointitoiminnolle. Sääntöpohjaista asiakirjojen läpikäyntiä tuetaan org.eclipse.jface.text.rules-paketissa.  Sääntöpohjaisen läpikäyntitoiminnon avulla muokkausohjelma voi käyttää kehyksen FastPartitioner-luokkaa.

		IDocumentPartitioner partitioner= new FastPartitioner(JavaEditorExamplePlugin.getDefault().getJavaPartitionScanner(), JavaPartitionScanner.JAVA_PARTITION_TYPES);

RuleBasedPartitionScanner on sääntöpohjaisten läpikäyntitoimintojen yliluokka. Sen aliluokat vastaavat niiden sääntöjen luetteloinnista ja toteutuksesta, joita käytetään asiakirjan läpikäynnissä yksilöimään sanakkeita, kuten rivierottimia, tyhjää tilaa ja yleisiä malleja.  Esimerkin JavaPartitionScanner määrittää säännöt yksirivisten kommenttien, merkkivakioiden, javadocin, monirivisten kommenttien ja sanojen yksilöimiseen.  Tämä tehdään läpikäyntitoiminnon konstruktorissa:

public JavaPartitionScanner() {
	super();
	IToken javaDoc= new Token(JAVA_DOC);
	IToken comment= new Token(JAVA_MULTILINE_COMMENT);

	List rules= new ArrayList();
	// Lisää yksirivisten kommenttien sääntö.
	rules.add(new EndOfLineRule("//", Token.UNDEFINED)); 

	// Lisää merkkijonojen ja merkkivakioiden sääntö.
	rules.add(new SingleLineRule("\"", "\"", Token.UNDEFINED, '\\')); 
	rules.add(new SingleLineRule("'", "'", Token.UNDEFINED, '\\')); 

	// Lisää erikoistapaussanojen sääntö.
	rules.add(new WordPredicateRule(comment));

	// Lisää monirivisten kommenttien ja javadocin säännöt.
	rules.add(new MultiLineRule("/**", "*/", javaDoc, (char) 0, true)); 
	rules.add(new MultiLineRule("/*", "*/", comment, (char) 0, true)); 

	IPredicateRule[] result= new IPredicateRule[rules.size()];
	rules.toArray(result);
	setPredicateRules(result);
}

Lisätietoja sääntöjen määrittämisestä ja käytettävissä olevista säännöistä on org.eclipse.jface.text.rules-luokassa.  Läpikäyntitoimintoihin perehdytään uudelleen syntaksin värityksen yhteydessä.